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.

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:

{
  "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:

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:

Build and send the request in the API Playground until it works, then save it.
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.
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.”
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.

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 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

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.

Chaining and postscripts

Reference earlier-step outputs in later steps.

Test rules in plain English

Assertions written in English, executed as JavaScript.

Request data generation

How Qodex fills params, headers, and bodies.

Auto-verification on save

The verdict that attaches the moment you save.

Get started

Concepts

PR review

API testing

UI testing

Security testing

Run tests

Autopilot

Findings

Memory

Skills

Integrations

Self-hosted

Account

API test scenarios

Scenarios

How a scenario is structured

Lifecycle: draft to active

Authoring from chat

Authoring from a known request

Rename a scenario

Delete scenarios

Remove a scenario data file

Combining AI and manual edits

Auto-verification

Inspect a run’s request and response

On the roadmap

Chaining and postscripts

Test rules in plain English

Request data generation

Auto-verification on save

​Scenarios

​How a scenario is structured

​Lifecycle: draft to active

​Authoring from chat

​Authoring from a known request

​Rename a scenario

​Delete scenarios

​Remove a scenario data file

​Combining AI and manual edits

​Auto-verification

​Inspect a run’s request and response

​On the roadmap

​Related

Chaining and postscripts

Test rules in plain English

Request data generation

Auto-verification on save

Scenarios

How a scenario is structured

Lifecycle: draft to active

Authoring from chat

Authoring from a known request

Rename a scenario

Delete scenarios

Remove a scenario data file

Combining AI and manual edits

Auto-verification

Inspect a run’s request and response

On the roadmap

Related