Locust

Warnings

• breaking The primary user classes `Locust` and `HttpLocust` were renamed to `User` and `HttpUser` respectively in version 2.0.0. Older scripts using `HttpLocust` will fail.
  Fix: Update imports from `from locust import HttpLocust` to `from locust import HttpUser`. Similarly, `Locust` becomes `User` [25, 29].
• deprecated The `min_wait`, `max_wait`, and `wait_function` attributes on `User` classes are deprecated. Use the `wait_time` attribute instead, which should be set to a function (like `between`, `constant`, `constant_throughput`) or a custom callable [27].
  Fix: 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].
• gotcha When testing URLs with dynamic components (e.g., `/item?id=1`, `/item?id=2`), Locust will, by default, record each unique URL separately in statistics. This can lead to an explosion of metrics and make analysis difficult. To aggregate these, use the `name` parameter in your client request.
  Fix: 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].
• gotcha The `TaskSet` class (an advanced feature for grouping tasks) does not automatically return control to its parent `User` or `TaskSet`. If not explicitly interrupted, a user entering a `TaskSet` will remain executing its tasks indefinitely.
  Fix: 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].
• gotcha Locust has dependencies like `gevent` and `geventhttpclient` which are compiled from C code. This can lead to installation failures if the necessary build tools (e.g., C compiler, Python development headers) are not present on the system.
  Fix: 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].
• gotcha By default, Locust looks for a test script named `locustfile.py`. If your script has a different name, or is not in the current directory, Locust will not find it.
  Fix: 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].
• gotcha Only checking HTTP status codes (e.g., 200 OK) is often insufficient for validating successful user flows. A server might return 200 OK with an error message in the body, or simply not return the expected content.
  Fix: 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].

Install

• pip install locust Standard installation

Imports

• HttpUser

  from locust import HttpUser

  `HttpLocust` was renamed to `HttpUser` in version 2.0.0 [25, 29].
• task

  from locust import task

  Used as a decorator for methods within `User` or `HttpUser` classes to define user actions [20].
• between

  from locust import between

  A built-in wait_time function for simulating realistic user think times [20].
• User

  from locust import User

  The base `Locust` class was renamed to `User` in version 2.0.0 [25, 29]. `HttpUser` is typically used for web testing [20, 21].

Quickstart

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].

import os
from locust import HttpUser, task, between

class QuickstartUser(HttpUser):
    wait_time = between(1, 2)  # Users wait between 1 and 2 seconds after each task
    host = os.environ.get('LOCUST_TARGET_HOST', 'http://localhost:8089') # Default host for testing

    def on_start(self):
        """ on_start is called when a Locust user starts running """
        # Example: Simulating a login if required by the target system
        # self.client.post("/login", json={"username":"test_user", "password":"test_password"})
        print(f"Starting user on host: {self.host}")

    @task
    def hello_world(self):
        self.client.get("/hello")
        self.client.get("/world")

    @task(3)
    def view_items(self):
        # Simulate viewing items with dynamic IDs, using 'name' to aggregate stats
        for item_id in range(10):
            self.client.get(f"/item?id={item_id}", name="/item")

    def on_stop(self):
        """ on_stop is called when a Locust user stops running """
        # Example: Simulating a logout
        # self.client.post("/logout")
        print("Stopping user.")

# To run this, save as `locustfile.py` and execute `locust` from the terminal.
# Then open your browser to http://localhost:8089 to use the web UI.
# Alternatively, run headless: `locust -f locustfile.py --headless --users 10 --spawn-rate 5 -H http://your-target-host.com`