Skip to main content

Stories engine

You can use the stories mechanism to test the bot. This is a mechanism that verifies that the bot will react in the expected way to events known in advance from the user. Events are grouped into separate stories, which are all described together in file as a list. Multiple stories files can be grouped in a directory.


Each story is an object and has the following set of fields:

name*StringPrintable name.
turns*List of TurnSchemaList of story turns.
markersList of StringsList of pytest marks


One step of history. It is an object and has the following set of fields:

utc_timeStringDate and time string of the story step in ISO 8601 format.
messageMessageSchemaIncoming message from customer.
rpcRpcRequestSchemaIncoming RPC event.
response*StringExpected bot response.

One of the fields must be filled in the TurnSchema object: message or rpc.

If no time zone is specified in the TurnSchema.utc_time field, then the value will be considered in UTC. If the TurnSchema.utc_time field contains a value with any time zone other than UTC, then the value will be converted to the UTC time zone.

After a step with the TurnSchema.utc_time field explicitly specified, all subsequent steps without this field will be shifted forward by 10 seconds.

If the bot can respond with one of the predefined answers (e.g. chosen by the bot's script using random) then the response field should contain a list of strings. One list item for each possible bot response.

- name: seasons-random
- message: season
- "Spring"
- "Summer"
- "Autumn"
- "Winter"