Test Scenarios
Test scenarios chain existing test cases into a multi-step workflow — register a user, log in, create an order, verify it. Steps run sequentially, and each step can extract values from its response that later steps reuse. That makes scenarios the tool for end-to-end flows that a single request can't cover.
Where scenarios live
Open Test Runner from the sidebar. The left panel is split into two collapsible sections: Suites on top and Scenarios below. The search box above filters both sections at once, and each scenario shows a badge with its step count.
Use the + button on the Scenarios header (New scenario or folder) to create a New Scenario or a New Folder. Creating scenarios and folders requires the tests:write permission.
Creating a scenario
- In the Scenarios section, click + and choose New Scenario.
- Enter a Name (e.g.
User Registration Flow) and an optional Description. - Add Tags to organize and filter your test scenarios.
- Click Create Scenario.
Right-click a scenario for its context menu: Run Scenario, Rename, and Delete. Deleting a scenario also deletes all of its steps — the underlying test cases are untouched.
Organizing scenarios in folders
Folders keep large scenario collections navigable and can be nested. Each folder has a name and an optional icon; the context menu offers Rename / Edit, New Sub-folder, and Delete. Deleting a folder moves its scenarios and sub-folders to the parent (or to the root) — scenarios themselves are not deleted. Drag scenarios and folders to reorganize the tree; drag a folder onto the Drop here to move to root zone to un-nest it.
Building the step list
Selecting a scenario opens its detail view in the center panel. Until you add steps, you'll see No steps yet with an Add Your First Step button.
Adding steps
- Click Add Step.
- Pick a test suite — the dialog lists every suite with its case count.
- Search or browse the suite's test cases and click Add next to each case you want. The dialog stays open, so you can add several steps (from different suites) in one go.
A step is a reference to an existing test case, so its request, assertions, and response extractions are maintained in one place — edit the case and every scenario that uses it picks up the change.
Wait steps
Click Add Wait to insert a pause between steps — useful for APIs with eventual consistency or rate limits. Wait steps display their duration on the card (e.g. Wait 500ms). Click that label to change the duration (0–300000 ms).
A wait step counts as a step: it appears in the results table and in the run history as a row named Wait, carrying its duration, and it always passes. It has no request, so there is no detail view behind it.
Managing steps
| Action | How |
|---|---|
| Open the step | Click the step's name on the card — see The step dialog below. |
| Reorder | Drag a step by its handle to a new position. Steps always execute top to bottom. |
| Enable / disable | Toggle the switch on the step card. Disabled steps are dimmed and don't execute. |
| Delete | Click the trash icon on the step card. |
| Add a condition | Click the branch icon (or the Conditional badge) on the step card. |
The step dialog
Clicking a step's name opens everything that step is made of.
Step settings — the parts that belong to this step, all editable here:
| Setting | Notes |
|---|---|
| Test case | Change picks another case. The step keeps its position, condition and enabled state. |
| Duration | Wait steps only: 0–300000 ms. |
| Enabled | Same switch as on the card. |
| Condition | Opens the condition editor, with autocomplete over the variables earlier steps produce. |
Test case configuration — read-only, because a test case is shared: editing it would change every other scenario that uses it. Shown are the request's method and URL, the assertions, and the two variable sides:
- Variables in — every
{{variable}}the request and assertions reference, each with where it comes from: an earlier step (with the step number and the extracting path), or the environment. A variable that no earlier step sets is flagged — the common case being one that a later step produces, which only surfaces as a failed run otherwise. Reordering steps changes this immediately. - Variables out — what this step extracts for later steps, with its source path.
If the test case has a pre-request script, coverage is reported without warnings: a script can define variables that can't be detected by reading the request.
Passing values between steps
Chaining works through response extractions defined on the test cases you use as steps. When a step runs, its extractions store values as variables; any later step can reference them with {{variableName}} — in URLs, headers, bodies, assertions, or step conditions.
An extraction has a source, a path (where applicable), and a variable name:
| Source | What it captures | You provide |
|---|---|---|
| Response Body | A value from the JSON body, selected with a JSONPath expression | JSONPath (e.g. $.data.id) + variable name |
| Response Header | A specific response header's value | Header name (e.g. Authorization) + variable name |
| Status Code | The HTTP status code of the response | Variable name only |
The test case editor also offers quick-add buttons — Store Status Code, Store Header, and Store JSON Value — that create the corresponding extraction with one click. Extractions can be reordered and removed in the extraction table.
A typical chain: step 1 (POST /users) extracts $.id into userId; step 2 calls GET /users/{{userId}} and asserts on the result.
Conditional steps
Any step can carry a condition that decides — based on variables extracted by earlier steps — whether it executes or is skipped. Click the branch icon on a step card to open the Step Condition editor:
| Field | Meaning |
|---|---|
| Variable | The variable to test, in placeholder syntax — e.g. {{prevStatus}} or {{userId}}. |
| Operator | One of ==, !=, >, <, >=, <=. |
| Value | The value to compare against — e.g. 200. |
| When true | Whether a true comparison means execute this step or skip this step — the other branch always does the opposite. |
The editor previews the resulting rule, and steps with a condition show a Conditional badge. Use Clear to remove a condition. Skipped steps are reported with their skip reason in the results.
Switch to the JSON tab to write the raw condition instead — the same shape the API accepts:
{ "if": "{{prevStatus}} == 200", "then": "execute", "else": "skip" }A condition the builder can't express (anything other than {{variable}} <operator> value) opens in JSON mode automatically, so it stays intact. One comparison per condition — there is no AND/OR, and a condition the evaluator can't parse runs the step.
Running a scenario
- Pick the target environment with the environment selector in the scenario toolbar — every step uses that environment's base URL and authentication.
- Optionally open Run settings (the gear next to the run button) to change how the run behaves:
| Setting | Options |
|---|---|
| On Error | Stop (default) halts at the first failed step · Ignore runs every step regardless · Abort cancels the whole run. |
| Save run to history | On by default. Turn it off for a dry run — results stay in the Results tab and no entry is written to the run history. |
The settings are remembered and apply to both run entry points (toolbar button and the scenario context menu). 3. Click Run Scenario. Running requires the tests:execute permission.
Steps execute sequentially. A progress bar tracks completion, and each step card's colored left edge shows its live status:
| State | On the card |
|---|---|
| Queued | Waiting its turn — the card is dimmed with a muted edge. |
| Running | Blue edge, plus a spinner badge that updates in real time. |
| Passed | Green edge and a result pill with the status code and duration. |
| Failed | Red edge and a result pill naming the failed assertions. |
| Skipped | Yellow edge and a Skipped badge — hover it for the skip reason. |
| Pending | Amber edge and pill: the step's case is a contract test whose endpoint the environment doesn't serve yet. Not a failure — see Contract Testing. |
| Blocked | Muted edge and a Blocked pill: the target environment is read-only and this step's case writes, so nothing was sent. Not a failure either — see Test Suites for the switch and the exact refusal message. |
If the run ends before every step ran — On Error → Stop or Abort — the steps it never reached go back to showing no indicator rather than staying queued.
Running a scenario from its context menu in the sidebar (and through the API or an AI agent over MCP) executes the same run, but without live progress: the cards and the results table fill in once the whole run returns. That is deliberate — live progress needs the scenario open in the center panel — and not a stalled run.
Reading the results
The Results tab in the right panel shows the run as a run-overview table — one row per step, in execution order, that fills in live as the scenario runs:
- A status icon (queued, running, passed, failed, skipped, pending, blocked).
- The step name with the response's HTTP status-code badge.
- An inline failure reason (or skip reason) right on the row, so a red step explains itself without a click.
- Vars in — the variables the step consumed — and Extracted — the variables it captured for later steps.
- The step duration.
Above the table, a summary bar carries the passed, failed and skipped counts plus the total duration. Pending and blocked steps get their own counts there whenever a run produced any; neither is ever folded into the failed count. The completion toast reads the same way — "2 passed · 1 blocked" rather than a red run — and a scenario in which no step was ever sent comes back as a neutral notice instead of a success.
Click any row to load that step's full detail below the table — the resolved request, assertion results, response body, and every extracted variable. Routebase focuses the first failed step automatically, so a failing run opens on the step that broke.
Before the first run, the panel shows No results yet — "Execute the scenario to see step-by-step results here."
Run history
The History tab lists past scenario runs with their status, relative timestamp, pass/fail/skip summary, and duration. Click a run to load its full step-by-step results into the Results tab — useful for comparing a failing run against the last green one.
A stored run keeps three outcomes per step — passed, failed, skipped. Pending and blocked steps are recorded as failed there, because the distinction is not part of what a scenario run stores. A live run does draw it: run the scenario again to see which steps were never sent rather than genuinely broken.
A historical run is no longer a thinner version of the live one. Each step keeps its actual request — the resolved URL, headers and body — alongside the assertion results, the response body and its size, the extracted variables, and the pre-request / post-response script console output. Runs recorded before that shipped never stored those fields, so their step detail opens without the request and console sections. There is no backfill: the next run of the scenario carries the full record.
Related
- Test Suites — the test cases your steps are built from
- Test Data — fixtures and seeds to set up state before a flow
- Environments — the base URLs and credentials scenarios run against
- Data-Driven Tests — running one case across many data rows