Test file format

A test is a YAML (or JSON) file. Unknown fields are rejected, so a typo is reported by teststream tests validate.

name: Empty cart cannot check out
description: Checkout is refused when nothing is in the cart.
role: standard_user
start: /inventory.html
folder: Checkout
tags: [smoke, critical]
background:
  - given: the cart is empty
steps:
  - when: I open the cart and click "Checkout"
  - then: checkout is refused or a message explains why

Fields

Field	Required	Meaning
name	yes	Test name, 1–200 characters.
steps	yes	1–60 steps.
description	no	Up to 4000 characters.
role	no	The role whose logged-in session the test starts in. lower_snake_case, for example standard_user.
start	no	The first page, absolute or relative to the environment's base URL.
folder	no	Folder for grouping, up to 200 characters.
tags	no	Up to 30 tags. Stored lowercase, spaces become -.
background	no	Up to 20 steps that run before steps.
examples	no	1–50 rows. The test runs once per row. See examples.
data	no	Named generated values.
dataSeed	no	A seed that reproduces a run's generated data.
key	no	Assigned by Teststream (SLUG-n). Ignored when you create a test.

Steps

A step has exactly one keyword.

Keyword	Meaning
given	A starting condition.
when	An action.
then	A check.
and, but	Continue the kind of the previous step.
use	Include shared steps by name.

Step text is 1–2000 characters. Two extra fields are allowed on given/when/then/and/but steps:

Field	Meaning
data	Test data for the step, such as a value to type or a file name.
optional: true	Skip the step when it does not apply, for example a banner that may not appear.

Shared steps

- use: new-transaction
  with: { amount: "<amount>", note: "Lunch" }

• The name is kebab-case.
• with gives the shared steps' parameters. Values are strings, numbers or booleans.
• A shared step may define defaults for parameters you leave out.

Examples

steps:
  - when: I enter the amount "<amount>"
  - then: I see "<shown>"
examples:
  - { amount: 5, shown: "$5.00" }
  - { amount: 12.5, shown: "$12.50" }

Every <name> used in the steps must be a column in examples, or validation fails.

Generated data

data:
  EMAIL: { faker: internet.email }
  LONG_TITLE: { faker: lorem.paragraph, length: 300 }

Names are UPPER_SNAKE_CASE, at most 20 per test. BASE_URL and names starting with EX_ are reserved. Use a value in steps, step data, the description and start as $NAME. It is generated once per run.

Generator	Produces	Options
person.firstName, person.lastName, person.fullName	A name	none
internet.username	A username	none
internet.email	A synthetic address on example.test	none
company.name	A company name	none
commerce.productName	A product name	none
location.streetAddress, location.city, location.zipCode	An address part	none
phone.number	A phone number	none
lorem.words	Words (3 by default)	count (1–100), length
lorem.sentence, lorem.paragraph	Text	length
string.uuid	A UUID	none
string.alpha, string.alphanumeric	Letters, or letters and digits (10 by default)	length
number.int	An integer (0–1000 by default)	min, max

length is an exact character count from 1 to 2000. min and max are inclusive, from −1,000,000,000 to 1,000,000,000.

Variables and secrets

$USERNAME and $PASSWORD style variables come from the environment. Never write a secret value in a test.