Контрактные тесты API

Пишет тесты HTTP API: коды ответов, схемы, формат ошибок, авторизация и права, идемпотентность, пагинация, без зависимости от состояния базы. Для тестирования REST и JSON API.

ТестированиеПак: Тестирование82 строкиapi-contract-tests

Установка

Выполните одну команду — она сохранит SKILL.md в папку скиллов агента. Перезапустите агента, и он подхватит скилл сам.

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"

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: 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, 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

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Тестирование

Разработка через тесты (TDD)

Ведёт изменение по циклу red, green, refactor: пишет падающий тест с описанием поведения, добавляет минимум кода для прохождения и рефакторит на зелёных тестах. Для фич и багфиксов с тестом вперёд.

Написание юнит-тестов

Пишет точечные юнит-тесты для существующего кода: находит публичное поведение, покрывает крайние случаи и ошибки, делает осмысленные проверки и следует фреймворку и стилю проекта. Для добавления тестов к функции или модулю.

E2E-тесты на Playwright

Пишет стабильные браузерные E2E-тесты на Playwright: пользовательские локаторы, web-first проверки вместо sleep, изолированные данные, трейсы при падении и отладка в headed-режиме. Используйте, когда просят добавить или починить браузерные E2E-тесты.

Пробелы в покрытии тестами

Находит рискованный непокрытый код: запускает coverage, ранжирует пробелы по риску (деньги, авторизация, потеря данных, парсинг), а не по проценту, и предлагает несколько самых важных тестов. Используйте, когда спрашивают, где не хватает тестов, или просят поднять покрытие.