Agent Wranglers

STK-97Recommended Open source

Use Locust for load tests

Write load tests as Locust scripts, run them headless against staging and fail the run when the budget is passed.

By Agent Wranglers. Updated .

How to do it

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 says. Reuse the same script to hold normal load for hours to find leaks. 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.

Examples

Python example

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

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

How to check

The load test runs in CI against staging. It exits non-zero when the 95th percentile or the error rate passes the budget.

For agents: this playbook is free to use under CC 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.