Locust review: load testing tutorial, pros and cons

Locust creates one instance of your User class for every simulated user and runs each in its own greenlet, a lightweight coroutine managed by gevent. gevent patches the standard library so that network calls and time.sleep yield to other greenlets instead of blocking, which is why a task can be written as plain sequential code and still run thousands of users in one process. The cost of that design shows up when code does not yield: a CPU-heavy loop, or a database or message client that does its own blocking I/O outside gevent’s patches, stops every user in the process until it returns. The docs say this plainly for custom clients: use a gevent-friendly library, or you are effectively limited to one user per worker.

Python cannot fully use more than one core per process, so a single Locust process saturates one core and then starts under-reporting what the system can do. Locust logs a CPU warning when that happens. The answer is built in: one master process coordinates and aggregates statistics, and worker processes run the users and report back over ZeroMQ, on port 5557 by default. The master runs no users itself. On one machine, --processes 4 forks a master and four workers, and --processes -1 starts one worker per logical core. Across machines, start a master and point workers at it with --master-host; workers can even fetch the locustfile from the master with -f -.

Each user repeatedly picks a task at random, weighted by the number given to the @task decorator, runs it to completion, then sleeps for its wait_time before picking again. Requests inside a task run in order, so a task is a natural unit for one user journey step. User classes can be weighted against each other, or pinned to an exact count with fixed_count. Wait time is applied after a task, not between requests, and it is what turns users into load: between and constant model think time, constant_throughput and constant_pacing cap how often a task runs, and poisson, added in 2.46.6, samples gaps from an exponential distribution so arrivals bunch and spread like real traffic.

Every request made through self.client fires a request event carrying its name, response time, length and any exception. Locust aggregates these by request name into the table you see in the web UI and console, with percentiles, failure counts and a history used for the charts. In distributed mode workers send their statistics to the master, which merges them. Because the event is the unit, anything that fires one is measured the same way: the HTTP clients do it for you, and a custom client for gRPC, MQTT or a database only needs to fire the event with a name and timing. It also explains why unique URLs must be grouped with name, or the table grows a row per URL.

A locustfile is an ordinary Python module, and the working directory is on sys.path, so treat a load test suite like any small Python package. Keep shared code such as authentication, test data loading and custom clients in a common package, one locustfile per system or journey under a locustfiles folder, and dependencies pinned in requirements.txt. Put run settings in locust.conf or a [tool.locust] section of pyproject.toml rather than long command lines, so the default run is reproducible and reviewable. Settings are applied in a fixed order: pyproject.toml, then locust.conf, then a --config file, then LOCUST_ environment variables, then command-line arguments, so CI can override the host or duration without editing the file. Use @tag on tasks and --tags to run a smoke subset from the same code.

By default a headless run exits with code 1 if any request failed, and --exit-code-on-error changes that code. Nothing fails a run for being slow, which is the usual reason a performance gate exists. The documented pattern is a listener on the quitting event that inspects the aggregated statistics and sets environment.process_exit_code. Keep it in a separate module, such as common/thresholds.py, and import it from every locustfile so every run applies the same rules. Choose thresholds from a baseline run against the same environment, and prefer percentiles to averages: an average hides the slow tail that users notice. Check them per request name too, using environment.stats.get with the name and method, when one endpoint matters more than the total.

Run load tests on a schedule or on demand against a dedicated test environment, not on every pull request against shared staging, and never against a system you do not own. The job below installs dependencies, runs four worker processes with a time limit, and keeps the CSV and HTML output whether the thresholds pass or not. PYTHONUNBUFFERED makes the console output appear as it happens, and a job timeout stops a hung run from holding a runner. A hosted runner is small, so treat it as a regression check at modest load: for capacity testing, run workers on machines sized for the job, or on Kubernetes with the operator, and keep the same locustfile.

Watch the generators as closely as the system under test. If Locust logs that CPU usage is above 90 percent, its numbers are no longer trustworthy. In order: switch hot paths to FastHttpUser, which the docs describe as using significantly less CPU than HttpUser; add processes up to the core count; then add machines. For multiple machines, start the master with --master and --expect-workers so a headless run waits for every worker, and start workers with --worker --master-host. The official Docker image and its Compose example make a master plus scaled workers a one-line command, and the Kubernetes operator manages master and worker jobs as a custom resource. Keep generators close to the target network-wise, and spread them if flood protection or a load balancer pins traffic from few addresses to few instances.

Users and spawn rate describe a ramp to a plateau. For anything else, such as a step test that holds each level long enough to read, a spike, or a soak with a warm-up, write a LoadTestShape. Locust uses it automatically when it finds one in the loaded files, calls tick about once a second, and stops the test when tick returns None. Keeping shapes in separate files means one locustfile serves several profiles: locust -f locustfile.py,step_shape.py. If user start-up is slow, for example a login per user, get_current_user_count lets a stage wait until the previous level is actually reached before moving on.