API contract tests

Writes HTTP API tests that check status codes, response schemas, error shapes, auth and permission cases, idempotency and pagination while staying independent of database state. Use when asked to test a REST or JSON API.

TestingPack: Testing82 linesapi-contract-tests

Install

Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.

Claude Code — macOS, Linux
mkdir -p ~/.claude/skills/api-contract-tests && curl -fsSL https://anymodel.org/en/skills/testing/api-contract-tests/SKILL.md -o ~/.claude/skills/api-contract-tests/SKILL.md
Codex, Cursor — macOS, Linux
mkdir -p ~/.agents/skills/api-contract-tests && curl -fsSL https://anymodel.org/en/skills/testing/api-contract-tests/SKILL.md -o ~/.agents/skills/api-contract-tests/SKILL.md
Claude Code — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\api-contract-tests" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/testing/api-contract-tests/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\api-contract-tests\SKILL.md"
Codex, Cursor — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.agents\skills\api-contract-tests" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/testing/api-contract-tests/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\api-contract-tests\SKILL.md"

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/testing/api-contract-tests/SKILL.md

SKILL.md

Raw

API Contract Tests

These tests pin the promise the API makes to its clients: URL, method, status, body shape, errors. They should fail when the contract changes and stay quiet when the implementation changes.

Workflow

1. Find the contract and the conventions

  • Look for an OpenAPI or Swagger file, route definitions, type definitions, handlers and existing API tests. Treat the spec as the intended contract; when code and spec disagree, report it and ask which one is right before encoding either in a test.
  • Reuse the project's HTTP test tooling (supertest, httpx / TestClient, net/http/httptest, RestAssured, curl scripts). Do not add a new library without asking.
  • Decide the level: in-process against the app object (fast, preferred) or over the network against a running instance. State which one you used.
  • Never point tests at production. Use a local or test instance and test credentials from environment variables; do not print or commit tokens.

2. List what to cover per endpoint

Work through this list for each endpoint that matters:

  • Success. Correct status (200, 201 with Location, 204 with no body), correct content type, and the body matches the schema.
  • Schema. Required fields present, types right, no unexpected fields leaking (password hashes, internal ids, other users' data). Validate against the OpenAPI schema if available, otherwise assert the exact keys and types.
  • Validation errors. Missing field, wrong type, too long, out of range, malformed JSON, wrong content type. Expect 400 or 422 as the project defines, with the documented error shape.
  • Error shape. All errors use the same structure (code, message, details). Check that a 404 for a missing resource, 405 for a wrong method and 409 for a conflict follow it, and that no stack trace or SQL is returned.
  • Authentication. No token gives 401; expired or malformed token gives 401; valid token works.
  • Authorization. A user cannot read, change or delete another user's resource (expect 403 or 404 as the project chooses); a normal user cannot call admin endpoints.
  • Idempotency. GET, PUT and DELETE repeated give the same result; a repeated POST with the same idempotency key does not create a duplicate. Deleting twice gives the documented second result.
  • Pagination and filtering. Default page size, limit and offset or cursor, last page, empty page, a page size above the maximum, invalid cursor, stable ordering, total count if promised.
  • Limits. Large payload, rate limit response (429 with Retry-After) where documented.

3. Keep tests independent of database state

  • Each test creates what it needs through the API or a factory with unique values (random suffix in names and emails) and does not rely on rows that "already exist".
  • Do not assert on global counts (total == 5) unless the test owns the entire dataset; assert that the created item appears, or filter by a unique tag.
  • Clean up what you created, or run each test in a transaction or fresh database that rolls back, if the project supports it.
  • Tests must pass in any order, alone, and in parallel. Never depend on auto-increment ids; read the id from the create response.
  • Freeze or inject time when the API returns timestamps or expiry; assert format and relative order, not exact values.
  • Fake third-party services behind the API (payment, email) at the boundary.

4. Write the tests

  • Name by behavior: POST /orders returns 422 when quantity is negative.
  • Assert status first, then headers that matter, then the body. A failure message should show the response body.
  • Use a small helper for auth headers and base URL; avoid building a mini-framework.
  • Prefer table-driven cases for validation errors.
it.each([
  [{ quantity: -1 }, 'quantity'],
  [{ quantity: 'abc' }, 'quantity'],
  [{}, 'quantity'],
])('rejects invalid body %j', async (body, field) => {
  const res = await api.post('/orders').set(auth(user)).send(body);
  expect(res.status).toBe(422);
  expect(res.body.error.details).toContainEqual(expect.objectContaining({ field }));
});

5. Run and verify

Run the new tests, then the full suite, then run the new tests twice more in random order or in parallel to check independence. Break one behavior in the handler temporarily to confirm a test fails, then restore it.

Report format

  • Endpoints covered and the cases per endpoint (short list).
  • Where the code disagrees with the spec or looks wrong (input, actual, expected).
  • Command to run, and how the environment and data are prepared.
  • Gaps: things not covered, such as file uploads or webhooks.

Pitfalls

  • Asserting only status == 200; the body can still be wrong.
  • Snapshotting whole responses with timestamps and ids, which then fail randomly.
  • Tests that need a seeded database and fail on a clean one.
  • Sending real emails, payments or webhooks from tests.
  • Logging full responses that contain tokens or personal data.
  • Testing authorization only for the owner; always include a second user and a request without credentials.
  • Mutating shared fixtures that other tests read.

Source: AnyModel skills catalog · License: CC BY 4.0

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Testing