API Contract Testing

Contract source

The task, its acceptance criteria and the spec document first; then the repo's OpenAPI file or README API docs (the named boot-docs exception). Never the handler source — a contract derived from the implementation only proves the implementation matches itself.

Request template

curl -sS -D "$QA/h.txt" -o "$QA/b.json" -w '%{http_code} %{time_total}s\n' -X POST "$BASE/api/tasks" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"title":"qa-T-12 a"}'; jq . "$QA/b.json"  # no jq (stock Windows, some Linux): read_file the body instead

Per changed endpoint, the matrix

One case each, mapped to the category enum:

Case	Category
2xx happy path	happy_path
400/422 for invalid body, with the error payload shape	negative
401 no token	auth
403 other user's resource (BOLA: create as A, read/update/delete as B)	auth
404 unknown id	negative
409 duplicate where uniqueness is implied	negative
405 wrong method	negative
extra unknown/privileged field ignored, e.g. "role":"admin" (mass assignment)	auth
pagination edges (limit 0, max, max+1)	boundary
idempotency: PUT/DELETE twice, POST with Idempotency-Key twice when claimed	negative
content-type (missing, wrong)	negative

Compatibility

Existing fields keep their name, type and nullability. A removed or renamed field is a break unless the task explicitly asks for it. Compare against the OpenAPI file, or a request to the same endpoint on stage/the default branch.

Side effects

Verify them the same way backend-manual-testing does — a 2xx with the wrong DB row or missed outbound call is a FAIL, not a pass with a note.

Optional depth: schema fuzzing

Local boot only, and only when the repo ships an OpenAPI file:

uvx schemathesis run <openapi> --url <base> -H "Authorization: Bearer $TOKEN" --include-path-regex '<changed path>' --checks not_a_server_error,status_code_conformance,response_schema_conformance --max-examples 20 --max-failures 5

Scope it to the changed paths with --include-path-regex. Never run it against stage or anything shared — it generates many writes.

Worked Example

"POST /tasks title ≤120 chars": happy path (120 chars, 201); empty title (422); 121 chars (422); no auth (401); another user's project (403); duplicate title where unique (409 or 201 per spec); wrong Content-Type (415/400); unknown field is_admin:true ignored (201, field absent from response) — 8 cases, each with its expected code recorded before running it.

Red Flags

• Asserting only the status code and never the body shape.
• Testing authz with the same user for both sides of a BOLA case.
• Fuzzing a shared environment (stage, a shared database).