Testing APIs

Contract tests

Check every answer against your API's OpenAPI description — documented status, content type, body and headers — and see which operations have no test yet.

Your API's OpenAPI (or Swagger) file says what each operation answers: which statuses, in which content type, with what body. A contract test checks real answers against it. When the two differ, either the API broke its promise or the description is out of date. Both are worth knowing.

In APITestCenter a folder names an API description, and every request inside it is checked against that description: on Send, in collection runs, on the command line and for AI agents. You don't write the checks yourself.

Set it up

  • Import the OpenAPI file (Import in the status bar). Check answers against this description is ticked: the requests go in a new collection, and the file becomes that collection's API description.
  • Or add one yourself: Ctrl+K → API descriptions → A file… (or drop the file on the dialog), From a web address… (the app fetches it, through your proxy, trusting the same certificates as Send), Paste its text…, or Practice shop to try it. When an address can't be fetched — a sign-in in front of it, say — open it in your browser, copy all of it, and paste it.

Then, in the same dialog, four steps show how far it is set up:

  1. Added — the description, with its operations.
  2. A folder uses it — pick the folder with this API's requests, or A new folder… (named after the API), and Use it for this folder. A folder's settings can pick it too: ⋯ next to the folder → Folder settings → API description.
  3. Requests for its operations — the bar shows how many have one. **Add N missing requests** makes one for each operation that has none.
  4. Send or run — each answer is checked; the lines are on the answer's Checks tab.

The folder's requests should be calls to that API. Requests already in the folder stay as they are and count for their operation; a request whose path isn't in the description is listed under saved requests that aren't in the description — it stays, and its answer fails … is in “Shop”: either its path differs, or the description is missing it.

When a file isn't taken

The dialog names the file and says what it is instead: a Postman collection, a HAR recording or an Insomnia export (import those, with Import, to get their requests), an AsyncAPI file, a JSON Schema, or a file of its own kind, with the names it starts with. It shows a small description to compare with, and Download this sample saves it.

An API description is an OpenAPI 3 or Swagger 2 file, JSON or YAML, starting with openapi: 3… (or swagger: "2.0"), then info and paths. Most frameworks publish theirs at an address: /openapi.json (FastAPI, NestJS), /v3/api-docs (Spring), /swagger/v1/swagger.json (.NET). Add it with From a web address….

Folders inside inherit it, the way they inherit auth. An inner folder can name a different one.

What is checked

Each answer is matched to its operation by method and path. The host doesn't count, so the same description serves test, staging and production. The server's base path (/v1) is allowed for. So is a gateway's prefix in front of it (/shop-team/v1/orders), and a path that has its own literal part beats one with parameters (/orders/mine over /orders/{id}).

LineFails when
GET /orders/{id} is in “Shop”No path matches, or the path has no such method (the description has GET, PATCH for this path, not DELETE).
200 is a documented statusThe status isn't listed, and neither is a range (4XX) or default.
application/json is a documented content typeThe answer's Content-Type isn't one the description lists for that status (*/* and application/* count).
the body matches the documented schemaThe body differs from the schema, which says where: $.items[0].price should be number (it is string).
an answer with no body documented has noneThe description lists no content, but the answer has a body.
the documented headers are thereA response header marked required: true is missing.

A documented error is a pass: a 404 the description lists, with the body it lists, is what was promised. The schema rules are the JSON schema check's, with $refs to the file's own components (or Swagger definitions). References to other files aren't followed.

The contract lines count like any other check. A failed one fails the request in a collection run and the build in CI.

Which operations have a test

API descriptions lists every operation, which saved requests cover it, and the operations that have none — All, No request and Have one, with a search. **Add N missing requests makes one for each, the way an import does (example values, the status check), in a folder that uses the description; the folder's own Folder settings → API description** shows the same for that folder, with the button there.

The new requests go to {{baseUrl}}, in an environment named after the API. It's where the description says the API runs; when the description gives only a path (/RosterApi), the address it was fetched from fills in the rest, and otherwise the dialog asks: type it once, as https://…. Pick that environment before sending.

Keep it current

  • Replace the file… when the API changes; the folders that use it check against the new one at once.
  • Descriptions live in the project folder, in contracts/, as the file's own text, so with projects in Git a change to the contract shows in the diff next to the change to the tests.
  • Delete a description and the folders that named it stop checking; their other settings and the requests stay.

Performance tests don't check the contract: they run the request's own checks only.

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