Quick start

In Locust you define your user behaviour in Python code. You then use the locust command and (optionally) its web interface to spawn and simulate a number of those users while gathering request statistics.

Example locustfile.py

import random
from locust import HttpUser, task, between

class QuickstartUser(HttpUser):
    wait_time = between(5, 9)

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

    @task(3)
    def view_item(self):
        item_id = random.randint(1, 10000)
        self.client.get(f"/item?id={item_id}", name="/item")

    def on_start(self):
        self.client.post("/login", {"username":"foo", "password":"bar"})

Let’s break it down

import random
from locust import HttpUser, task, between

A locust file is just a normal Python module, it can import code from other files or packages.

class QuickstartUser(HttpUser):

Here we define a class for the users that we will be simulating. It inherits from HttpUser which gives each user a client attribute, which is an instance of HttpSession, that can be used to make HTTP requests to the target system that we want to load test. When a test starts, locust will create an instance of this class for every user that it simulates, and each of these users will start running within their own green gevent thread.

wait_time = between(5, 9)

Our class defines a wait_time function that will make the simulated users wait between 5 and 9 seconds after each task is executed. For more info see wait_time attribute.

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

@task(3)
def view_item(self):
    ...

We’ve also declared two tasks by decorating two methods with @task, one of which has been given a higher weight (3). When a User of this type runs it’ll pick one of either hello or view_item - with three times the chance of picking view_item - call that method and then pick a duration uniformly between 5 and 9 and just sleep for that duration. After it’s wait time it’ll pick a new task and keep repeating that.

@task(3)
def view_item(self):
    item_id = random.randint(1, 10000)
    self.client.get(f"/item?id={item_id}", name="/item")

In the view_item task we load a dynamic URL by using a query parameter that is a number picked at random between 1 and 10000. In order to not get 10k separate entries in Locust’s statistics - since the stats is grouped on the URL - we use the name parameter to group all those requests under an entry named "/item" instead.

Note that only methods decorated with @task will be called, so you can define your own internal helper methods any way you like.

def on_start(self):

Additionally we’ve declared an on_start method. A method with this name will be called for each simulated user when they start. For more info see on_start and on_stop methods.

Start Locust

Put the above code in a file named locustfile.py in your current directory and run:

$ locust

If your Locust file is located somewhere else, you can specify it using -f

$ locust -f locust_files/my_locust_file.py

Note

To see all available options type: locust --help or check Configuration

Locust’s web interface

Once you’ve started Locust using one of the above command lines, you should open up a browser and point it to http://127.0.0.1:8089. Then you should be greeted with something like this:

_images/webui-splash-screenshot.png

Fill out the form and try it out! (but note that if you dont change your locust file to match your target system you’ll mostly get error responses)

_images/webui-running-statistics.png _images/webui-running-charts.png

More options

To run Locust distributed across multiple Python processes or machines, you can start a single Locust master process with the --master command line parameter, and then any number of Locust worker processes usin the --worker command line parameter. See Running Locust distributed for more info.

To start tests directly, without using the web interface, use --headless.

Parameters can also be set through environment variables, or in a config file.