API

Locust class

class Locust

Locust class that inherits from LocustBase and creates a client attribute on instantiation.

The client attribute is a simple HTTP client with support for keeping a user session between requests.

schedule_task(task_callable, *args, **kwargs)

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

Arguments:

  • task_callable: Locust task to schedule
  • first: Optional keyword argument. If True, the task will be put first in the queue.
  • All other non keyword arguments will be passed to the task callable.
client = None

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

HttpBrowser class

class HttpBrowser(base_url, gzip=False)

Class for performing web requests and holding session cookie between requests (in order to be able to log in to websites).

Logs each request so that locust can display statistics.

get(path, headers={}, name=None, **kwargs)

Make an HTTP GET request.

Arguments:

  • path is the relative path to request.
  • headers is an optional dict with HTTP request headers
  • name is an optional argument that can be specified to use as label in the statistics instead of the path
  • catch_response is an optional boolean argument that, if set, can be used to make a request with a with statement. This will allows the request to be marked as a fail based on the content of the response, even if the response code is ok (2xx).
  • allow_http_error os an optional boolean argument, that, if set, can be used to not mark responses with HTTP errors as failures. If an HTTPError occurs, it will be available in the exception attribute of the response.

Returns an HttpResponse instance, or None if the request failed.

Example:

client = HttpBrowser("http://example.com")
response = client.get("/")

Example using the with statement:

from locust import ResponseError

with self.client.get("/inbox", catch_response=True) as response:
    if response.data == "fail":
        raise ResponseError("Request failed")
post(path, data, headers={}, name=None, **kwargs)

Make an HTTP POST request.

Arguments:

  • path is the relative path to request.
  • data dict with the data that will be sent in the body of the POST request
  • headers is an optional dict with HTTP request headers
  • name is an optional argument that can be specified to use as label in the statistics instead of the path
  • catch_response is an optional boolean argument that, if set, can be used to make a request with a with statement. This will allows the request to be marked as a fail based on the content of the response, even if the response code is ok (2xx).
  • allow_http_error os an optional boolean argument, that, if set, can be used to not mark responses with HTTP errors as failures. If an HTTPError occurs, it will be available in the exception attribute of the response.

Returns an HttpResponse instance, or None if the request failed.

Example:

client = HttpBrowser("http://example.com")
response = client.post("/post", {"user":"joe_hill"})

Example using the with statement:

from locust import ResponseError

with self.client.post("/inbox", {"user":"ada", content="Hello!"}, catch_response=True) as response:
    if response.data == "fail":
        raise ResponseError("Posting of inbox message failed")

HttpResponse class

class HttpResponse(method, url, name, code, data, info, gzip)

An instance of HttpResponse is returned by HttpBrowser’s get and post functions. It contains response data for the request that was made.

code = None

HTTP response code

data

Response data

url = None

URL that was requested

info

urllib2 info object containing info about the response

@require_once decorator

require_once(required_func)

@require_once decorator is used on a locust task in order to make sure another locust task (the argument to require_once) is run once (per client) before the decorated task.

The require_once decorator respects the wait time of the Locust class, by inserting the locust tasks at the beginning of the task execution queue.

Example:

def login(l):
    l.client.post("/login", {"username":"joe_hill", "password":"organize"})

@require_once(login)
def inbox(l):
    l.client.get("/inbox")

InterruptLocust Exception

exception InterruptLocust(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 0x2a6b210>

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: Instance of locust.clients.HttpResponse
request_failure = <locust.events.EventHook object at 0x2a6b290>

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 0x2a6b2d0>

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
report_to_master = <locust.events.EventHook object at 0x2a6b310>

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 0x2a6b350>

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 0x2a6b390>

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 0x2a6b3d0>

quitting is fired when the locust process in exiting

Project Versions

Table Of Contents

Previous topic

Extending Locust

Next topic

Changelog