Locust

Enables developers to define load test scenarios as Python classes inheriting from User or HttpUser, with @task decorators specifying which methods execute and their relative weights. The framework uses Python's full expressiveness for conditional logic, loops, and state management within task definitions, avoiding XML or GUI-based test design. Task execution is scheduled by the framework's event loop, which randomly selects weighted tasks and executes them sequentially per simulated user.

Locust uses gevent's greenlet-based concurrency model to simulate thousands of concurrent users within a single process with minimal memory overhead. Each simulated user runs in its own greenlet (lightweight pseudo-thread), and the framework uses gevent's event loop to manage I/O-bound operations (HTTP requests, network calls) without blocking. This allows a single machine to generate load equivalent to tools requiring multiple processes or machines, by avoiding OS thread overhead and context-switching costs.

Locust exports test results to CSV and HTML formats via the stats system. CSV exports include per-endpoint metrics (request count, response times, failure count) and a summary row. HTML exports include charts (response time distribution, requests over time), tables with detailed metrics, and failure summaries. Exports are triggered via the web UI or command-line arguments (--csv, --html), and can be customized via event listeners to include additional data.

The UsersDispatcher component in distributed mode calculates optimal user distribution across workers using a KL-divergence (Kullback-Leibler divergence) algorithm. Given a target user count and worker capacity estimates, the dispatcher minimizes the divergence between target and actual user distribution, ensuring balanced load generation. This is more sophisticated than round-robin allocation because it accounts for worker heterogeneity (different CPU, network capacity) and adjusts distribution dynamically as workers join/leave.

Locust's User base class is protocol-agnostic; developers can subclass User and implement custom client logic for non-HTTP protocols (gRPC, WebSocket, MQTT, custom binary). Custom implementations must manually fire request_success or request_failed events to integrate with Locust's metrics system. This allows any protocol to benefit from Locust's concurrency model, statistics collection, and distributed testing infrastructure without modifying the framework.

Locust implements a master-worker distributed testing pattern using ZMQ (ZeroMQ) for inter-process communication. The master runner coordinates test execution, collects statistics from multiple worker processes/machines, and exposes a unified web UI. Workers spawn user greenlets and report request metrics back to the master via ZMQ publish-subscribe channels. The UsersDispatcher component uses a KL-divergence algorithm to calculate optimal user distribution across workers, ensuring balanced load generation even with heterogeneous worker capacity.

Locust provides a Flask-based web UI (accessible at http://localhost:8089 by default) that displays real-time request statistics, response time distributions, and failure rates. The UI allows operators to start/stop tests, adjust user count and spawn rate without restarting, and download results as CSV/HTML. The backend exposes a REST API that the React frontend consumes; the UI updates via WebSocket or polling to reflect live metrics from the runner and stats system.

Locust's RequestStats system collects detailed metrics for every request: response time, status code, request/response size, and failure reason. Statistics are aggregated per endpoint and globally, with percentile calculations (p50, p95, p99) computed incrementally to avoid storing all response times. The stats system supports custom aggregation via events (request_success, request_failed) and exports results to CSV, HTML, or JSON formats. Failure tracking includes categorization by error type (timeout, connection error, HTTP 5xx, etc.) for root-cause analysis.

Locust exposes an event system (EventHook pattern) that fires events at key lifecycle points: test_start, test_stop, request_success, request_failed, user_add, user_remove, etc. Developers can register listeners to these events to inject custom logic: logging, metrics collection, dynamic test adjustments, or integration with external systems. Events are fired synchronously from the runner/user code, allowing listeners to modify test behavior or collect supplementary data without modifying core framework code.

Locust supports load shaping via the LoadShape class, allowing developers to define custom user count and spawn rate curves over time. Built-in shapes include StagesShape (step-wise increases) and LinearShape (linear ramp). Custom shapes implement a tick() method that returns (user_count, spawn_rate) at each time step, enabling complex load profiles: gradual ramp-up, plateau, spike tests, or realistic traffic patterns. The runner polls the shape at regular intervals and adjusts user count dynamically without stopping the test.

Locust provides HttpUser base class that wraps the requests library, and FastHttpUser that uses a custom HTTP client (locust.contrib.fasthttp) optimized for high-throughput scenarios. Both clients support cookies, authentication, custom headers, and request/response inspection. The HTTP client is abstracted to allow custom protocol implementations: developers can subclass User and implement custom client logic (gRPC, WebSocket, custom binary protocols) by overriding the client attribute and firing request events manually.

Locust's main.py and argument_parser.py implement locustfile loading: the framework accepts a Python file path, imports it dynamically, and discovers User subclasses via introspection. The locustfile can define multiple User classes, each representing a different user type or scenario. The framework supports command-line options to select which User classes to run, or runs all discovered classes by default. Locustfiles can also define custom LoadShape classes and event listeners, making them self-contained test definitions.

Locust's argument_parser.py provides a comprehensive CLI with options for locustfile path, target URL, user count, spawn rate, test duration, distributed mode configuration, and output formats. The CLI supports both short and long option names, environment variable overrides, and configuration file loading. Arguments are parsed into an Options object that is passed to the Environment and runners, controlling test execution without code changes.

Locust is an open-source load testing framework that allows developers to define user behavior in Python code, enabling scalable and distributed testing of web applications and APIs under realistic traffic conditions.