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

The root context

After each step executes, the test agent assembles a root context document — a single JSON object that assertions and extract rules query using $.-prefixed paths. Understanding this document is key to writing assertions and extractions.

$
├── request          // the step's own request
├── response         // the step's own response
├── responseTime     // response time in milliseconds
├── variables        // all variables in scope
├── traffic          // HTTP traffic captured between services
├── consoleLogs      // console output from services
├── dbLogs           // database query logs
├── messageLogs      // broker messages (AMQP/Kafka)
└── timeline         // all of the above merged chronologically

The shape of request and response depends on the action type:

Action type	`$.request`	`$.response`	`$.responseTime`
`httpRequest`	`method`, `url`, `headers`, `body`	`status`, `headers`, `body`	ms (number)
`dbQuery`	`database`, `query`	`success`, `data`, `rowsAffected`, `error`	ms (number)
`ui`	—	UI execution result	—
`wait`	—	—	—

The captured-data fields (traffic, consoleLogs, dbLogs, messageLogs) contain only entries from the current test's steps — traffic from one test is never visible in another.

See Assertions for how to query this document and Variables for how to extract values from it.

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 →