Quick start

Example locustfile.py

When using Locust you define the behaviour of users in Python code, and then you have the ability to simulate any number of those users while gathering request statistic. The entrypoint for defining the user behaviour is the locustfile.py.

Note

The locustfile.py is a normal Python file that will get imported by Locust. Within it you can import modules just as you would in any python code.

The file can be named something else and specified with the -f flag to the locust command.

Below is a quick little example of a simple locustfile.py:

import random
from locust import HttpLocust, task, between

class WebsiteUser(HttpLocust):
    wait_time = between(5, 9)

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

    @task(1)
    def view_post(self):
        post_id = random.randint(1, 10000)
        self.client.get("/post?id=%i" % post_id, name="/post?id=[post-id]")

    def on_start(self):
        """ on_start is called when a Locust start before any task is scheduled """
        self.login()

    def login(self):
        self.client.post("/login", {"username":"ellen_key", "password":"education"})

Let’s break it down:

class WebsiteUser(HttpLocust):

Here we define a class for the users that we will be simulating. It inherits from HttpLocust 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.

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

@task(1)
def view_post(self):
    ...

We’ve also declared two tasks by decorating two methods with @task and given them different weights (2 and 1). When a simulated user of this type runs it’ll pick one of either index or view_post - with twice the chance of picking index - 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.

post_id = random.randint(1, 10000)
self.client.get("/post?id=%i" % post_id, name="/post?id=[post-id]")

In the view_post 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 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 "/post?id=[post-id]" instead.

def on_start(self):

Additionally we’ve declared a 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

To run Locust with the above Locust file, if it was named locustfile.py and located in the current working directory, we could run:

$ locust

If the Locust file is located under a subdirectory and/or named different than locustfile.py, specify it using -f:

$ locust -f locust_files/my_locust_file.py

To run Locust distributed across multiple processes we would start a master process by specifying --master:

$ locust -f locust_files/my_locust_file.py --master

and then we would start an arbitrary number of worker processes:

$ locust -f locust_files/my_locust_file.py --worker

If we want to run Locust distributed on multiple machines we would also have to specify the master host when starting the workers (this is not needed when running Locust distributed on a single machine, since the master host defaults to 127.0.0.1):

$ locust -f locust_files/my_locust_file.py --worker --master-host=192.168.0.100

Parameters can also be set in a config file (locust.conf or ~/.locust.conf) or in env vars, prefixed by LOCUST_

For example: (this will do the same thing as the previous command)

$ LOCUST_MASTER_HOST=192.168.0.100 locust

Note

To see all available options type: locust --help

Open up 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 (if you are running Locust locally). Then you should be greeted with something like this:

_images/webui-splash-screenshot.png

If you run Locust in Step Load Mode, then you should be greeted with Locust UI like this:

_images/webui-stepload-screenshot.png