Welcome to the Locust Tutorial

If you need help:

Locust documentation

Slack channel

1. Set up Locust

Option 1: Run on Locust Cloud (no setup needed)

Option 2: Run locally

> pip install locust
...
> locust -V
locust 2.42.1 from /Users/.../locust (Python 3.12.2)

Option 3: Clone this repo and use uv to run in an isolated environment:

> git clone https://github.com/locustcloud/workshop.git
...
> cd workshop
> uv run locust -V
locust 2.42.1 from /Users/.../.venv/lib/python3.12/site-packages/locust (Python 3.12.7)

2. Creating your first test

Open locustfile.py (locally or in the hosted test editor)

from locust import HttpUser, task

class MyUser(HttpUser):
    @task
    def t(self):
        self.client.get("/")
        self.client.get("/product/42")

3. Running your first test

Now, run your first test against a mock web shop hosted by us:

> locust --host https://mock-test-target.eu-north-1.locust.cloud
[2024-11-10 15:59:26,604] lars-mbp/INFO/locust.main: Starting Locust 2.42.1
[2024-11-10 15:59:26,608] lars-mbp/INFO/locust.main: Starting web interface at http://0.0.0.0:8089

Open the web ui and try running it! Just use a single user for now to not spam the service.

4. Use regular programming constructs in your test

import time
from locust import HttpUser, task

class MyUser(HttpUser):
    @task
    def t(self):
        self.client.get("/")
        for i in range(5):
            time.sleep(1)
            self.client.get(f"/product/{i}")

• It is probably fairly obvious what this does, but go ahead and try it out anyway!

5. Use the debugger to run a single user

from locust import HttpUser, run_single_user, task

class MyUser(HttpUser):
    @task
    def t(self):
        self.client.get("/")
        for i in range(5):
            response = self.client.get(f"/product/{i}")
        self.client.get("/this_does_not_exist")

if __name__ == "__main__":
    run_single_user(MyUser)

If you're in VSCode, just launch the "Run current file" configuration. Also check out the Locust VSCode Extension. You'll need to set "gevent": true in your launch.json if you didn't clone this repo, otherwise vscode will give an error talking about It seems that the gevent monkey-patching is being used. ...

Then you can:

• Try setting a breakpoint & examine the response object in real time

6. Use the catch_response flag to validate responses

from locust import HttpUser, run_single_user, task

class MyUser(HttpUser):
    @task
    def t(self):
        with self.client.post(
            "/authenticate", json={"username": "foo", "password": "bar"}, catch_response=True
        ) as response:
            if err := response.json().get("error"):
                response.failure(err)

if __name__ == "__main__":
    run_single_user(MyUser)

• Try running this with a changed password and examine the results.

7. Use Locust Cloud from the terminal

Locust Cloud tests can be executed in the same way as local load tests, by just adding the --cloud flag.

Register for Locust Cloud if you haven't already. When you are done, log in to the service:

locust --cloud --login

And then run your first test.

locust --cloud --host https://mock-test-target.eu-north-1.locust.cloud --users 100

Run a more advanced test against the mock server:

locust --cloud --host https://mock-test-target.eu-north-1.locust.cloud -f locustfile_advanced.py --users 100 --spawn-rate 5

• Analyze the results
  • Peak throughput that the mock can handle?
  • Which requests are slow?
  • Are there any periodic variations?
  • ...

Where do we go from here?

• Locust documentation

• Run Locust in your own Kubernetes cluster?

• Check out the Locust Cloud blog:

1. Breaking your website for fun and profit

2. Smoke, stress, spike, soak, and recovery: 5 essential load test profiles

3. Closed vs Open Workload Models in Load Testing

4. Garbage In, Garbage Out: Your Load Test Results Are Only as Reliable as Your Test Environment

5. 16 ways to improve your load test scenarios