---
title: "Use Locust for load tests · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/testing-and-code-quality/locust
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use Locust for load tests

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: STK-97
- Level: Recommended
- Chapter: [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality)
- Rule: Write load tests as Locust scripts, run them headless against staging and fail the run when the budget is passed.
- Cost: Open source. MIT licence, free to run on your own machines.
- How: Locust 1.0 came out on 16 May 2020, and 2.46.7 shipped on 4 October 2026. It had about 2.3 million weekly PyPI downloads in October 2026, and its image about 285 million Docker Hub pulls. Scripts are plain Python, but they load a server written in any language. Run it with `--headless`, a user count and a run time, so CI gets an exit code. Set the budget and the steps as [Test load against a budget](https://agentwranglers.se/playbook/testing/non-functional-tests/load-tests) says. Reuse the same script to [hold normal load for hours to find leaks](https://agentwranglers.se/playbook/testing/non-functional-tests/soak-tests). Choose something else when your team writes no Python. k6 takes JavaScript scripts, but its 1.0 came out on 6 May 2025. Record it as an exception to [Pick software proven in production for five years](https://agentwranglers.se/playbook/stack/how-to-choose/proven-for-five-years).
- Check: The load test runs in CI against staging. It exits non-zero when the 95th percentile or the error rate passes the budget.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Python example

```python
from locust import HttpUser, between, events, task

MAX_P95_MS = 500
MAX_FAILURE_RATIO = 0.01

class Shopper(HttpUser):
    wait_time = between(1, 3)

    @task
    def browse(self):
        self.client.get("/products")

@events.quitting.add_listener
def enforce_budget(environment, **_):
    total = environment.stats.total
    if total.fail_ratio > MAX_FAILURE_RATIO or total.get_response_time_percentile(0.95) > MAX_P95_MS:
        environment.process_exit_code = 1
```

### Shell example

```sh
locust -f loadtest.py --headless --users 200 --spawn-rate 20 --run-time 5m --host https://staging.example.com
```

## Related rules

- [Test load against a budget](https://agentwranglers.se/playbook/testing/non-functional-tests/load-tests) in Testing
- [Hold normal load for hours to find leaks](https://agentwranglers.se/playbook/testing/non-functional-tests/soak-tests) in Testing
- [Pick software proven in production for five years](https://agentwranglers.se/playbook/stack/how-to-choose/proven-for-five-years) in Software choices

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/stack/testing-and-code-quality/locust">Agent Wranglers software choices playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Use TruffleHog to find leaked secrets](https://agentwranglers.se/playbook/stack/testing-and-code-quality/secret-scanner)
- Next: [Use Spectral to lint the OpenAPI contract](https://agentwranglers.se/playbook/stack/testing-and-code-quality/spectral)
- [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality)