Tests & Steps

Structure test cases with sequential steps and parallel actions.

Test structure

Tests are defined in the top-level tests array. Each test is independent and contains a flat list of steps that run sequentially.

{
  "name": "my-test-suite",
  "items": [ ... ],
  "tests": [
    {
      "name": "Create and fetch a user",
      "variables": { "email": "test@example.com" },
      "steps": [
        { "name": "Step 1", ... },
        { "name": "Step 2", ... }
      ]
    }
  ]
}

Sequential and parallel execution

Steps are a flat array and run sequentially, one after another. When you need concurrent execution, use the parallel action type to run multiple actions simultaneously within a single step:

"steps": [
  {
    "name": "Create both users in parallel",
    "action": {
      "type": "parallel",
      "actions": [
        { "type": "httpRequest", "method": "POST", "url": "api-gateway/api/users", "body": { "name": "User A" } },
        { "type": "httpRequest", "method": "POST", "url": "api-gateway/api/users", "body": { "name": "User B" } }
      ]
    }
  },
  {
    "name": "List all users",
    "action": { "type": "httpRequest", "method": "GET", "url": "api-gateway/api/users" }
  }
]

TestDefinition fields

Field	Type	Required	Default	Description
`name`	string	Yes	—	Name of the test
`description`	string	No	—	What the test verifies
`timeoutSeconds`	integer	No	—	Timeout for entire test
`stopOnFailure`	boolean	No	`true`	Stop subsequent steps when any assertion fails
`variables`	object	No	—	Test-level variables (overrides definition-level). Supports `$ref`.
`steps`	array	Yes	—	Sequential list of test steps

TestStep fields

Field	Type	Required	Default	Description
`name`	string	No	—	Step name
`description`	string	No	—	Step description
`action`	object	Yes	—	Action to execute (see Actions)
`extract`	object	No	—	Extract variables from response (see Variables)
`assertions`	array	No	—	Assertion blocks (see Assertions)
`stopOnFailure`	boolean	No	`true`	Stop test when assertions in this step fail

Definition-level variables

The definition file itself can have a top-level variables field alongside name, items, and tests. These are shared across all tests in the definition. Test-level variables override definition-level variables with the same key.

{
  "name": "my-suite",
  "variables": {
    "baseEmail": "test@example.com"
  },
  "items": [ ... ],
  "tests": [
    {
      "name": "Test 1",
      "variables": {
        "baseEmail": "override@example.com"
      },
      "steps": [ ... ]
    }
  ]
}

See Variables for full details on interpolation, extraction, and scoping.

← References ($ref) Actions →