> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API test scenarios

> API scenarios are reusable tests with steps, assertions, captures, tags, and draft-to-active lifecycle.

# Scenarios

An API scenario is a reusable test for one API behavior.

It describes the request steps to run, the data to capture, the assertions to check, and whether the scenario is still a draft or ready for scheduled runs.

![Qodex agent generating API test scenarios from a chat request](https://mintcdn.com/qodexai/rhkO1RmGEPTQ07wr/images/docs/api-testing/ai-scenario-generation.gif?s=69e6d42b9b3d79bd4e3aeec1bd17b289)

## How a scenario is structured

Each scenario is stored on the project with the steps, captures, and assertions needed to test one behavior. Here is an abbreviated shape:

```json theme={null}
{
  "id": "scn_a1b2",
  "name": "POST /users returns 201 with id",
  "description": "Happy path: valid payload, valid auth, expect 201 + id in body.",
  "type": "api",
  "status": "draft",
  "priority": "high",
  "tags": ["users", "happy-path"],
  "steps": [
    {
      "order": 1,
      "kind": "api",
      "action": "create user",
      "target": "${API_BASE_URL}/users",
      "method": "POST",
      "auth": { "type": "bearer", "token": "${AUTH_TOKEN}" },
      "body": { "email": "test+${TS}@example.com", "name": "Ada" },
      "expectedStatus": 201,
      "captures": [{ "as": "userId", "from": "$.id" }],
      "expectations": [
        { "kind": "status", "equals": 201 },
        { "kind": "jsonpath", "path": "$.id", "exists": true }
      ]
    }
  ]
}
```

Important fields:

* `type` is `api`, `ui`, or `mixed`. This page covers `api`.
* `status` is `draft` or `active`. The scheduler only runs `active`.
* `steps[]` are ordered. Each step has an `action`, a `target`, optional `auth`, optional `body`, optional `captures` for chaining, and `expectations` (the assertions).
* `tags` filter scenarios at run time (`smoke`, `checkout`, `auth`).
* `priority` is `critical`, `high`, `medium`, or `low`.

## Lifecycle: draft to active

Every scenario starts as `draft`. Qodex can recommend and generate tests, but humans decide when a test is ready for automation.

| Status | Who can run it | Used for |
| - | - | - |
| `draft` | You, manually | Review, edit, promote |
| `active` | Scheduler, webhooks, CI, you | Regression runs |

Promote a scenario when the steps and assertions look right: open it from **Scenarios** (under **Test** in the sidebar) and click **Mark active** in the detail panel, or select several rows and click **Activate**. Click the **ACTIVE** state, or select rows and click **Deactivate**, to move a scenario back to `draft` when the underlying endpoint changes and you need a quiet window to update.

The draft default is deliberate. Generated scenarios are recommendations, not releases. Scheduled suites only execute scenarios you have explicitly promoted.

## Authoring from chat

In a chat, describe the behavior:

```text theme={null}
Test that POST /orders requires auth: no token -> 401,
expired token -> 401, valid admin token -> 201.
```

Qodex picks the matching endpoints from the catalog, generates one scenario per behavior, and verifies them against your default `staging` environment. The verdict (`pass`, `fail`, `error`) attaches to the scenario row immediately so you can triage right away.

Prompts that work well:

* Name a behavior, not a step list. "Test the refund flow" beats "POST /refunds then GET /orders/123".
* Reference your terms: module names (`auth`, `users`, `billing`), HTTP codes (`401`, `403`, `422`), and edge cases (`missing email`, `expired token`).
* Constrain auth explicitly when it matters: "as admin", "without a token", "as a viewer trying to write".

## Authoring from a known request

When you already know exactly what request and assertions you want, start from the request instead of a behavior description:

1. Build and send the request in the [API Playground](https://qodex.ai/docs/api-testing-playground.md) until it works, then save it.
2. Open the endpoint in the API catalog (**API** under **Context** in the sidebar) and click **Generate tests**. Qodex opens a new chat grounded on that endpoint.
3. Spell out the steps, captures, and expectations you want, for example: "one step, expect 201, capture `$.id` as `userId`, assert `$.email` equals the email sent."
4. Review the saved draft in **Scenarios** and promote it when it looks right.

Auto-verification runs on save, the same as for any other scenario.

## Rename a scenario

Open the scenario in **Scenarios**, hover its title in the detail panel, and click the pencil icon (**Rename scenario**). Type the new name and press Enter or click **Save**. Press Escape or click **Cancel** to keep the old name.

A name cannot be empty. Renaming does not change the scenario's steps, status, or run history.

## Delete scenarios

To permanently remove one or more tests, open **Scenarios** and either select the rows you no longer need or open the scenario detail. Click **Delete**, then confirm **Delete** in the dialog.

> [!WARNING]
>
> Deleting a scenario cannot be undone. Use the draft status when you only want to keep a test out of scheduled runs while you revise it.

## Remove a scenario data file

Open the scenario detail, select **Data**, click **Remove** next to its CSV file, and confirm the removal. The CSV is deleted from storage, so download it first if you need to reuse it.

## Combining AI and manual edits

Click **Edit** on a scenario to open a chat scoped to it. The agent walks you through what the scenario currently tests and asks what to change: the body, a header, the auth, or an assertion. It reads the current shape and edits on top instead of regenerating from scratch.

Common pattern: let the agent scaffold the structure, including steps, captures, and basic expectations. Then hand-edit the values and assertions that depend on your business rules.

## Auto-verification

API scenarios run against the target environment the moment you save them. The verdict attaches to the row immediately. See [Auto-verification on save](https://qodex.ai/docs/api-testing-auto-verification.md) for what is checked and what is not.

## Inspect a run's request and response

Open a test run and expand an API step to see its URL, request headers, request body, response status, response body, and assertions.

* **Long response bodies**: the step keeps a preview of the response. When the body was cut, the step says so, for example "Preview, first 2,000 of 48,113 chars." Click **Show full response** to load the whole body from the step's saved artifact. Assertions always run against the whole response, never the preview.
* **Copy the request or response**: under **API request / response (redacted)**, switch between **Request** and **Response**, then click the copy icon to copy that JSON. Sensitive headers and body fields are redacted.

Long bodies with no spaces wrap inside the panel instead of running off the side.

## On the roadmap

> [!TIP]
>
> Self-critique on save (intelligence track): a flagship LLM reviewer reads every generated scenario against its stated goal and endpoint context, returns a structured verdict (`approve`, `revise`, `reject`) and a strength score (0 to 100), and flags weak scenarios with issue lists in the scenarios sidebar. Advisory only, never blocks the save. The reviewer is a different role from the coordinator: plan before, judge after.

## Related

> [card] [Chaining and postscripts](https://qodex.ai/docs/api-testing-chaining.md)
>
> Reference earlier-step outputs in later steps.

> [card] [Test rules in plain English](https://qodex.ai/docs/api-testing-test-rules.md)
>
> Assertions written in English, executed as JavaScript.

> [card] [Request data generation](https://qodex.ai/docs/api-testing-request-data-generation.md)
>
> How Qodex fills params, headers, and bodies.

> [card] [Auto-verification on save](https://qodex.ai/docs/api-testing-auto-verification.md)
>
> The verdict that attaches the moment you save.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.