Locust

Enables defining load test scenarios as Python classes (User, HttpUser) where test logic is expressed through @task decorators and methods rather than GUI or XML configuration. The framework uses Python's full expressiveness for conditional logic, loops, and state management within user behavior definitions. Each User class instance runs in its own gevent greenlet, allowing thousands of concurrent users to be simulated with minimal memory overhead through event-based concurrency rather than OS threads.

Implements a master-worker pattern using ZMQ (ZeroMQ) for inter-process communication that distributes user load across multiple machines. The MasterRunner coordinates test execution, receives statistics from WorkerRunner instances, and aggregates metrics in real-time. The UsersDispatcher component uses a KL-divergence algorithm to calculate optimal user distribution across workers, ensuring balanced load distribution even with heterogeneous worker capacities. Workers connect to the master via ZMQ sockets and report per-request statistics that are aggregated into global RequestStats.

Uses gevent's greenlet model to simulate thousands of concurrent users in a single process with minimal memory overhead. Each simulated user runs in its own greenlet (lightweight pseudo-thread), allowing context switching without OS thread creation. The framework patches standard library I/O operations (socket, select, etc.) to be non-blocking, enabling greenlets to yield control when waiting for I/O. This approach achieves 10-100x better concurrency than thread-based approaches, allowing a single machine to simulate 10k+ concurrent users. The runner spawns greenlets at the configured spawn rate and manages their lifecycle.

Implements task execution through the @task decorator with optional weight parameter, allowing developers to define multiple tasks with different execution probabilities. The framework randomly selects tasks based on their weights (e.g., @task(3) for 3x likelihood vs @task(1) for 1x likelihood), simulating realistic user behavior where some actions are more common than others. Tasks are executed in a loop within each user's greenlet, with optional wait times between tasks. This enables modeling complex user journeys without explicit state machines.

Provides a Flask-based REST API backend with a React frontend that displays live load test metrics, allows starting/stopping tests, and adjusts user count during execution. The web UI connects to the Environment's event system to receive real-time updates on request completion, user spawning, and test state changes. The backend serves JSON endpoints for metrics aggregation, and the React frontend polls these endpoints to update charts showing response times, throughput, error rates, and per-endpoint statistics. Users can control test execution (start, stop, pause) and modify load parameters (spawn rate, user count) through the UI without restarting the test.

Implements an event-driven architecture using EventHook pattern where custom code can subscribe to test lifecycle events (test_start, test_stop, request_success, request_failure, user_add, user_remove, etc.). Hooks are registered on the Environment object and fired at specific points in the test execution lifecycle. This enables users to inject custom logic for setup/teardown, request validation, metrics collection, and dynamic behavior without modifying core framework code. Events are fired synchronously from the runner and user greenlets, allowing hooks to modify test state or collect custom metrics.

Collects detailed per-request statistics through the RequestStats system, tracking response times, status codes, error messages, and request counts. Statistics are aggregated at multiple levels: per-endpoint (name), per-user-class, and globally. The framework calculates percentiles (50th, 66th, 75th, 90th, 95th, 99th) of response times using a histogram-based approach, enabling identification of tail latencies. Statistics are updated in real-time as requests complete and can be exported to CSV or HTML reports. The StatsEntry class maintains running statistics without storing individual request data, enabling memory-efficient collection of millions of requests.

Provides two HTTP client implementations: standard HttpUser using the requests library for compatibility and ease of use, and FastHttpUser using the httpx library with connection pooling and keep-alive for higher throughput. Both clients are wrapped in a statistics-collecting layer that automatically records response times, status codes, and errors. The HTTP client abstraction allows users to make requests via simple method calls (get, post, etc.) with automatic exception handling and metric collection. FastHttpUser achieves 2-3x higher throughput than HttpUser by using httpx's async-compatible connection pooling and reducing per-request overhead.

Implements load shaping through the LoadShape interface, allowing tests to define custom user count and spawn rate over time. The framework supports predefined shapes (StepLoadShape for gradual ramp-up, ConstantLoadShape for steady-state) and custom shapes via Python code. The UsersDispatcher component distributes target user counts across workers using a KL-divergence algorithm that minimizes the difference between target and actual distribution. Spawn rate (users per second) is controlled by the runner, which spawns greenlets at the configured rate. This enables realistic load profiles (ramp-up, plateau, ramp-down) without manual intervention.

Provides a User base class that can be extended to support custom protocols beyond HTTP. Users implement custom client logic by overriding the on_start() method to initialize connections and defining @task methods that use custom client libraries (gRPC, WebSocket, MQTT, etc.). The framework handles greenlet-based concurrency and statistics collection; custom protocol implementations are responsible for their own request/response handling. Examples include gRPC clients, WebSocket connections, and database query clients. This enables load testing of any network-based service that can be accessed from Python.

Exports test results to CSV and HTML formats at test completion or on-demand. CSV exports include per-endpoint statistics (response times, percentiles, error rates, request counts) in tabular format suitable for parsing and comparison. HTML reports include interactive charts showing response time distributions, throughput over time, and error rate trends. The reporting system can compare current test results with previous runs by parsing historical CSV files, enabling trend analysis and regression detection. Reports are generated from in-memory RequestStats objects and can be customized via command-line options.

Supports running load tests entirely from command-line without the web UI, controlled via CLI arguments and environment variables. The argument_parser module processes flags like --users, --spawn-rate, --run-time, --host, etc., enabling CI/CD integration without requiring browser interaction. Tests can be started, stopped, and monitored programmatically via the Environment and Runner APIs, allowing integration with orchestration tools and monitoring systems. Exit codes indicate test success/failure, enabling automated test result validation in pipelines.