locust

Load-test "example.com" with web interface using locustfile.py

$ locust --host=[http://example.com]

$ locust --locustfile=[test_file.py] --host=[http://example.com]

$ locust --no-web --clients=[100] --hatch-rate=[1] --host=[http://example.com]

$ locust --master --host=[http://example.com]

$ locust --slave --host=[http://example.com]

$ locust --slave --master-host=[master_hostname] --host=[http://example.com]

locust [--help] [-f LOCUSTFILE] [--host HOSTNAME] [--web-host HOSTNAME] [--port PORT] [--users NUM_USERS] [--spawn-rate RATE] [--run-time TIME] [--csv FILENAME] [--headless] [--master] [--worker] [--expect-workers COUNT] [--stop-timeout SECONDS] [--skip-teardown] [--env ENV]

-f LOCUSTFILE, --locustfile LOCUSTFILE
    Specify the Python file containing your test scenarios (Locustfile).

--host HOSTNAME
    The base host (prefix) to be tested, e.g., http://localhost:8089. This sets the host attribute for HttpUser classes.

--web-host HOSTNAME
    Host for the web UI to bind to. Defaults to 127.0.0.1 (localhost).

--port PORT
    Port for the web UI to bind to. Defaults to 8089.

--users NUM_USERS
    Total number of concurrent users to simulate. Used when running in headless mode.

--spawn-rate RATE
    The rate per second at which users are spawned. Used when running in headless mode.

--run-time TIME
    Stop the test after the specified run time. E.g., 20m for 20 minutes, 3h for 3 hours. Used in headless mode.

--csv FILENAME_PREFIX
    Store results in CSV files (requests and statistics) with the given filename prefix. Used in headless mode.

--headless
    Run Locust without the web UI. Useful for automated tests in CI/CD pipelines.

--master
    Run Locust as a master node in a distributed setup. This node coordinates workers and aggregates results.

--worker
    Run Locust as a worker node in a distributed setup. This node executes user tasks and sends statistics to the master.

--expect-workers COUNT
    When running as master, wait until this many workers have connected before starting the test.

--stop-timeout SECONDS
    Time in seconds to wait for graceful stop of load tests before forcing exit. Defaults to 80 seconds.

--skip-teardown
    Do not run the teardown functions after test completion.

--help
    Show the help message and exit.

Locust is an open-source, event-based user load testing tool written in Python. It allows developers and testers to define user behavior in Python code, rather than relying on complex XML configurations or GUI-based scripting. Locust simulates thousands or millions of concurrent users against a system to identify performance bottlenecks and assess scalability.

It provides a user-friendly web interface for real-time monitoring of test progress, requests per second, response times, and error rates. Its distributed architecture enables testing at massive scale by allowing multiple worker instances to be controlled by a single master instance. This makes it highly flexible for testing various protocols, though it's most commonly used for HTTP/S web applications.

Unlike many traditional load testing tools, Locust's emphasis on Python code for test scenarios offers immense flexibility and seamless integration with existing development workflows, making it a popular choice for performance testing and capacity planning.

Locust is a Python application and is not a built-in Linux utility. It requires Python 3 and the pip package manager to be installed. Users must install it via pip install locust (or through system package managers if available) before it can be used. Its performance is influenced by the underlying Python interpreter and system resources, though it is designed to be highly efficient and scalable through its distributed execution capabilities. While primarily used for HTTP/S, testing other protocols requires custom client implementations within the Python test scripts.

Locust supports distributed load generation across multiple machines. A single 'master' node manages the test, aggregates statistics from all workers, and provides the web UI. Multiple 'worker' nodes execute the actual user simulations and send their performance metrics back to the master. This architecture allows for generating massive loads far beyond the capabilities of a single machine, making it suitable for large-scale performance testing.

Tests in Locust are defined as plain Python classes, typically inheriting from User or HttpUser. This approach allows developers to leverage the full power of Python for defining user behavior, including defining various tasks with different probabilities, sequential actions, dynamic data generation, and custom validation logic. This code-based approach provides unparalleled flexibility and allows for version controlling test scripts alongside application code.

Locust was created by Carl Groner and first released in 2011. It was developed out of a need for a more flexible and programmable load testing tool compared to existing commercial and open-source solutions of the time. Its design emphasizes simplicity and extensibility through Python code, allowing testers to define complex user behaviors and test scenarios easily. Over the years, it has gained significant popularity within the development and QA communities for its ease of use, scalability, and seamless integration with modern CI/CD pipelines. It is actively maintained and evolved by a community of contributors, continuously adding new features and improving performance.

ab(1), curl(1)