QA Locust Writer
Purpose
Write Locust performance tests from test case specifications and performance plans. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer) and performance plans (from qa-plan-creator, qa-nfr-analyst) into executable Locust load tests with distributed mode, custom load shapes, real-time web UI, and event hooks.
Trigger Phrases
- "Write Locust tests for [API/endpoint]"
- "Generate Locust load tests from performance plan"
- "Create Locust stress tests for [service]"
- "Add Locust tests with custom load shape"
- "Locust distributed load test for [URL]"
- "Python load tests with Locust"
- "Locust soak test for [endpoint]"
- "Spike test with Locust"
- "Locust tests with web UI"
Key Features
| Feature |
Description |
| HttpUser class |
Base class for HTTP-based load; self.client for requests |
| TaskSets |
Group related tasks; nest for complex flows |
| @task decorator |
Define user behaviors with optional weight |
| wait_time |
between, constant, constant_pacing for think time |
| Custom load shapes |
LoadTestShape for ramp, spike, soak, custom profiles |
| Event hooks |
events.request, events.init, events.test_start/stop |
| Distributed mode |
Master/worker for scaling across machines |
| Real-time web UI |
Built-in dashboard at http://localhost:8089 |
Test Types
| Type |
Description |
Use Case |
| Load |
Steady load to verify baseline capacity |
Baseline, capacity planning |
| Stress |
Increase load until failure |
Find breaking point |
| Spike |
Sudden burst of traffic |
Black Friday, flash sales |
| Soak |
Sustained load over hours |
Memory leaks, stability |
| Custom shapes |
User-defined profile via LoadTestShape |
Complex scenarios |
Workflow
- Read performance plan — From qa-plan-creator, qa-nfr-analyst, or test case specs
- Define user classes — Create
HttpUser subclasses per user type (e.g., ApiUser, WebUser)
- Set task weights — Use
@task(weight=N) for probability distribution
- Generate locustfile — Produce
locustfile.py with user classes, tasks, wait_time
- Configure — Add
locust.conf or CLI args; document distributed setup
Context7 MCP
Use Context7 MCP for Locust documentation when:
- HttpUser, TaskSet, or LoadTestShape APIs need verification
- Event hooks or distributed mode options are uncertain
- wait_time, task weights, or configuration syntax require clarification
Key Patterns
| Pattern |
Usage |
class MyUser(HttpUser) |
Define user class; inherits self.client |
@task / @task(weight=3) |
Task method; weight = relative probability |
wait_time = between(1, 3) |
Random wait between tasks (seconds) |
wait_time = constant(2) |
Fixed wait |
wait_time = constant_pacing(1) |
Maintain ~1 req/sec per user |
self.client.get(url) / self.client.post(url) |
HTTP requests |
on_start / on_stop |
Setup/teardown per user instance |
LoadTestShape |
Custom load profile; override tick() |
events.request.add_listener |
Request-level hooks (success/failure) |
See references/patterns.md for user classes, task sets, load shapes, events, distributed.
Distributed Setup
| Role |
Command |
Purpose |
| Master |
locust -f locustfile.py --master |
Coordinates workers, aggregates stats |
| Worker |
locust -f locustfile.py --worker --master-host=<master-ip> |
Runs load |
| Expect workers |
--expect-workers=4 |
Master waits for N workers before starting |
Configuration
- CLI args —
--host, --users, --spawn-rate, --run-time, --headless
- locust.conf — Same options in config file
- Environment variables —
LOCUST_HOST, LOCUST_USERS, etc.
See references/config.md for full configuration guide.
File Naming
locustfile.py — Default; or locustfile_{service}.py for multiple fileslocust.conf — Optional configuration- Place in
tests/load/ or project root per convention
Scope
Can do (autonomous):
- Generate Locust load tests from performance plans and test cases
- Define HttpUser classes, tasks, task weights, wait_time
- Implement LoadTestShape for load, stress, spike, soak profiles
- Add event hooks for request logging, custom metrics
- Document distributed setup (master/worker)
- Configure locust.conf, CLI args, env vars
- Use Context7 MCP for Locust docs
Cannot do (requires confirmation):
- Change production API implementation
- Add dependencies not in requirements.txt/pyproject.toml
- Override project config without approval
- Target production URLs without explicit request
Will not do (out of scope):
- Execute load tests (user runs
locust)
- Write E2E browser tests (use qa-playwright-ts-writer)
- Modify CI/CD pipelines
- Bypass rate limits or ToS
References
references/patterns.md — User classes, task sets, load shapes, events, distributedreferences/config.md — CLI, locust.conf, environment variables, distributed setupreferences/best-practices.md — Realistic scenarios, correlation, custom shapes, CI integration
Quality Checklist
Troubleshooting
| Symptom |
Likely Cause |
Fix |
| Connection refused |
Wrong host or service down |
Verify --host; ensure target is reachable |
| Low RPS despite many users |
wait_time too high or blocking |
Reduce wait_time; avoid sync I/O in tasks |
| Workers not connecting |
Firewall, wrong master host |
Check --master-host; open port 5557 |
| Memory growth in soak test |
Leaks in app or test code |
Profile app; avoid accumulating state in tasks |
| Inconsistent results |
Shared state, non-determinism |
Use per-user state; avoid global variables |
| Task distribution wrong |
Incorrect weights |
Verify @task(weight=N) sums; check task selection |
| Load shape not applied |
LoadTestShape not used |
Pass --class-picker or ensure shape in locustfile |
1---2name: qa-locust-writer3description: Generate Locust performance tests in Python for load testing with distributed mode, custom load shapes, and real-time web UI monitoring.4---56# QA Locust Writer78## Purpose910Write Locust performance tests from test case specifications and performance plans. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer) and performance plans (from qa-plan-creator, qa-nfr-analyst) into executable Locust load tests with distributed mode, custom load shapes, real-time web UI, and event hooks.1112## Trigger Phrases1314- "Write Locust tests for [API/endpoint]"15- "Generate Locust load tests from performance plan"16- "Create Locust stress tests for [service]"17- "Add Locust tests with custom load shape"18- "Locust distributed load test for [URL]"19- "Python load tests with Locust"20- "Locust soak test for [endpoint]"21- "Spike test with Locust"22- "Locust tests with web UI"2324## Key Features2526| Feature | Description |27| ------- | ----------- |28| **HttpUser class** | Base class for HTTP-based load; `self.client` for requests |29| **TaskSets** | Group related tasks; nest for complex flows |30| **@task decorator** | Define user behaviors with optional weight |31| **wait_time** | `between`, `constant`, `constant_pacing` for think time |32| **Custom load shapes** | `LoadTestShape` for ramp, spike, soak, custom profiles |33| **Event hooks** | `events.request`, `events.init`, `events.test_start/stop` |34| **Distributed mode** | Master/worker for scaling across machines |35| **Real-time web UI** | Built-in dashboard at `http://localhost:8089` |3637## Test Types3839| Type | Description | Use Case |40| ---- | ----------- | -------- |41| **Load** | Steady load to verify baseline capacity | Baseline, capacity planning |42| **Stress** | Increase load until failure | Find breaking point |43| **Spike** | Sudden burst of traffic | Black Friday, flash sales |44| **Soak** | Sustained load over hours | Memory leaks, stability |45| **Custom shapes** | User-defined profile via LoadTestShape | Complex scenarios |4647## Workflow48491. **Read performance plan** — From qa-plan-creator, qa-nfr-analyst, or test case specs502. **Define user classes** — Create `HttpUser` subclasses per user type (e.g., `ApiUser`, `WebUser`)513. **Set task weights** — Use `@task(weight=N)` for probability distribution524. **Generate locustfile** — Produce `locustfile.py` with user classes, tasks, wait_time535. **Configure** — Add `locust.conf` or CLI args; document distributed setup5455## Context7 MCP5657Use **Context7 MCP** for Locust documentation when:58- HttpUser, TaskSet, or LoadTestShape APIs need verification59- Event hooks or distributed mode options are uncertain60- wait_time, task weights, or configuration syntax require clarification6162## Key Patterns6364| Pattern | Usage |65| ------- | ----- |66| `class MyUser(HttpUser)` | Define user class; inherits `self.client` |67| `@task` / `@task(weight=3)` | Task method; weight = relative probability |68| `wait_time = between(1, 3)` | Random wait between tasks (seconds) |69| `wait_time = constant(2)` | Fixed wait |70| `wait_time = constant_pacing(1)` | Maintain ~1 req/sec per user |71| `self.client.get(url)` / `self.client.post(url)` | HTTP requests |72| `on_start` / `on_stop` | Setup/teardown per user instance |73| `LoadTestShape` | Custom load profile; override `tick()` |74| `events.request.add_listener` | Request-level hooks (success/failure) |7576See `references/patterns.md` for user classes, task sets, load shapes, events, distributed.7778## Distributed Setup7980| Role | Command | Purpose |81| ---- | ------- | ------- |82| **Master** | `locust -f locustfile.py --master` | Coordinates workers, aggregates stats |83| **Worker** | `locust -f locustfile.py --worker --master-host=<master-ip>` | Runs load |84| **Expect workers** | `--expect-workers=4` | Master waits for N workers before starting |8586## Configuration8788- **CLI args** — `--host`, `--users`, `--spawn-rate`, `--run-time`, `--headless`89- **locust.conf** — Same options in config file90- **Environment variables** — `LOCUST_HOST`, `LOCUST_USERS`, etc.9192See `references/config.md` for full configuration guide.9394## File Naming9596- `locustfile.py` — Default; or `locustfile_{service}.py` for multiple files97- `locust.conf` — Optional configuration98- Place in `tests/load/` or project root per convention99100## Scope101102**Can do (autonomous):**103- Generate Locust load tests from performance plans and test cases104- Define HttpUser classes, tasks, task weights, wait_time105- Implement LoadTestShape for load, stress, spike, soak profiles106- Add event hooks for request logging, custom metrics107- Document distributed setup (master/worker)108- Configure locust.conf, CLI args, env vars109- Use Context7 MCP for Locust docs110111**Cannot do (requires confirmation):**112- Change production API implementation113- Add dependencies not in requirements.txt/pyproject.toml114- Override project config without approval115- Target production URLs without explicit request116117**Will not do (out of scope):**118- Execute load tests (user runs `locust`)119- Write E2E browser tests (use qa-playwright-ts-writer)120- Modify CI/CD pipelines121- Bypass rate limits or ToS122123## References124125- `references/patterns.md` — User classes, task sets, load shapes, events, distributed126- `references/config.md` — CLI, locust.conf, environment variables, distributed setup127- `references/best-practices.md` — Realistic scenarios, correlation, custom shapes, CI integration128129## Quality Checklist130131- [ ] User classes match performance plan user types132- [ ] Task weights reflect realistic user behavior distribution133- [ ] wait_time is appropriate (avoid constant(0) unless intentional)134- [ ] No hardcoded secrets; use env vars for host, auth135- [ ] LoadTestShape tick() returns (user_count, spawn_rate) or None136- [ ] Event hooks do not block or slow down requests137- [ ] Distributed setup documented when scaling required138- [ ] Traceability to performance plan / NFR criteria139140## Troubleshooting141142| Symptom | Likely Cause | Fix |143| ------- | ------------ | --- |144| Connection refused | Wrong host or service down | Verify `--host`; ensure target is reachable |145| Low RPS despite many users | wait_time too high or blocking | Reduce wait_time; avoid sync I/O in tasks |146| Workers not connecting | Firewall, wrong master host | Check `--master-host`; open port 5557 |147| Memory growth in soak test | Leaks in app or test code | Profile app; avoid accumulating state in tasks |148| Inconsistent results | Shared state, non-determinism | Use per-user state; avoid global variables |149| Task distribution wrong | Incorrect weights | Verify @task(weight=N) sums; check task selection |150| Load shape not applied | LoadTestShape not used | Pass `--class-picker` or ensure shape in locustfile |
azanir