Testing APIs

Run a collection

Send every request in a collection once, in your order, and see which passed and why the others didn't — a functional test of a whole API in one click.

A performance test asks “is one request fast enough under load?”. A collection run asks “does every request still work?” — usually the first thing to check after a release.

Run one

Click ▶ next to a collection in the saved-requests list, or open Run collection in the sidebar.

  1. Pick the Collection and the Environment. Every folder is listed; running a folder runs its subfolders too, and each request gets its folders' auth, headers and variables. No collection holds the saved requests that are in no folder.
  2. Check the run order. Untick a request to leave it out; use the arrows to move it. The order is saved for next time and for the command line.
  3. Optionally tick Stop at the first failure.
  4. Press **Run N requests** (N counts the ticked ones). Stop ends the run after the current request.

Results appear as each request finishes, in place of the run order. Failed requests open by themselves, showing why, the checks, and the start of the answer. Open this request takes you to it in the editor.

When the run is done, Edit the run order (under the results) brings the run order back so you can change it and run again.

What passes

ResultWhen
PassedEvery check passed. Without checks: any 2xx or 3xx status.
FailedA check failed (the message names which), the status was 4xx/5xx with no checks, or a value to save was missing from the answer.
Could not runNo answer at all, a {{variable}} with no value, a missing saved secret, or the Run first request failed.
SkippedLeft out of the order, or not reached because the run stopped.

The run passes only when something ran and nothing failed or could not run.

A real flow: create, read, delete

Collections shine when requests depend on each other. For an Orders API:

  1. Sign in — used by the others as Run first. It runs once for the whole collection run.
  2. Create order — Save values: id as {{orderId}}.
  3. Get order — GET {{baseUrl}}/orders/{{orderId}}, with a check that status equals new.
  4. Cancel order — DELETE {{baseUrl}}/orders/{{orderId}}.

If Create order fails, Get order and Cancel order say they could not run because {{orderId}} should have come from it — so you look at the real cause first. See Save values.

Once per row of a spreadsheet

To check many records the same way (every employee in a list, every order of a migration), run the collection once per row of a CSV file:

  1. Make a CSV whose first line names the columns, for example employeeId,expectedTitle, with one row per record under it. Excel and Google Sheets save CSV.
  2. On Run collection, press Choose a CSV…. The page shows the rows and the {{variables}} the columns give.
  3. Run. Every request runs for row 1, then for row 2, and so on, with that row's values: {{employeeId}} is the row's employee.

The results are grouped by row, each marked passed or failed, with its first values (employeeId=E1004, expectedTitle=Engineer), and the summary counts both: 2 of 3 rows passed · 5 of 6 requests passed.

  • Each row starts afresh: values a request saves are used by the requests after it in the same row, never by the next row.
  • A request that runs first (a sign-in) runs once and is reused by every row.
  • A column wins over an environment variable with the same name.
  • Stop at the first failure stops the whole run, not only the row.
  • Up to 1,000 rows. A column name must work as a {{variable}}: letters, digits, _, . or -.
  • From the command line: atc suite "My collection" --rows employees.csv (see the command line).

Save the result

After a run, save it as:

  • HTML — one page that opens anywhere and prints well;
  • JUnit — XML with one test per request, for CI dashboards (Jenkins, GitLab, Azure DevOps, GitHub);
  • JSON — every detail, for your own tools.

The files show the URL as you wrote it ({{baseUrl}}/orders/{{orderId}}), never the filled-in values, so tokens don't leak into reports.

On a schedule

At the bottom of the page, Scheduled checks runs the collection again and again while the app runs: pick How often (every 5 minutes to every day) and Notify me, then Schedule it. It uses the environment chosen above, and its first run starts at once.

Notify meYou hear about it
When it starts failing, and when it's fixed (the default)The first failed run after passing ones, and the first passing one after failures.
Every failed runEach failure, and the fix.
Every runAll of them.
NeverOnly here, in the list.

A notification is a message in the app and, when the app isn't in front, a desktop notification: Turn on desktop notifications in the panel if you haven't. It says what failed and why: Orders API started failing. 11 of 12 passed · 1 failed — Create an order: status is 201 (got 500).

Each scheduled check shows its last 20 runs as green and red bars (hover one for its time and result), when it runs next, and the last failure in full. Run now runs it at once, Pause stops it without losing its results, and a click on its name changes how often and when it notifies. Runs happen one at a time, the last 100 results of each are kept in schedules.json in the project, and a schedule follows its folder when you rename or move it.

When you close the window

In the desktop app, closing the window while a scheduled check is on — or a collection run is going — leaves the app running in the system tray (the menu bar on macOS), so checks keep running and still notify. Click the tray icon to open the window again; its menu has Quit APITestCenter. With nothing running, closing the window quits as usual.

Settings → Running in the background changes this, and Start with Windows opens the app straight into the tray when you sign in, so checks run without opening it. More: In the tray.

Checks run only while the app runs: after the computer sleeps or the app quit, a check that's due runs once when it's back, not once for every interval missed. For checks around the clock, use a pipeline: the one Download for CI makes (below) has an hourly schedule: ready to turn on.

In a pipeline

Download for CI (next to Run) gives you a zip that unzips into the root of your repository:

In the zipWhat it is
api-tests/requests/, api-tests/environments.json, api-tests/suites.jsonThis collection's saved requests (plus any Run first request kept in another collection), your environments, and the run order. Secret values are never included.
api-tests/README.mdThe command to run, and how to pass secrets with --var. If a request has a secret typed straight into it (not a {{variable}}), the README lists those requests: change them to use a variable, or they won't run in CI.
.github/workflows/api-checks.ymlA GitHub Actions pipeline that runs the collection on every push and keeps atc-results.xml as a build artifact.

After the download, a message says whether any request has a secret typed in. See From the app to your pipeline. The same runner works from the command line — npx apitestcenter suite "Orders API" --env UAT --junit results.xml — and exits with 0 when everything passed. See Command line and CI.

Something unclear or missing? Write to support@apitestcenter.com — the guide improves with every question.