Testing an API

API Studio

API Studio > Test > Test suites on an API holds the test cases for one version. A test case is a request and the checks its answer must pass. You can run one case or a suite of cases.

Editing test cases and suites needs the API design permission. Running them needs the API test permission. Anyone who can view the API can read the results.

Pick a run target

Under Run target, pick where runs are sent:

• Design preview: answers come from Sample responses. Enter a test key in Test key. See Testing with Sample responses.
• An environment: each environment where this version is deployed is listed by name. Runs call the deployed flow. Enter an API key for that environment in API key.

Test runs count as test traffic. They appear in the call log as test calls and are not billed or counted against your call allowance.

The key is used for the run only. It is not saved with the test case.

Saved test cases

1. Press New case.
2. Enter a Name, the Method and the Path, for example /orders/42.
3. Optionally enter Query (JSON), Headers (JSON) and Body (JSON) as JSON objects.
4. Tick Send without a key to check how the API answers a request with no credentials.
5. Add assertions with Add assertion.
6. Press Save case.

Each assertion is one of these:

Assertion	Passes when
Status	The answer has the expected status code.
JSON Schema	The response body matches the JSON Schema.
JSONPath equals	The value at the JSONPath, for example $.items[0].id, equals the expected value.
JSONPath exists	The JSONPath points to a value in the body.
Header present	The response has the header. Header names are not case sensitive.
Header equals	The response header has the expected value.

Press Edit or Delete on a saved case to change or remove it.

Generated contract tests

Press Generate contract tests to build cases from the version's published document. Each operation gets:

• One positive case, built from the operation's examples. It checks the declared success status, the response schema and the required response headers. A 201 answer must carry Location. On a deployed environment it also checks ETag when caching is on and the RateLimit header when rate limit headers are on.
• Negative cases: a missing required field, a wrong type, a value longer than its maximum length, and a request without a key. Each expects the declared 400, 401 or 422 answer in the Problem Details (RFC 9457) shape, with type, title and status.

Generating again replaces the generated cases for the version. Saved cases stay as they are.

Generated cases are read only. Press Copy to saved to make an editable copy.

Suites

A suite is a named set of test cases.

1. Tick the cases in the Saved and Generated lists.
2. Enter a Suite name.
3. Press Save selected as suite.

Press Run suite to run every case in it. Press Delete to remove a suite. The cases stay.

Read the results

Press Run on a case or Run suite on a suite. Results shows:

• the run status: Passed, Failed or Error;
• how many cases passed, the target and the time taken;
• for each case, the HTTP status and every assertion that failed, with the expected and actual values.

Recent runs lists earlier runs for the version. Press View to open one.

Your administrator sets the time limit per request, how many cases run at once and the largest suite.