Script Reference

Configuration

The whole stressor confiuration is stored in a single YAML file with a few attributes and five mandatory sections.

See also

See the annotated stressor.yaml for an example.

Top-level Attributes

file_version (str)

File identifier, must be file_version: 'stressor#0'.

‘config’: Section

This section contains general configuration.

config.base_url (str, default: ‘’)

Prefix that is prepended to relative URLs in HTTP activities. Example: base_url: 'http://example.com/foo'

config.details (str, default: ‘’)

Optional multi-line string with additional info.

config.max_errors (int, default: 0)

Maximum total error count that is tolerated before stopping. Override with –max-errors argument. Default 0 means: don’t stop on errors.

config.max_time (float, default: 0.0)

(float) Max. run time in seconds before stopping (override with –max-time) Default 0.0 means: no time limit.

config.name (str, default: file name)

Scenario name (defaults to name of this file without ‘.yaml’ extension)

config.request_timeout (float, default: null)

Default timeout in seconds for web requests (i.e. HTTP activities) This value can be overridden with HTTP-Activity’s timeout parameter

config.tag (str, default: ‘’)

Optional string that describes the current run. May be used to display additional info about boundary conditions, etc. Example ‘Test-Run STAGING nightly’ (pass -o “tag:MY TAG INFO” to override)

config.verbose (int, default: 3)

Output verbosity level [0..5]. (See also --verbose/-v argument)

‘context’ Section

When a scenario is run, one separate context dictionary is created per session. This instance is then passed to every activity of the session’s sequences, so activities can read and write from/to it using macro syntax:
$(context_name)

The context dictionary inherits all entries from the ‘config’ section above, but we can optionally add new or override exising settings here.
Values may also be defined or overridden using the the command line, e.g. –option “NAME:VALUE”

See also

See also the Context Variables section below for details.

‘sessions’ Section

This run configuration defines how the sequences are executed in parallel sessions.

sessions.basic_auth (bool, default: false)

Pass true to enable HTTP basic authentication, using user’s credentials.

sessions.count (int, default: 1)

Number of sessions (virtual users). If greater than no. of users, users will be re-used round robin.

sessions.duration (float, default: 0.0)

max. run time in seconds, before the session stops. The current and the ‘end’ sequences are completed. Default: 0.0 means no time limit.

sessions.ramp_up_delay (float, default: 0.0)

Waiting time between starting distinct user sessions in seconds. Default 0.0 means start all session at once.

sessions.users (list, default: [])

Defines a list of user dicts, with at least name and pasword attributes. Often stored in a separate file and included like so: users: $load(users.yaml)
If no users are defined, one user is assumed: {"name": "anonymous", "password": ""}.

sessions.verify_ssl (bool, default: true)

Pass false to ignore SSL certificate errors.

‘scenario’ Section

Define the order and duration of sequences that every virtual user session performs. All sequence definitions that are referenced here, must also appear in the following sequences section.

scenario:
  - sequence: init  # This is typically the first sequence
  - sequence: SEQUENCE_NAME
    repeat: 3  # optional
  - sequence: SEQUENCE_NAME
    duration: 30.0  # optional
  - sequence: end  # This is typically the last sequence
scenario_item.sequence (str)

‘init’ is the reserved name for the set-up sequence, like logging-in. If errors occur here, all subsequent sequences (including ‘end’) are skipped.

Other sections can have arbitrary names and are excuted in order of appearance.
Sequence names may occur multiple times.

‘end’ is the reserved name for the tear-down sequence (e.g. log out or cleanup fixtures).
This sequence is executed even if errors in previous sequences caused the scenario to stop.

scenario_item.duration (float, default: 0.0)

This sequence is repeated in a loop, until duration seconds are reached (always completing the current sequence). Default: 0.0 means no time-based looping.

scenario_item.repeat (int, default: 1)

This sequence is repeated in a loop, until repeat iterations are completed.

‘sequences’ Section

List of named action sequences. Used as building blocks for scenarios:

sequences:
  SEQUENCE_NAME_1:
    - activity: ACTIVITY_TYPE
      ...  # activity arguments
    - activity: ACTIVITY_TYPE
      ...
  SEQUENCE_NAME_2:
    - activity: ACTIVITY_TYPE
      ...
    - activity: ACTIVITY_TYPE
      ...

See below for details on Activities.

Activities

Activities are defined as part of a sequence list like so:

- activity: ACTIVITY_TYPE
...

See also

See also some examples: stressor.yaml and Writing Scripts.

Common Args

All activites share these common arguments (see also ActivityBase).

activity (str)

The activity type, e.g. “GetRequest”, “RunScript”, or “Sleep”.
Also macros like “$sleep(0.3)” are accepted.

assert_match (str, optional)

Check if the result matches a regular expression.
Tip: Prepend (?i) to the expression to enable case insensitive match:

assert_match: "(?i).*foobar.*"
assert_max_time (float, optional)

Trigger error if execution takes longer than x seconds.

debug (bool, default: false)

Increase logging for this activity.

ignore_timing (bool, default: false)

If true, this activity’s run time does not count towards the ‘net time’ statistics.
For Sleep activities this defaults to true.

mock_result (any, optional):

If dry-run mode is active, this activity is not run, but instead the value of mock_result is stored as context.last_result.

monitor (bool, default: false)

Pass true to collect and display statistics for this activity as a separate line.

name (str, default: ‘’)

A name that will be used when logging this activity.

store_json (str, optional)

Store a part of the activity’s JSON result as context variable.
For example if the activity returns {"response": {"key": "1234abc"}} for this request:

- activity: GetRequest
  url: /my_target
  store_json:
    res_key: 'response.key'

We would create a context variable that would be accessible as $(res_key) == “1234abc”. (See also the assert_json argument of HTTP activities.)

HTTP Request Activities

Stressor defines a generic HTTPRequestActivity class, that accepts (among others) a method argument.
These four convenience activities are direct derivatives that set the method argument accordingly:
GetRequestActivity, PostRequestActivity, PutRequestActivity, DeleteRequestActivity.

(Another related activity is the StaticRequestsActivity.)

Following a list of activity arguments.
Note: Arguments marked with [req] are passed directly to the requests library.

assert_html (dict, optional)

Check if the response has HTML format and matches an XPath expression:

- activity: GetRequest
url: /
assert_html:
    "//*[@class='logo']": true

(See also the common assert_match argument.)

assert_json (dict, optional)

Check if the response has JSON format and contains a specific value or format, e.g. {"status": "ok", "result": {"guid": "{BBFC98E6-DD92-473C-A65C-BDD868E64CF2}"}}:

- activity: GetRequest
  url: /my_target
  assert_json:
    status: 'ok'
    result.guid: '[{]?[0-9a-fA-F\-]{36}[}]?'

(See also the common store_json argument.)

assert_match_headers (str, optional)

Check if the headers match a regular expression, for example:

assert_match_headers: ".*'DAV'.*"

Prepend (?i) to the expression to enable case insensitive match: "(?i).*'DAV'.*"

assert_status (list[int], optional)

Normally HTTP requests raise an error if the return status code is 4xx, 5xx, etc.
Here we can define a list of status codes that will be considerd ‘success’.

auth (2-tuple, optional) [req]

(username, password) will be used for HTTP Basic Authentication.
The default for this setting is defined by the config.basic_auth option: if true, this tuple will be defined as (user.name, user.password) for the current session.

data (dict, optional) [req]

Used to pass form-encoded data with POST requests.

json (dict, optional) [req]

Used to pass JSON data with POST requests.

headers (dict, optional) [req]

Pass additional headers with the request.

method (str)

This is mandatory for the HTTPRequestActivity: passing “GET” is equivalent to using GetRequestActivity for example.
Other common values could “OPTION”, “HEAD”, …

params (dict, optional) [req]

Pass URL arguments with GET/POST, … requests.

timeout (float, optional) [req]

Request timeout in seconds (default: infinite).
Note: the default for this flag is defined by the config.request_timeout option.

url (str) [req]

Target URL for the request.
For relative URLs (no server part), the config.base_url prefix will be added:
url: /my_target is equivalent to url: $(base_url)/my_target.

verify (bool, optional) [req]

False: ignore SSL certificate verification errors.
The default for this flag is defined by the config.verify_ssl option.

‘RunScript’ Activity

(see also RunScriptActivity).

export (bool|null|list, optional)

List of local variable names (defined by the script) should be exported into the run context. Pass null or false to define ‘no export wanted’. Omitting this argumet is considered ‘undefined’ and will emit a warning if the script defines variables.

path (str, optional)

Path to a python file.

- activity: RunScript
    export: ["the_answer"]
    path: "my_script.py"
script (str, optional)

Python script code, e.g.

- activity: RunScript
    export: ["the_answer"]
    script: |
    the_answer = 6 * 7
    print("The answer is {}".format(loclhost))

Afterwards the context contains the result and can be accessed like $(the_answer).

‘Sleep’ Activity

SleepActivity

duration (float)

Sleep time in seconds.

duration_2 (float, optional)

If defined, the sleep time will be a random value in the range [duration .. duration_2].

Context Variables

When a scenario is run, one separate context dictionary is created per session.
The context contains all entries from the ‘config’ section and everything that was added to the ‘context’ section.
Values may also be defined or overridden via the command line, e.g. --option "NAME:VALUE".

This instance is then passed to every activity of the session’s sequences, so activities can read it using macro syntax, e.g $(var_name).
Activitites may als write to the context, for example by using the store_json or export argument.

Finally, also these values are added:

dry_run (bool)

If true, activities should avoid to perform write operations.

last_result (any)

The result of the previous activity. Mostly a string, possibly truncated to a reasonable length.

session_id (str)

The ID of the current session, e.g. "t03".
This string may be handy to construct session-specific file names, URLs, etc.:

- activity: PutRequest
  url: /wsgidav_test_file~$(session_id).txt
user (dict)

The current user that is assigned to this session.
‘name’ and password are always present, but we can also add custom attributes to the user list entries.
Access properties like $(user.name), $(user.password), $(user.field_1), …

verbose (int)

0: quiet .. 5: maximal verbose

See Macros below for details on how to access those attributes in action definitions.

Macros

$(context_var):

This macro looks-up and returns a variable of the current run context, for examle $(base_url), $(session_id).
Use dots (‘.’) to address sub-members, e.g. $(user.name).

$sleep(duration) or $sleep(min, max):

A shortcut to the Sleep activity (see above).

$debug:

Dump the current run context (useful when debugging scripts).