Testing APIs
Checks — deciding what a correct answer is
A check (or assertion) is a rule a correct answer must follow. Which checks to write, how strict to be, and how scripts go further when a rule needs code.
A check — in many tools called an assertion — is a rule a correct answer must follow: the status is 201, total is more than 0, the answer arrives within 500 ms. A test is a request plus its checks. Without checks, a tool can only tell you the request got an answer; with them, it tells you the answer was right.
The kinds of check
| Check on | Example rule | Catches |
|---|---|---|
| Status | is 200; is 2xx; is 201 | Failures, wrong success codes |
| A field's value | status equals "paid" | Wrong data |
| A field exists / doesn't | data.token exists; errors does not exist | Missing data, hidden errors |
| A number | total is more than 0; quantity is less than 100 | Nonsense values |
| A type | price is a number; items is an array | "45" instead of 45 |
| A length | items has length > 0 | Empty lists |
| A pattern | id matches ^A-\d+$ | Badly formed ids, dates, emails |
| The body | contains "inStock"; is valid JSON | Error pages, HTML instead of JSON |
| A header | content-type contains json; x-powered-by does not exist | Wrong formats, leaking server details |
| The time | within 500 ms | Slowness |
| The shape | matches a JSON schema | Renamed, missing or retyped fields |
How strict should a check be?
Too loose, and broken answers pass. Too strict, and correct answers fail — and people learn to ignore red tests.
- Check what must be true, not everything that happens to be.
itemshas length> 0survives a new product being added;itemshas length12breaks the day someone adds one. - Don't check values that change every time — timestamps, generated ids, prices that update — for equality. Check their type or pattern instead:
createdAtmatches^\d{4}-\d\d-\d\d. - Check the thing the test is about. A test of "create an order" should check the order was created (
201, anid, the rightproductId) — not the customer's address. - Always check the status, and at least one thing in the body. That pair catches most "fast but wrong" answers, like a
200with an error inside. - Time checks need headroom. If an answer usually takes 80 ms, a 100 ms limit fails on a busy afternoon. Pick a number that means too slow for a person, like 500 ms or 1 s.
Many checks, one answer
A request can have many checks, and each one is reported separately. That matters: "3 of 4 checks passed — $.items[0].price should be number" tells you exactly what broke, where "test failed" doesn't.
When a rule needs code: test scripts
Some rules don't fit a single check: the total is the sum of the line items; every item in the list is in stock; the dates are in order. For those, tools let you write a short test script. In APITestCenter (and Postman) it looks like this:
pm.test("total is the sum of the items", () => {
const order = pm.response.json();
const sum = order.items.reduce((s, i) => s + i.price * i.quantity, 0);
pm.expect(order.total).to.equal(sum);
});
pm.test(name, fn) is one named check; inside it, pm.expect(value).to… states the rule. Reach for scripts when a check can't say it — simple checks are easier to read later.
Checks under load
The same checks can run on every request of a load test. That turns "the API handled 500 requests a second" into "the API handled 500 requests a second and 99.8% of the answers were correct" — because under pressure, APIs don't only slow down; some start answering wrongly: empty lists, timeouts disguised as errors, someone else's data from a broken cache.
Key takeaways
- A check is a rule a correct answer must follow — status, values, types, lengths, patterns, headers, time, shape.
- Be strict about what must be true, loose about what may change; check type or pattern for values that vary.
- Use test scripts for rules a single check can't express — and run your checks under load too.