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 --browseropens a tab in your usual browser instead of a window.ui --no-openopens 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}}/healthwith 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 it | Command |
|---|---|
| With the desktop app installed | atc 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 computer | npm 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 with | atc in a terminal |
|---|---|
| Windows installer | Added 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 .deb | Linked as /usr/bin/atc |
| macOS | Link it once: sudo ln -s "/Applications/APITestCenter.app/Contents/Resources/bin/atc" /usr/local/bin/atc |
| Windows portable, AppImage, Microsoft Store | Not 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
| Command | What 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 | |
list | List 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) | |
mcp | Let 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
.jsonfile 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
| Code | atc suite | atc run |
|---|---|---|
| 0 | Every request passed | Every target met and the result is not failing |
| 1 | A request failed or could not run | A target was missed or the result failed |
| 2 | Could not start: unknown collection or environment, bad arguments | Could 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
| Option | Meaning |
|---|---|
--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 |
--browser | ui: open a tab in your usual browser instead of an app window |
--no-open | ui: open nothing (it prints the address) |
Variables (suite and run)
| Option | Meaning |
|---|---|
--env <name> | The environment for {{variables}} |
--var key=value | Set 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
| Option | Meaning |
|---|---|
--cert host=cert.pem,key.pem | Present this certificate to host (repeatable). host is like api.example.com, *.example.com or api.example.com:8443. |
--cert host=client.pfx | The 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)
| Option | Meaning |
|---|---|
--stop-on-fail | Stop 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)
| Option | Meaning | |||||
|---|---|---|---|---|---|---|
| `--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-check | Skip 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)
| Option | Meaning |
|---|---|
--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 |
--abort | Stop early when a target is clearly missed |
Compare with a baseline (run)
| Option | Meaning |
|---|---|
--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
| Option | Meaning |
|---|---|
--junit <file> · --html <file> · --json <file> | Write the report (suite and run) |
--save | run: also keep the run in History in the data folder |
--quiet | Only the final summary |
-h, --help | Print the help |
-v, --version | Print 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.