Locust

Locust is an open source load testing tool written in Python. You define user behaviour in plain Python code and Locust can simulate millions of simultaneous users to stress-test your web application or API. It includes a real-time web UI to monitor requests per second, response times, and failure rates while a test is running.

Getting Started

Launch a Locust instance from the OSC dashboard.

Prerequisites

  • An OSC account. Sign up here.
  • A locustfile.py hosted at a publicly accessible URL (e.g. a raw GitHub URL). This file defines the load test scenarios.

Write a Locust File

Create a locustfile.py that describes your test scenario:

from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)

    @task
    def index(self):
        self.client.get("/")

    @task(3)
    def about(self):
        self.client.get("/about")

Push this file to a public GitHub repository and copy the raw URL (e.g. https://raw.githubusercontent.com/myorg/myrepo/main/locustfile.py).

Create a Locust Instance

Using the OSC dashboard

  1. Go to Locust on OSC.
  2. Click Create instance.
  3. Fill in:
  4. Name — alphanumeric identifier for the instance
  5. LocustfileUrl — raw URL to your locustfile.py
  6. Click Create.

Using the CLI

osc create locustio-locust myloadtest \
  -o LocustfileUrl="https://raw.githubusercontent.com/myorg/myrepo/main/locustfile.py"

Running a Test

  1. Open the instance URL in your browser. The Locust web UI appears.
  2. Enter the Host (base URL of the system under test, e.g. https://api.example.com).
  3. Set the Number of users and Spawn rate.
  4. Click Start swarming.
  5. Monitor requests/sec, response times, and failures in real time on the Charts and Statistics tabs.
  6. Click Stop when the test is complete.

Resources