Quick start¶
Example locustfile.py¶
Below is a quick little example of a simple locustfile.py:
from locust import HttpLocust, TaskSet, between
def login(l):
l.client.post("/login", {"username":"ellen_key", "password":"education"})
def logout(l):
l.client.post("/logout", {"username":"ellen_key", "password":"education"})
def index(l):
l.client.get("/")
def profile(l):
l.client.get("/profile")
class UserBehavior(TaskSet):
tasks = {index: 2, profile: 1}
def on_start(self):
login(self)
def on_stop(self):
logout(self)
class WebsiteUser(HttpLocust):
task_set = UserBehavior
wait_time = between(5.0, 9.0)
Here we define a number of Locust tasks, which are normal Python callables that take one argument
(a Locust
class instance). These tasks are gathered under a
TaskSet
class in the tasks attribute. Then we have a
HttpLocust
class which represents a user, where we define how
long a simulated user should wait between executing tasks, as well as what
TaskSet
class should define the user’s “behaviour”.
TaskSet
classes can be nested.
The HttpLocust
class inherits from the
Locust
class, and it adds a client attribute which is an instance of
HttpSession
that can be used to make HTTP requests.
By default, we stop looking for proxy settings to improve performance. If you really want the test requests
go through a HTTP proxy, you can inherit from the HttpLocust
class and
set the trust_env field to True. For further details, refer to the documentation of requests.
Another way we could declare tasks, which is usually more convenient, is to use the
@task
decorator. The following code is equivalent to the above:
from locust import HttpLocust, TaskSet, task, between
class UserBehaviour(TaskSet):
def on_start(self):
""" on_start is called when a Locust start before any task is scheduled """
self.login()
def on_stop(self):
""" on_stop is called when the TaskSet is stopping """
self.logout()
def login(self):
self.client.post("/login", {"username":"ellen_key", "password":"education"})
def logout(self):
self.client.post("/logout", {"username":"ellen_key", "password":"education"})
@task(2)
def index(self):
self.client.get("/")
@task(1)
def profile(self):
self.client.get("/profile")
class WebsiteUser(HttpLocust):
task_set = UserBehaviour
wait_time = between(5, 9)
The Locust
class (as well as HttpLocust
since it’s a subclass) also allows one to specify the wait time between the execution of tasks
(wait_time = between(5, 9)
) as well as other user behaviours.
With the between function the time is randomly chosen uniformly between the specified min and max values,
but any user-defined time distributions can be used by setting wait_time to any arbitrary function.
For example, for an exponentially distributed wait time with average of 1 second:
import random
class WebsiteUser(HttpLocust):
task_set = UserBehaviour
wait_time = lambda self: random.expovariate(1)*1000
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 slave processes:
$ locust -f locust_files/my_locust_file.py --slave
If we want to run Locust distributed on multiple machines we would also have to specify the master host when starting the slaves (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 --slave --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:
If you run Locust in Step Load Mode, then you should be greeted with Locust UI like this: