API

Locust class

class Locust

Represents a “user” which is to be hatched and attack the system that is to be load tested.

The behaviour of this user is defined by the task_set attribute, which should point to a TaskSet class.

This class creates a client attribute on instantiation which is an HTTP client with support for keeping a user session between requests.

min_wait = 1000

Minimum waiting time between the execution of locust tasks

max_wait = 1000

Maximum waiting time between the execution of locust tasks

task_set = None

TaskSet class that defines the execution behaviour of this locust

min_wait = 1000

Minimum waiting time between the execution of locust tasks

max_wait = 1000

Maximum waiting time between the execution of locust tasks

task_set = None

TaskSet class that defines the execution behaviour of this locust

client = None

Instance of HttpSession that is created upon instantiation of Locust. The client support cookies, and therefore keeps the session between HTTP requests.

TaskSet class

class TaskSet(parent)

Class defining a set of tasks that a Locust user will execute.

When a TaskSet starts running, it will pick a task from the tasks attribute, execute it, call it’s wait function which will sleep a randomm number between min_wait and max_wait milliseconds. It will then schedule another task for execution and so on.

TaskTests can be nested, which means that a TaskSet’s tasks attribute can contain another TaskSet. If the nested TaskSet it scheduled to be executed, it will be instanciated and called from the current executing TaskSet. Execution in the the currently running TaskSet will then be handed over to the nested TaskSet which will continue to run until it throws an InterruptTaskSet exception, which is done when TaskSet.interrupt() is called. (execution will then continue in the first TaskSet).

locust = None

Will refer to the root Locust class when the TaskSet has been instantiated

min_wait = None

Minimum waiting time between the execution of locust tasks. Can be used to override the min_wait defined in the root Locust class, which will be used if not set on the TaskSet.

max_wait = None

Maximum waiting time between the execution of locust tasks. Can be used to override the max_wait defined in the root Locust class, which will be used if not set on the TaskSet.

client = None

Reference to the client attribute of the root Locust instance.

tasks = []

List with python callables that represents a locust user task.

If tasks is a list, the task to be performed will be picked randomly.

If tasks is a (callable,int) list of two-tuples, or a {callable:int} dict, the task to be performed will be picked randomly, but each task will be weighted according to it’s corresponding int value. So in the following case ThreadPage will be fifteen times more likely to be picked than write_post:

class ForumPage(TaskSet):
    tasks = {ThreadPage:15, write_post:1}
interrupt(reschedule=True)

Interrupt the TaskSet and hand over execution control back to the parent TaskSet.

If reschedule is True (default), the parent Locust will immediately re-schedule, and execute, a new task

This method should not be called by the root TaskSet (the one that is immediately, attached to the Locust class’ task_set attribute), but rather in nested TaskSet classes further down the hierarchy.

schedule_task(task_callable, args=[], kwargs={}, first=False)

Add a task to the Locust’s task execution queue.

Arguments:

  • task_callable: Locust task to schedule
  • args: Arguments that will be passed to the task callable
  • kwargs: Dict of keyword arguments that will be passed to the task callable.
  • first: Optional keyword argument. If True, the task will be put first in the queue.

task decorator

task(weight=1)

Used as a convenience decorator to be able to declare tasks for a TaskSet inline in the class. Example:

class ForumPage(TaskSet):
    @task(100)
    def read_thread(self):
        pass
    
    @task(7)
    def create_thread(self):
        pass

HttpSession class

class HttpSession(base_url, *args, **kwargs)

Class for performing web requests and holding (session-) cookies between requests (in order to be able to log in and out of websites). Each request is logged so that locust can display statistics.

This is a slightly extended version of python-request‘s requests.Session class and mostly this class works exactly the same. However the methods for making requests (get, post, delete, put, head, options, patch, request) can now take a url argument that’s only the path part of the URL, in which case the host part of the URL will be prepended with the HttpSession.base_url which is normally inherited from a Locust class’ host property.

Each of the methods for making requests also takes two additional optional arguments which are Locust specific and doesn’t exist in python-requests. These are:

Parameters:
  • name – (optional) An argument that can be specified to use as label in Locust’s statistics instead of the URL path. This can be used to group different URL’s that are requested into a single entry in Locust’s statistics.
  • catch_response – (optional) Boolean argument that, if set, can be used to make a request return a context manager to work as argument to a with statement. This will allow the request to be marked as a fail based on the content of the response, even if the response code is ok (2xx). The opposite also works, one can use catch_response to catch a request and then mark it as successful even if the response code was not (i.e 500 or 404).
request(method, url, name=None, catch_response=False, **kwargs)

Constructs and sends a requests.Request. Returns requests.Response object.

Parameters:
  • method – method for the new Request object.
  • url – URL for the new Request object.
  • name – (optional) An argument that can be specified to use as label in Locust’s statistics instead of the URL path. This can be used to group different URL’s that are requested into a single entry in Locust’s statistics.
  • catch_response – (optional) Boolean argument that, if set, can be used to make a request return a context manager to work as argument to a with statement. This will allow the request to be marked as a fail based on the content of the response, even if the response code is ok (2xx). The opposite also works, one can use catch_response to catch a request and then mark it as successful even if the response code was not (i.e 500 or 404).
  • params – (optional) Dictionary or bytes to be sent in the query string for the Request.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • headers – (optional) Dictionary of HTTP Headers to send with the Request.
  • cookies – (optional) Dict or CookieJar object to send with the Request.
  • files – (optional) Dictionary of ‘filename’: file-like-objects for multipart encoding upload.
  • auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
  • timeout – (optional) Float describing the timeout of the request.
  • allow_redirects – (optional) Boolean. Set to True by default.
  • proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
  • return_response – (optional) If False, an un-sent Request object will returned.
  • config – (optional) A configuration dictionary. See request.defaults for allowed keys and their default values.
  • prefetch – (optional) whether to immediately download the response content. Defaults to True.
  • verify – (optional) if True, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
  • cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.
get(url, **kwargs)

Sends a GET request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • **kwargs – Optional arguments that request takes.
post(url, data=None, **kwargs)

Sends a POST request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • **kwargs – Optional arguments that request takes.
delete(url, **kwargs)

Sends a DELETE request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • **kwargs – Optional arguments that request takes.
put(url, data=None, **kwargs)

Sends a PUT request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • **kwargs – Optional arguments that request takes.
head(url, **kwargs)

Sends a HEAD request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • **kwargs – Optional arguments that request takes.
options(url, **kwargs)

Sends a OPTIONS request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • **kwargs – Optional arguments that request takes.
patch(url, data=None, **kwargs)

Sends a PATCH request. Returns Response object.

Parameters:
  • url – URL for the new Request object.
  • data – (optional) Dictionary or bytes to send in the body of the Request.
  • **kwargs – Optional arguments that request takes.

Response class

This class actually resides in the python-requests library, since that’s what Locust is using to make HTTP requests, but it’s included in the API docs for locust since it’s so central when writing locust load tests. You can also look at the Response class at the requests documentation.

class Response

The core Response object. All Request objects contain a response attribute, which is an instance of this class.

Response.config = None

Dictionary of configurations for this request.

Response.content

Content of the response, in bytes.

Response.cookies = None

A CookieJar of Cookies the server sent back.

Response.encoding = None

Encoding to decode with when accessing r.text.

Response.error = None

Resulting HTTPError of request, if one occurred.

Response.headers = None

Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

Response.history = None

A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.

Response.iter_content(chunk_size=1, decode_unicode=False)

Iterates over the response data. This avoids reading the content at once into memory for large responses. The chunk size is the number of bytes it should read into memory. This is not necessarily the length of each item returned as decoding can take place.

Response.iter_lines(chunk_size=10240, decode_unicode=None)

Iterates over the response data, one line at a time. This avoids reading the content at once into memory for large responses.

Response.json

Returns the json-encoded content of a response, if any.

Response.links

Returns the parsed header links of the response, if any.

Response.raise_for_status(allow_redirects=True)

Raises stored HTTPError or URLError, if one occurred.

Response.raw = None

File-like object representation of response (for advanced usage).

Response.reason

The HTTP Reason for the response.

Response.request = None

The Request that created the Response.

Response.status_code = None

Integer Code of responded HTTP Status.

Response.text

Content of the response, in unicode.

if Response.encoding is None and chardet module is available, encoding will be guessed.

Response.url = None

Final URL location of Response.

ResponseContextManager class

class ResponseContextManager(response)

A Response class that also acts as a context manager that provides the ability to manually control if an HTTP request should be marked as successful or a failure in Locust’s statistics

This class is a subclass of Response with two additional methods: success and failure.

success()

Report the response as successful

Example:

with self.client.get("/does/not/exist", catch_response=True) as response:
    if response.status_code == 404:
        response.success()
failure(exc)

Report the response as a failure.

exc can be either a python exception, or a string in which case it will be wrapped inside a CatchResponseError.

Example:

with self.client.get("/", catch_response=True) as response:
    if response.content == "":
        response.failure("No data")

InterruptTaskSet Exception

exception InterruptTaskSet(reschedule=True)

Exception that will interrupt a Locust when thrown inside a task

Event hooks

The event hooks are instances of the locust.events.EventHook class:

class EventHook

Simple event class used to provide hooks for different types of events in Locust.

Here’s how to use the EventHook class:

my_event = EventHook()
def on_my_event(a, b):
    print "Event was fired with arguments: %s, %s" % (a, b)
my_event += on_my_event
my_event.fire("foo", "bar")

Available hooks

The wollowing event hooks are available under the locust.events module:

request_success = <locust.events.EventHook object at 0x1edf910>

request_success is fired when an HTTP request is completed successfully.

Listeners should take the following arguments:

  • method: HTTP Request method used
  • path: Path to the URL that was called (or override name if it was used in the call to the client)
  • response_time: Reponse time in milliseconds
  • response_length: Content-length of the response
request_failure = <locust.events.EventHook object at 0x1edf990>

request_failure is fired when an HTTP request fails

Event is fired with the following arguments:

  • method: HTTP Request method used
  • path: Path to the URL that was called (or override name if it was used in the call to the client)
  • response_time: Time in milliseconds until exception was thrown
  • exception: Exception instance that was thrown
  • response: If the failure was due to an HTTP error code (exception is an instance of urllib2.HTTPError), then response will be an instance of locus.clients.HttpResponse. Otherwise response will be None.
locust_error = <locust.events.EventHook object at 0x1edf9d0>

locust_error is fired when an exception occurs inside the execution of a Locust class.

Event is fired with the following arguments:

  • locust_instance: Locust class instance where the exception occured
  • exception: Exception that was thrown
  • traceback: Traceback object (from sys.exc_info()[2])
report_to_master = <locust.events.EventHook object at 0x1edfa10>

report_to_master is used when Locust is running in –slave mode. It can be used to attach data to the dicts that are regularly sent to the master. It’s fired regularly when a report is to be sent to the master server.

Note that the keys “stats” and “errors” are used by Locust and shouldn’t be overridden.

Event is fired with the following arguments:

  • client_id: The client id of the running locust process.
  • data: Data dict that can be modified in order to attach data that should be sent to the master.
slave_report = <locust.events.EventHook object at 0x1edfa50>

slave_report is used when Locust is running in –master mode and is fired when the master server recieves a report from a Locust slave server.

This event can be used to aggregate data from the locust slave servers.

Event is fired with following arguments:

  • client_id: Client id of the reporting locust slave
  • data: Data dict with the data from the slave node
hatch_complete = <locust.events.EventHook object at 0x1edfa90>

hatch_complete is fired when all locust users has been spawned.

Event is fire with the following arguments:

  • user_count: Number of users that was hatched
quitting = <locust.events.EventHook object at 0x1edfad0>

quitting is fired when the locust process in exiting

Project Versions

Table Of Contents

Previous topic

Writing a locustfile

Next topic

Extending Locust