Writing Scripts

Overview

Run configuration scripts are text files, that are read and compiled by the Context Manager. This configuration is then passed to the Run Manager for execution.

Note

Unless you are a Python programmer, you may have to get used to the fact that whitespace matters in YAML files:
Make sure you indent uniformly. Don’t mix tabs and spaces. We recommend to use an editor that supports the YAML syntax (e.g. VS Code).

A simple confuguration script may look like this:
scenario_1.yaml:

 1# ----------------------------------------------------------------------------
 2# Stressor Scenario Definition
 3# See
 4#   - https://stressor.readthedocs.io/
 5#   - https://stressor.readthedocs.io/en/latest/ug_reference.html
 6# ----------------------------------------------------------------------------
 7file_version: stressor#0
 8
 9config:
10  name: Test Scenario 1
11  #: (str) Default URL prefix
12  base_url: http://127.0.0.1:8082
13  #: (int) Max. total error count that is tolerated before stopping
14  #: (override with `--max-errors`)
15  max_errors: 0
16  #: (float) Max. run time in seconds before stopping (override with `--max-time`)
17  max_time: 0.0
18
19# Initial context value definitions and defaults:
20context:
21
22# Define the virtual test users and no. of sessions:
23sessions:
24  users: $load(users.yaml)
25  count: 3
26  basic_auth: false
27  verify_ssl: false
28
29# Define what actions should be performed by every session:
30scenario:
31  - sequence: init
32  - sequence: main
33    repeat: 3
34  - sequence: end
35
36# List of named action sequences. Used as building blocks for scenarios:
37sequences:
38  # 'init' is the reserved name for the set-up sequence:
39  init:
40    - activity: GetRequest
41      url: login
42      auth: $(user.auth)
43
44  # Other sections can have arbitrary names and are excuted as defined in 'scenario'.
45  main:
46    - activity: PutRequest
47      url: $(base_url)/test_file.txt
48      data: "Test"
49      assert_max_time: 0.5
50
51    - activity: $sleep(0.3)
52
53    - activity: GetRequest
54      url: $(base_url)/test_file.txt
55      assert_match: "Test"
56
57
58  # 'end' is the reserved name for the tear-down sequence.
59  end:
60    - activity: GetRequest
61      url: $(base_url)/log_out

The above example assumes the virtual users to be defined in a separate file, for example:
users.yaml:

1- name: User_1
2  password: secret
3- name: User_2
4  password: guessme

Script Activities

RunScript activities are the swiss army knife for the scenario definitions. The follwing example shows inline script definitions.

 1main:
 2
 3- activity: RunScript
 4    export: ["the_answer"]
 5    script: |
 6    the_answer = 6 * 7
 7    print("The answer is {}".format(the_answer))
 8
 9- activity: RunScript
10    name: "GET example.com"
11    # debug: true
12    script: |
13    r = session.browser.get("http://example.com")
14    result = r.status_code

Importing HAR Files

HAR files contain a list of recorded browser requests.
stressor can convert those files into its own format, e.g. a YAML formatted sequence of HTTPRequest activities.

We can use the Chrome browser as macro recorder like so:

  1. Open a Chrome tab and start the developer tools e.g. by hitting F12.

  2. Activate the Network panel.

  3. Clear the current network log if any.

  4. Navigate to the URL that you want to record and perform your activities.

  5. Select Save all as HAR with content… from the context menu.

Now convert the HAR file to a new stressor project:

$ stressor init /path/to/scenario_name --convert /path/to/har_file.har

You probably want to edit scenario.yaml and main_sequence.yaml in the /path/to/scenario_name/ folder now.

Optionally, additional conversion options can be defined:

$ stressor init /path/to/scenario_name --convert /path/to/har_file.har --config /path/to/convert_opts.yaml

The available options (with their default):
convert_opts.yaml

 1# Stressor HAR conversion options
 2# See https://stressor.readthedocs.io/
 3
 4#force: False,  # Use --force argument instead
 5base_url: true  # true: automatic
 6collate_max_len: 100  # Put max 100 URL into one StaticRequests activity
 7collate_max_duration: 1.0  # Collate burst intervals of max. 1 second
 8collate_max_pause: 0.2  # Start a new collation if have a gap of 0.2 seconds
 9collate_thread_count: 5  # The created StaticRequests activity uses 5 threads
10# add_req_comments: True
11skip_externals: true
12statics_types:  # Regular expressions (case insensitive)
13    - "image/.*"
14    - ".*/css"
15    - ".*/javascript"
16"skip_errors": true

Debugging

Use the --verbose (short -v) option to generate more console logging.
Use the --single option to run all activities once, but only in one single session. Also loop counts are ignored:

$ stressor run ./scenario_1/scenario.yaml --single -v

Activities can be marked with a debug argument, which will generate more output, for example response body, etc.
The monitor argument will add the activity as distinct entry of a special section of the monitor dashboard (use with the --monitor option):

sequences:
  main:
    - activity: GetRequest
      url: $(base_url)/
      assert_match: ".*Index of /.*"
      assert_html:
        "//*[@class='logo']": true
      debug: true
      monitor: true