Automation

Command line and CI

Run performance tests and collection runs from a pipeline and fail the build when an API breaks or gets slower.

Build tests without the desktop app

Everything works from the command line, with a window when you want one:

# In your repository: api-tests/ with a starter request, and a GitHub Actions pipeline
npx apitestcenter init "Orders API"

# Open the app in your browser, working directly on api-tests/ — build requests, checks, run order
npx apitestcenter ui --data api-tests

ui starts the app on your computer (only reachable from this computer) and opens it in its own window — the same screens as the desktop app, with nothing to install. What you save goes straight into api-tests/. Press Ctrl+C in the terminal to stop: the window closes with it. Closing the window stops it too. Then git commit. Without --data it opens the app's usual data folder.

The window is an app window of Microsoft Edge, Google Chrome or Brave, whichever is installed — no tabs or address bar. Without any of them it opens a tab in your usual browser instead; a browser doesn't let a page close its own tab, so when you stop ui the tab shows APITestCenter was stopped and you close it.

  • ui "Orders API" opens Run collection with that collection picked.
  • ui --browser opens a tab in your usual browser instead of a window.
  • ui --no-open opens nothing; it prints the address to open yourself.

A few things stay desktop-only: secrets typed into requests or secret environment variables last only until you stop ui (use {{variables}} and --var for tests you commit), there is no automatic update, and usage counts are never sent.

init creates, in api-tests/:

  • a collection (the name you give, or My API) with one request, Health check — GET {{baseUrl}}/health with a check that the status is 2xx;
  • a Local environment with baseUrl = http://localhost:3000;
  • README.md — what to run, and how to pass secrets;
  • .github/workflows/api-checks.yml (at the repository root) — runs the collection on every push.

init --data <folder> uses another folder instead of api-tests, and creates it if needed. init never overwrites: it stops if the folder already has saved requests, and leaves an existing pipeline file alone.

Running tests

# Send every request in a collection once and check each one
npx apitestcenter suite "Orders API" --env UAT --junit results.xml

# Run a saved request's performance test with pass/fail targets
npx apitestcenter run "Orders API/List orders" --env UAT --preset smoke --p95 500 --errors 1 --junit results.xml

Both use the same engine, checks, and rules as the app, so a pipeline run and a run in the app mean the same thing. They read your saved requests, environments, and collection run order. Two names for the same tool: apitestcenter and the short atc.

How you run itCommand
With the desktop app installedatc suite … — the app includes the command line (see below)
No install (CI, a quick try)npx apitestcenter suite … — always use the full name with npx: npx atc would look for a different npm package called "atc"
Installed once on your computernpm install -g apitestcenter, then atc suite … (or apitestcenter suite …)
In a project (devDependency)npm install -D apitestcenter, then npx apitestcenter suite … inside that project

Updating. The desktop app's atc updates with the app. A global install: npm install -g apitestcenter@latest. A project install: npm install -D apitestcenter@latest in that project — a project keeps the version it installed until you update it, so npx apitestcenter --version there can be older than your global atc. Pin the version in CI for repeatable builds.

The command line in the desktop app

The desktop app comes with atc, the same version as the app, using the app's own runtime and k6 — no Node.js needed.

Installed withatc in a terminal
Windows installerAdded to your PATH. Open a new terminal after installing. Uninstalling takes it off again. Settings → Command line says whether atc is on your PATH and which version runs when you type it; if it isn't on PATH (PATH edited since, or an install from before atc shipped), Install atc puts it back — for your Windows account, no administrator needed. When an older atc from npm comes first, it says New version available: Update brings npm's up to the app's version, and Use the app's copy puts the app's first.
Linux .debLinked as /usr/bin/atc
macOSLink it once: sudo ln -s "/Applications/APITestCenter.app/Contents/Resources/bin/atc" /usr/local/bin/atc
Windows portable, AppImage, Microsoft StoreNot added to PATH — use npx apitestcenter …, or npm install -g apitestcenter

If you also installed it with npm install -g, the one earlier in your PATH runs; atc --version tells you which version that is.

Requests that use the practice API ({{practiceApi}}) run from the command line too: suite and run start it on a free port of this computer when a request needs it.

Requirements (npm package): Node.js 20 or later. suite needs nothing else. run uses k6: if it is not installed, the first run downloads the official k6 release once, checks it against k6's published checksums, and keeps it in a cache folder. Set K6_BIN to use your own k6.

Commands

CommandWhat it does
ui [collection]Open the app in your browser to build and edit tests
init [collection]Start api-tests/ in this repository, with a CI pipeline
suite <collection>Send every request in a collection once and check each one
run <request>Run a performance test of one request
listList saved requests (as Collection/Name) and environments
`import <file \folder>`Import into the data folder, as Import requests does in the app: a Postman, Insomnia, Bruno, OpenAPI, .http, Hurl or HAR file, an APITestCenter collection file, or a folder of them (a Bruno collection's folder). --collection <name> names the collection
import template:<name>Start from a template: ready-made requests that run straight away against the practice systems built in. templates lists them
mock <collection>Answer the collection's requests with their example responses, until Ctrl+C — see Mock server. --port (default 4010)
mcpLet AI agents (Claude Code, Cursor, VS Code, Claude Desktop) use the app — see AI agents (MCP). --allow-load host,…

<collection> is the collection's name, or a folder inside it as Orders/Admin — a folder runs with its subfolders. suite "" runs the saved requests that are in no collection. Folder auth, headers and variables apply, as in the app.

<request> is a saved request, found by:

  • "Collection/Name" — always works; inside a folder, "Orders/Admin/Get user";
  • its name alone — only when no other saved request has the same name;
  • its id;
  • or a path to a .json file holding a request.

Run list to see the exact names. Put names with spaces in quotes.

run uses the request, its checks, Run first, and Test data as saved in the app. It does not use the Performance tab or the Goals tab: the load comes from --preset (default smoke) and the load options, and the pass/fail goals come from the target options below. Goals set in the app are remembered on that computer only.

Goal in the app (Goals tab)On the command line
p95 must stay under (ms)--p95 <ms>
p99 must stay under (ms)--p99 <ms>
Error rate must stay under (%)--errors <percent>
Checks must pass at least (%)--checks <percent>
Stop the test early if a target is clearly missed--abort

Exit codes

Codeatc suiteatc run
0Every request passedEvery target met and the result is not failing
1A request failed or could not runA target was missed or the result failed
2Could not start: unknown collection or environment, bad argumentsCould not start: bad arguments, an unknown request, a missing variable, the check request not 2xx, k6 could not be found or downloaded

Running it with no command prints the help and exits with 2. Pressing Ctrl+C once stops the run and still gives a result; pressing it twice quits at once with 2.

A pipeline step that runs atc fails on any code other than 0 — that is how a broken or slow API stops a release.

Options

Where your requests are

OptionMeaning
--data <folder>The app's data folder, or a copy of it in your repository. Default: this computer's APITestCenter folder (see Where your files are), or the folder in the ATC_DATA_DIR environment variable when it is set
--browserui: open a tab in your usual browser instead of an app window
--no-openui: open nothing (it prints the address)

Variables (suite and run)

OptionMeaning
--env <name>The environment for {{variables}}
--var key=valueSet or override a variable (repeatable) — use this for CI secrets

Client certificates (suite and run) — certificates saved in the app (same data folder) are used too

OptionMeaning
--cert host=cert.pem,key.pemPresent this certificate to host (repeatable). host is like api.example.com, *.example.com or api.example.com:8443.
--cert host=client.pfxThe same with a PFX or P12 file
--cert-passphrase <text>The passphrase of an encrypted key or PFX. In CI, set ATC_CERT_PASSPHRASE instead.

Collection runs (suite)

OptionMeaning
--stop-on-failStop at the first request that fails
--rows <file.csv>Run the collection once per row of the CSV; each column is a {{variable}}. See Once per row of a spreadsheet

The order and the left-out requests come from the run order saved in the app.

Load (run)

OptionMeaning
`--preset smoke\load\stress\spike\soak\breakpoint`The test type (default smoke: 2 users for 30 seconds). breakpoint adds users until a target breaks, so it exits 1 unless it never broke; the output says the most it handled
--vus <n>Simulated users
--duration <30s>How long the load lasts
--ramp-up <10s> · --ramp-down <0s>Time to reach full load, and to come back down
--rps <n>Drive by requests per second instead of users
--max-vus <n>With --rps: the most users k6 may start to keep the rate
--no-checkSkip the single check request before the load starts

Any load option turns the preset into a custom load, starting from the preset's values.

Targets (run, pass/fail)

OptionMeaning
--p95 <ms> · --p99 <ms>95% (or 99%) of requests must answer within this time
--errors <percent>At most this share of requests may fail
--checks <percent>At least this share of checks must pass
--abortStop early when a target is clearly missed

Compare with a baseline (run)

OptionMeaning
--baseline <file>Compare with a saved report and fail if it got slower — see Did it get slower?
--max-slower <percent>How much slower than the baseline is allowed (default 10)
--save-baseline <file>Save this run as the baseline for later runs

Output

OptionMeaning
--junit <file> · --html <file> · --json <file>Write the report (suite and run)
--saverun: also keep the run in History in the data folder
--quietOnly the final summary
-h, --helpPrint the help
-v, --versionPrint the version

Did it get slower?

Fixed goals (--p95 500) catch an API that is slow. A baseline catches an API that got slower than it was — even while it is still under the goal.

# On your main branch: save a good run as the baseline
npx apitestcenter run "Orders API/List orders" --data api-tests --env UAT --save-baseline api-tests/baseline.json

# On every deployment: compare with it, and fail if p95 is more than 10% slower
npx apitestcenter run "Orders API/List orders" --data api-tests --env UAT --baseline api-tests/baseline.json --max-slower 10
compared with baseline “List orders” (2026-10-02)
  After is 18% slower: 95% of requests within 142 ms → 168 ms. That is more than normal run-to-run variation.
  ✕ 18% slower than the baseline (p95 142 ms → 168 ms), more than the 10% allowed

The run fails (exit code 1) when p95 is slower by more than --max-slower percent (default 10), or when more requests fail than in the baseline. Differences under 5% or 10 ms count as the same. If the baseline used different load or a different request, the comparison is skipped instead of judged. With --junit, the comparison is its own test case, so the reason shows in your CI's test results.

Any exported JSON report works as a baseline — from the app (Export → JSON) or from --save-baseline.

Secrets in a pipeline

Secrets saved in the app are encrypted with your computer's key, so a build agent cannot read them. Write {{token}} in the request and pass the value from your CI's secret store:

npx apitestcenter suite "Orders API" --env UAT --var token=$ORDERS_TOKEN --junit results.xml

Examples

GitHub Actions

- name: API checks
  run: npx apitestcenter suite "Orders API" --data api-tests --env UAT --var token=${{ secrets.ORDERS_TOKEN }} --junit atc.xml
- uses: actions/upload-artifact@v4
  if: always()
  with: { name: api-checks, path: atc.xml }

GitLab CI

api-checks:
  script:
    - npx apitestcenter suite "Orders API" --data api-tests --env UAT --var token=$ORDERS_TOKEN --junit atc.xml
  artifacts:
    when: always
    reports:
      junit: atc.xml

Azure DevOps

- script: npx apitestcenter suite "Orders API" --data api-tests --env UAT --var token=$(ORDERS_TOKEN) --junit atc.xml
- task: PublishTestResults@2
  condition: always()
  inputs: { testResultsFormat: JUnit, testResultsFiles: atc.xml }

Your requests in the repository

A pipeline can't see the app on your computer, so keep a copy of what it needs in your repository. The easy way: Run collection → Download for CI gives you a zip with the collection (no secrets) and a ready pipeline — see step 3 of the walkthrough. By hand: copy the requests folder, environments.json, and suites.json from your data folder (About → Open folder) into, say, api-tests/, and run with --data api-tests.

Secret values are never in those files, so they are safe to commit; pass secrets with --var. Update the copy when you change requests in the app.

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