Playbook Syntax Overview

In order to load test a server, you need to write a Playbook and make it process by the player.

The Playbook is a YAML file that describes what to do and how. It contains up to 6 sections which are not mandatory. The section order is irrelevant in YAML !

Playbook sections

Usually, the first "section" describes the global parameters and gives information such as the count of Virtual Users (VU) to simulate, the test duration, the rate of VU injection.

Name	Description	Example values
`iterations`	Mandatory - indicates how many time each VU must play the scenario	`2`
`duration`	Mandatory if iterations == -1. Time is in seconds	`100`
`rampup`	Mandatory - if 10 VU must be injected on a rampup period of 5s, 2 new VU will be created each second (time is in seconds)	`5`
`users`	Mandatory - number of VU to launch during the rampup period	`10`
`timeout`	Number of seconds before a network timeout occurs	`10`
`on_error`	Behaviour of error handling (continue, stop_iteration, stop_vu, stop_test)	`continue`
`http_error_codes`	if set, these HTTP response codes generates errors	`404,403,500`

The next section describes the default value for some parameters used to play HTTP/S as well as Database requests. The default values are keys which belong to the default key:

Name	Description	Example values
`server`	name of remoter server - may also specify a port, for SQL this a DSN. Mandatory if grpc_proto has been specified	`www.google.com:80` or `www.bing.com` or `mongodb://localhost:27017`
`protocol`	protocol to be used	`http` or `https`
`method`	HTTP method to use	`GET or POST`
`database`	default database for MongoDB and SQL	`my_database`
`collection`	default collection for MongoDB	`my_collection`
`db_driver`	default SQL Driver - only "mysql" and "postgres" are supported yet	`mysql`

User variables can be defined in the variables section, some variables are predefined. The variables can be referenced in the action section.

Example of user variable definition:

variables:
  my_var1: john
  other_var:
    - value1
    - value2

As you can see, variables can be scalar or arrays. In case of arrays, the values are used one after another during the iterations of the same virtual user.

Here is the list of the predefined variables:

Name	Description
`UID`	integer value which represents the virtual user ID
`HTTP_Response`	contains the HTTP returned code
`MONGODB_Last_Insert_ID`	contains the value of the `_id` field of the last inserted document (string)
`SQL_Row_Count`	contains the count of rows selected, updated or deleted (for SQL action)
`__cookie__name`	if the option `store_cookie` has been set for `http` actions, Cookies returned by the server can be referenced as variable by prefixing their name with the `__cookie__<cookie_name>`

Then come the pre_actions, actions and post_actions sections. They all share the same syntax (actions in fact). The pre_actions and post_actions sections are optional. pre_actions are played only once before starting the VUs, then actions are played by the VUs. post_actions are played at the end of the script. A typical usage of pre_actions would be to create a database table before injecting data. A typical usage of post_actions would be to clean a database table at the end of the script.

actions are typed and their attributes depend on their type.

Action Type	Description
`http`	used to make HTTP/S requests (GET, POST, PUT...)
`mongodb`	defines request for a MongoDB server
`sql`	defines request for a MySQL or PostgreSQL server
`ws`	implements the WebSocket protocol
`mqtt`	implements the MQTT protocol
`grpc`	implements the gRPC protocol (beta)
`tcp`	layer 4 (TCP) request
`udp`	layer 4 (UDP) request
`setvar`	creates user-defined variable, handles expression computation
`sleep`	simulates a user pause
`log`	generates a log message to help debugging
`assert`	defines assertion to make the script robust
`start_timer`	starts a user timer to measure a group of requests
`stop_timer`	stops a user timer

At last, the playbook may define a feeder section that references a CSV file which content will be used to populate variables and inject dynamic data in the requests:

feeder:
  type: csv
  filename: /path/to/file.csv
  separator: ","

You can click here if you want a full sample of the syntax