P0 · Chapter 04 / 15

API / HTTP testing

The 60-second cheat sheet#

An API test validates a transport contract and business effects at a service boundary. HTTP success is evidence of request handling, not necessarily final workflow success. Read the OpenAPI/requirements, assert the specified status and runtime body, check permissions and side effects, then clean owned test data.

HTTP decision tables#

Authentication establishes identity, authorization decides permitted actions. A valid token for user A must not authorize reading B's records. Test object-level permissions, not just “token present.” Error messages must not leak secrets or internal details.

Anatomy, schema and test design#

Method + path + query + headers + body describe a request. A path ID identifies a resource; query parameters filter/paginate. Validate Content-Type before assuming JSON, required fields/types, business invariants and error shape. A TypeScript DTO describes expectations only; optional Zod/Ajv can validate runtime schema but are not dependencies of this website.

Cursor pagination needs stable ordering and no duplicates/gaps across pages; offset pagination can shift under concurrent writes. At awareness level, ETag + If-None-Match supports conditional reads, while If-Match can prevent lost updates if the API implements it. Verify caching does not expose private cross-user data.

POST → GET with cleanup#

// tests/api/users.spec.ts: complete test; hypothetical authorized test APIs.
import { test, expect } from '@playwright/test';
import { randomUUID } from 'node:crypto';
test('created user can be fetched', async ({ request }, testInfo) => {
  const correlation = randomUUID();
  const created = await request.post('/test-support/users', {
    data: { name: `QA-${correlation}`, correlation },
  });
  expect(created.status()).toBe(201);
  const data: unknown = await created.json();
  if (!data || typeof data !== 'object' || !('id' in data) || typeof data.id !== 'string') {
    throw new Error('Creation did not return a string id');
  }
  const id = encodeURIComponent(data.id);
  let primaryFailed = false;
  try {
    const fetched = await request.get(`/api/users/${id}`);
    expect(fetched.status()).toBe(200);
    expect(await fetched.json()).toMatchObject({ id: data.id, name: `QA-${correlation}` });
  } catch (error) { primaryFailed = true; throw error; }
  finally {
    try {
      const deleted = await request.delete(`/test-support/users/${id}`);
      expect(deleted.status()).toBe(204);
    } catch (error) {
      await testInfo.attach('cleanup-failure', { body: String(error), contentType: 'text/plain' });
      if (!primaryFailed) throw error;
    }
  }
});

Assumes configured baseURL/auth and a safe test-support contract. Cleanup covers failures after ID parsing. If creation commits but response/JSON is lost, use correlation lookup or supported idempotency to find the record; finally cannot clean an unknown ID. A cleanup API outage remains an outstanding resource leak: record it and use an authorized TTL janitor.

Direct calls, negatives and browser mocks#

// Scoped test body with request + expect. Illustrative contracts.
const invalid = await request.post('/api/users', { data: { email: 'invalid' } });
expect(invalid.status()).toBe(422);
expect(await invalid.json()).toMatchObject({ code: 'INVALID_EMAIL' });
const changed = await request.put('/api/profiles/owned-qa-user', { data: { displayName: 'QA' } });
expect(changed.status()).toBe(200);
const missing = await request.get('/api/users/nonexistent-qa-id');
expect(missing.status()).toBe(404);

.ok() accepts any 2xx; await expect(response).toBeOK() also checks success status, not the business body. A 202 PENDING is not VERIFIED. request.get/post/put/delete are real HTTP through APIRequestContext; page.route intercepts browser traffic only. API-first setup reduces cost; UI login/create tests remain when those interactions carry business risk. Postman is effective for exploration and sharing examples, Newman for collection CI; Playwright integrates typed fixtures, UI/API workflows and runner evidence. Neither tool substitutes for useful assertions.

Retry, concurrency and payments#

A client timeout means “outcome unknown,” not “server did nothing.” Before replaying a mutation, query by correlation/payment ID. An idempotency key helps only if the backend stores and enforces the key, payload consistency and deduplication window. In a sandbox, submit the same supported key twice and verify the same payment identity and one ledger effect; also test changed payload with same key and window expiry according to contract. Never replay real financial writes blindly.

Concurrent GETs can use Promise.all. Concurrent writes require a designed collision test, isolated resources and expected conflict behavior; do not accidentally create one through shared fixtures. Honor bounded retry policies only for classified transient failures. A returned HTTP 503 still needs status assertion; Promise rejection handling alone is insufficient.

Contract testing and traceability#

OpenAPI checks validate documented shape/status but may miss actual business semantics or compatibility expectations. Consumer-driven contracts record the interaction a consumer needs and verify providers satisfy it; they do not replace deployed integration checks. Trace Jira acceptance criteria → TestRail case/suite → automated test identifier → CI run/results → defect. TestRail runs execute selected cases; plans organize runs/configurations; reports support evidence. Vendor fields and integrations vary.

Wrong versus right and interview response#

30 seconds: “I derive API tests from the real contract: exact statuses, runtime schema, business rules and side effects. I cover negative and authorization paths, create unique data and fetch by returned IDs. For async acceptance I check final completion separately. I treat uncertain mutation outcomes as reconciliation problems before retrying.”

Memory hook: method + identity + shape + state + effect + cleanup.

Quick practice · reveal answers#

Official references and related topics#

Optional online further reading; all core study material is included above.

• API testing
• HTTP semantics RFC 9110

Back to library index