Locust is an open-source, developer-friendly load testing framework that allows you to define user behavior in plain Python code. It's designed for testing web applications, APIs, and other systems, supporting hundreds of thousands of concurrent users through its event-based architecture. Locust offers a real-time web-based UI for monitoring and analysis, and is actively maintained with frequent updates (approximately every 62 days) [1, 2, 11, 19, 31]. It currently requires Python 3.10 or newer [31].
pip install locustVerified import paths — ran on the pinned version, not inferred.
This quickstart defines a `QuickstartUser` that inherits from `HttpUser` for HTTP load testing. It includes `wait_time` to simulate user think time and two tasks (`hello_world` and `view_items`) decorated with `@task` to define user actions. The `view_items` task demonstrates using the `name` parameter for grouping dynamic URLs. `on_start` and `on_stop` methods are shown for per-user setup and teardown, such as login/logout. Save this code as `locustfile.py` and run `locust` from the command line to start the web UI, or use the `--headless` option for command-line execution [2, 10, 20].
Update imports from `from locust import HttpLocust` to `from locust import HttpUser`. Similarly, `Locust` becomes `User` [25, 29].
Replace `min_wait = X` and `max_wait = Y` with `wait_time = between(X, Y)`. For custom logic, define a `wait_time` method on your `User` class [20, 27].
For requests like `self.client.get(f'/item?id={item_id}')`, add `name='/item'` (e.g., `self.client.get(f'/item?id={item_id}', name='/item')`) to group statistics under a common label [20, 21, 36].Call `self.interrupt()` within a `TaskSet` method to explicitly exit the `TaskSet` and allow the user to pick other tasks from its parent [22, 24, 26].
Ensure that Python development headers and a C compiler (e.g., build-essential on Linux, Xcode command line tools on macOS, Visual C++ Build Tools on Windows) are installed. Using `pip install --prefer-binary locust` can sometimes help by forcing the use of pre-compiled wheels if available [16, 30].
Ensure your test script is named `locustfile.py` or specify the filename using the `-f` flag when running Locust (e.g., `locust -f my_test_script.py`) [4, 9].
Always add assertions to validate the response content, not just the status code. Use Python's built-in assertion capabilities on `response.text` or `response.json()` and call `response.failure("Reason for failure")` if validation fails [34].Ensure your Python environment (e.g., virtual environment) is activated. If installed via pip, the executable might be in a local bin directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in Python installation on Windows) which needs to be added to your system's PATH. Alternatively, run Locust using `python -m locust -f your_locustfile.py`.
Run Locust from the root directory of your project, ensuring the imported module is discoverable by Python. For example, if 'your_custom_module.py' is in a 'lib' subdirectory, run `locust -f tests/locustfile.py` from the project root (where 'lib' is a sibling of 'tests'), or add the module's parent directory to `sys.path` within your locustfile: `import sys, os; sys.path.append(os.path.join(os.path.dirname(__file__), '..'))`.
For `User` or `TaskSet` classes meant to be executed, define tasks using the `@task` decorator on methods or assign a list/dictionary of tasks to the `tasks` attribute. For base classes that should not be instantiated directly by Locust, add `abstract = True` to the class definition: `class MyBaseUser(HttpUser): abstract = True`.
Ensure that any overridden `__init__` methods in your `User` or `TaskSet` classes correctly call their parent's constructor: `class MyTaskSet(TaskSet): def __init__(self, parent): super().__init__(parent) # ... your custom initialization`.
Define the target host within your `HttpUser` class: `class MyUser(HttpUser): host = 'http://localhost:8080'` or provide it via the command line when starting Locust: `locust -f your_locustfile.py --host http://localhost:8080`.