Chain requests in a test suite

Build a suite of ordered steps, run it and read the result.

In short

A test suite runs saved requests in order, as cases, so a later case can use a value an earlier one read - sign in, create an order, then check it. Each case can have its own parameters, checks, retries and timing. The result says which case broke and why.

Before you start

Who: building a suite needs Edit on the project; running it needs Run. View reads results.
Plan: every plan. Each request a run sends counts toward your allowance.
First: save the requests the suite will call, and choose the environment.

Steps

Open "Test" with a project selected - it opens on "Suites" - and press "New suite". Give it a "Name"; "First steps (optional)" lets you tick saved requests now. With no suite yet, "Use a template" starts from a ready one.
Press "Add steps", tick saved requests in the order they should run, and add them as steps.
Open a step to set its parameters, expectations and timing.
Choose an environment for the run, or leave each step on its own default, and press "Run suite".

Result: the head line shows passed, failed and skipped cases and the total time; each case lists its checks, with the actual value when one failed.

Cases and parameters

A step starts as a copy of a saved request. Parameters add query values for this step only, and a method or body override changes what is sent, so one request can appear several times with different parameters. A saved request's "Used in suites" tab adds it to a suite with "Add to a suite".

"Run this step" turns a case off without deleting it.
"Always run" marks a cleanup step that runs even when an earlier step failed.
Retries, retry delay, delay before and timeout apply to this case only.
"Stop normal steps after the first failure", beside the steps on the suite's Details tab, stops the run when later steps make no sense after an earlier failure.
The suite's name and description are edited where they stand and save themselves when you leave the field. "Undo" in the message that follows puts them back.
"Remove step" takes the case out at once; "Undo" in the message that follows puts it back in its old place. The saved request itself stays in the project.

Run a suite

Cases run in order, and a failed case is retried as configured before it counts as failed. A suite can also run once for each row of a data set (/help/api-testing/variables#data-sets), on two environments side by side (/help/api-testing/variables#compare-environments), or from your pipeline (/help/api-testing/run-in-a-pipeline). A step can wait up to 60 seconds for a webhook to reach a project's webhook inbox (/help/api-testing/quality-view#webhook-inbox).

Read the result

Values passed forward appear under the case that kept them.
"Analyze" compares a failed case with the ones that passed and points at the value that differed, with a confidence score.
"Run history" keeps every run.
"Run in CI…" is in the screen's … menu. See /help/api-testing/run-in-a-pipeline.
What happens next: the run is kept in "Run history" and turns the suite and its requests green or red on boards and Home.

If something goes wrong

A later case fails because an earlier one failed: turn on "Stop normal steps after the first failure", or mark cleanup steps "Always run".
A case uses {{name}} as text: the earlier case did not keep the value. Check its "Keep a value" path.
"This data set would send more than 2,000 steps in one run.": use fewer rows or steps.
"A test case can appear only once in the order." and "A suite can only contain requests from its own project."
"Retry count must be between 0 and 3." and "Retry delay must be between 0 and 30000 milliseconds.": change the case's retries.
"Step delay must be between 0 and 300000 milliseconds." and "Step timeout must be between 1 and 300 seconds.": change the case's timing.
"A step waits for a webhook between 1 and 60 seconds.": shorten the wait.

/help/api-testing/suite-checks
/help/api-testing/record-a-suite
/help/api-testing/run-in-a-pipeline
/help/api-testing/start-from-a-template