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.
api-contract-testsInstall
Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.
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
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
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"
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
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,curlscripts). 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,201withLocation,204with 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
400or422as the project defines, with the documented error shape. - Error shape. All errors use the same structure (code, message, details). Check that a
404for a missing resource,405for a wrong method and409for a conflict follow it, and that no stack trace or SQL is returned. - Authentication. No token gives
401; expired or malformed token gives401; valid token works. - Authorization. A user cannot read, change or delete another user's resource (expect
403or404as the project chooses); a normal user cannot call admin endpoints. - Idempotency.
GET,PUTandDELETErepeated give the same result; a repeatedPOSTwith the same idempotency key does not create a duplicate. Deleting twice gives the documented second result. - Pagination and filtering. Default page size,
limitandoffsetor 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 (
429withRetry-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.
AnyModel