# QA Locust Writer

> Generate Locust performance tests in Python for load testing with distributed mode, custom load shapes, and real-time web UI monitoring.

- Skill: `azanir/qa-locust-writer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add azanir/qa-locust-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azanir/qa-locust-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: azanir (https://skillmd.com/u/azanir)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azanir/qa-locust-writer

---


# 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

1. **Read performance plan** — From qa-plan-creator, qa-nfr-analyst, or test case specs
2. **Define user classes** — Create `HttpUser` subclasses per user type (e.g., `ApiUser`, `WebUser`)
3. **Set task weights** — Use `@task(weight=N)` for probability distribution
4. **Generate locustfile** — Produce `locustfile.py` with user classes, tasks, wait_time
5. **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 files
- `locust.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, distributed
- `references/config.md` — CLI, locust.conf, environment variables, distributed setup
- `references/best-practices.md` — Realistic scenarios, correlation, custom shapes, CI integration

## Quality Checklist

- [ ] User classes match performance plan user types
- [ ] Task weights reflect realistic user behavior distribution
- [ ] wait_time is appropriate (avoid constant(0) unless intentional)
- [ ] No hardcoded secrets; use env vars for host, auth
- [ ] LoadTestShape tick() returns (user_count, spawn_rate) or None
- [ ] Event hooks do not block or slow down requests
- [ ] Distributed setup documented when scaling required
- [ ] Traceability to performance plan / NFR criteria

## 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 |