Тестирование API контрактом: как проверять не только статус, но и семантику ответов

Контрактные тесты — это способ перестать измерять качество API одним лишь HTTP-кодом. В реальных системах «200 OK» может сопровождаться пустым телом, несоответствующей схемой данных, неверными бизнес-значениями или нарушением идемпотентности. В итоге интеграции ломаются не во время компиляции, а в продакшене — потому что никто не проверял семантику ответа и правила поведения сервиса.

Контрактное тестирование решает эту проблему: мы фиксируем ожидаемую структуру ответа (схемы, обязательные/необязательные поля), допустимые состояния ошибок и поведение сервисов при повторных запросах. Ниже — практический разбор подхода: что именно проверять, как описывать контракт, как моделировать ошибки и идемпотентность, и как организовать регрессии при изменениях версий API.

Почему статус-код недостаточен

Многие команды начинают с тестов вида:

• проверить, что ответ 200 при корректном запросе;
• проверить, что 404 при неверном id;
• проверить, что 400 при некорректном payload.

Проблема в том, что HTTP-коды не являются полным описанием бизнес-семантики:

1. Схема может быть неверной
   Сервер вернул JSON, но поменял структуру: поле переименовали, типы сдвинулись, формат даты нарушен. Тест, проверяющий только код, этого не увидит.

2. Данные могут быть формально валидны, но семантически неправильны
   Например, сумма со знаком наоборот, status не соответствует ожидаемому машинному состоянию, currency не совпадает с контекстом.

3. Ошибки могут быть «не теми»
   Сервер вернул 400, но не указал error.code или указал код, который клиент не знает. Или вернул 409, когда ожидался 422 по правилам домена.

4. Idempotency легко ломается
   Особенно в операциях создания/обработки (например, POST /payments, POST /orders или PUT /resources/{id} с повтором запроса). HTTP статус может быть одинаковым, но побочные эффекты — разные.

Именно поэтому контрактные тесты должны проверять не только факт успеха/ошибки, но и что именно означает этот успех или ошибка для клиента.

Контракт API: что именно фиксировать

Контракт — это не только OpenAPI/Swagger. Для тестов полезно разложить контракт на уровни:

Схема успешных ответов

Для каждого эндпоинта и метода фиксируйте:

• HTTP статус (например, 200, 201);
• JSON-схему ответа:
  • обязательные поля;
  • допустимые типы;
  • форматы (UUID, email, даты);
  • диапазоны/ограничения (например, amount >= 0);
• инварианты:
  например, если status = "COMPLETED", тогда completedAt обязателен и не пустой.

Схема ошибок (и семантика)

Ошибки тоже контрактны. Для каждого класса сценариев фиксируйте:

• ожидаемый HTTP код;
• структуру ошибки (обычно:
  • error.code
  • error.message (иногда локализуемая — зависит от продукта)
  • error.details/violations — для валидации
  • requestId/traceId — для трассировки);
• набор допустимых error.code под конкретные причины;
• правила полей: что всегда присутствует, что может отсутствовать.

Важно: один и тот же 400 может включать разные причины. Контракт должен разделять эти случаи, а тесты — ловить несоответствие.

Допустимые состояния бизнес-ошибок

Если ваш API возвращает доменные состояния в теле (например, status: "PENDING", status: "CANCELLED" и т.п.), контрактные тесты должны проверять соответствие набора допустимых переходов и обязательность сопутствующих полей.

Пример инварианта: если операция вернула status: "REJECTED", то:

• должен присутствовать reason.code;
• result может быть пустым;
• completedAt обязательна.

Idempotency как часть контракта

Идемпотентность — это поведенческое требование. Для контрактных тестов она обычно описывается так:

• клиент отправляет повторный запрос с одним и тем же идемпотентным ключом (например, Idempotency-Key заголовок);
• API должен:
  • либо возвращать один и тот же результат (тот же resourceId, те же поля),
  • либо обеспечивать отсутствие дубликатов на уровне побочных эффектов.

Контрактно проверять это значит:

• сравнить ключевые поля между первым и вторым ответом;
• проверить отсутствие дубликатов в системе (через отдельный GET, запрос к “read model”, ожидание консистентности — в зависимости от архитектуры).

Регрессия поведения при изменениях версий

При изменении версий API часто ломаются:

• старые контракты: клиенты ожидают прежнюю схему и семантику;
• поля: появились/исчезли;
• ошибки: стали другие error.code;
• формат дат/чисел;
• правила идемпотентности.

Поэтому контрактные тесты должны быть:

• версионированными: тесты под v1, v2;
• ориентированными на backward compatibility: если поле стало необязательным — тест должен учитывать это;
• устойчивыми к предсказуемым изменениям: но при этом строгими там, где изменения не допускаются.

Как организовать контрактные тесты: практический подход

Есть несколько распространённых стратегий:

1. Валидировать ответы по JSON Schema
   Хороший вариант, когда контракт выражается схемой JSON и вы хотите автоматическую проверку типов и обязательных полей.

2. Подход “snapshot” (снимки ответов)
   Удобно для отладки и быстрых регрессий, но осторожно: при изменениях контрактов легко “замазать” проблему.

3. Собственные проверки доменной семантики
   JSON Schema отвечает за структуру, но семантику (инварианты, переходы состояний) нужно проверять кодом.

4. Contract-first через OpenAPI/AsyncAPI
   Тесты могут генерироваться из спецификаций. На практике часто комбинируют: спецификация — источник схем, плюс вручную — доменные правила.

Ниже — комбинация “схема + доменная семантика + идемпотентность + версионные тесты”.

Проверка схем ответа: JSON Schema как фундамент

Допустим, у вас есть эндпоинт:

• POST /v1/orders
• успешный ответ: 201 Created
• тело: JSON с полями id, status, items, createdAt

Сначала удобно описать JSON Schema. Например, в файле schemas/order-created.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status", "items", "createdAt"],
  "properties": {
    "id": { "type": "string", "pattern": "^[0-9a-fA-F-]{36}$" },
    "status": { "type": "string", "enum": ["PENDING", "CONFIRMED", "REJECTED"] },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["sku", "quantity"],
        "properties": {
          "sku": { "type": "string", "minLength": 1 },
          "quantity": { "type": "integer", "minimum": 1 }
        },
        "additionalProperties": false
      }
    },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "additionalProperties": false
}

Дальше тест проверяет:

• HTTP статус;
• валидность JSON;
• соответствие схеме.

Ниже пример на Node.js (подход схематичен — можно адаптировать под вашу инфраструктуру):

import Ajv from "ajv";
import fs from "node:fs";
import fetch from "node-fetch";

const ajv = new Ajv({ allErrors: true, strict: false });

const schema = JSON.parse(fs.readFileSync("./schemas/order-created.json", "utf-8"));
const validate = ajv.compile(schema);

test("POST /v1/orders: returns contract-compliant response", async () => {
  const res = await fetch("http://localhost:8080/v1/orders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ /* валидный payload */ })
  });

  expect(res.status).toBe(201);

  const json = await res.json();
  const ok = validate(json);

  if (!ok) {
    console.log(validate.errors);
  }
  expect(ok).toBe(true);
});

Ключевой нюанс: additionalProperties: false — это строгая проверка. Она полезна, чтобы ловить неожиданные изменения. Но если вы сознательно допускаете расширение ответа (например, добавление новых полей без вреда клиенту), лучше не запрещать additionalProperties. Практически это решается так:

• для полей, на которые клиент опирается, делайте строгую проверку;
• для “дополнительных полей” решайте по политике совместимости:
  • либо запрещаем (жесткий контракт),
  • либо допускаем, но обязательно проверяем обязательные.

Проверка ошибок: контракт ошибки — отдельный объект

Многие команды игнорируют структуру ошибок, потому что “код уже говорит всё”. На практике клиенту нужен error.code и детали, чтобы корректно отреагировать.

Сделайте отдельные схемы для каждой категории:

• 400 ValidationError
• 404 NotFound
• 409 Conflict
• 422 UnprocessableEntity (если используете её валидацию/доменные ограничения)

Например, схема ошибки валидации:

{
  "type": "object",
  "required": ["error", "requestId"],
  "properties": {
    "requestId": { "type": "string", "minLength": 1 },
    "error": {
      "type": "object",
      "required": ["code", "message", "details"],
      "properties": {
        "code": { "type": "string", "const": "VALIDATION_ERROR" },
        "message": { "type": "string", "minLength": 1 },
        "details": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["field", "issue"],
            "properties": {
              "field": { "type": "string", "minLength": 1 },
              "issue": { "type": "string", "minLength": 1 }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Тест должен проверять, что:

1. HTTP статус соответствует сценарию;
2. error.code в теле равен ожидаемому;
3. details содержит минимум одну проблему по конкретному полю.

Пример:

test("POST /v1/orders: invalid payload returns validation contract", async () => {
  const res = await fetch("http://localhost:8080/v1/orders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ items: [] }) // допустим, поле требует minItems >= 1
  });

  expect(res.status).toBe(400);

  const json = await res.json();
  expect(json.error.code).toBe("VALIDATION_ERROR");
  expect(Array.isArray(json.error.details)).toBe(true);
  expect(json.error.details.some(d => d.field === "items")).toBe(true);
});

Заметка по политике сообщений: error.message может меняться (особенно если есть локализация или уточнения). Поэтому чаще всего проверяют:

• присутствие сообщения (minLength),
• либо шаблон формата,
• либо отсутствие зависимости теста от точного текста.

Семантические инварианты: что проверять кодом

Schema фиксирует форму, но не смысл. Поэтому добавьте доменные проверки.

Пример: согласованность статусов и полей

Допустим, ваша операция создания заказа возвращает status. Тогда семантика может быть такой:

• если status === "CONFIRMED", то items должны включать цены/подтверждения (пусть эти поля есть в расширенной версии);
• если status === "REJECTED", то в теле должна быть секция rejection.

Даже если в текущей схеме rejection отсутствует (или опциональна), тест должен отражать контракт домена.

Пример псевдо-кода:

function assertOrderSemantics(order) {
  if (order.status === "REJECTED") {
    expect(order).toHaveProperty("rejection");
    expect(order.rejection).toHaveProperty("reason");
    expect(order.rejection.reason).not.toBe("");
  }

  if (order.status === "PENDING") {
    // например: обязательный инвариант отсутствия завершения
    expect(order).not.toHaveProperty("completedAt");
  }
}

Idempotency: как тестировать без ложных срабатываний

Идемпотентность ломается чаще всего по двум причинам:

1. Повторный запрос создаёт новый ресурс вместо возврата результата.
2. Повторный запрос возвращает иной формат/статус/данные из-за гонки (race conditions) или различий в трактовке заголовка.

Контрактный подход: проверяем результат + побочные эффекты

Алгоритм теста идемпотентности обычно такой:

1. Сгенерировать уникальный Idempotency-Key.
2. Отправить запрос POST один раз и сохранить ключевые поля результата (например, order.id).
3. Отправить тот же запрос повторно с тем же Idempotency-Key.
4. Сравнить:
   • order.id (должен совпасть),
   • ключевые поля ответа (например, сумма, статус),
   • отсутствие дубликатов (через GET/поиск по order.id или по ключу клиента).

Пример на концептуальном уровне:

test("POST /v1/orders is idempotent with Idempotency-Key", async () => {
  const idemKey = crypto.randomUUID();

  const payload = { /* валидный payload */ };

  const res1 = await fetch("http://localhost:8080/v1/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idemKey
    },
    body: JSON.stringify(payload)
  });

  const json1 = await res1.json();

  const res2 = await fetch("http://localhost:8080/v1/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idemKey
    },
    body: JSON.stringify(payload)
  });

  const json2 = await res2.json();

  expect(res1.status).toBeGreaterThanOrEqual(200);
  expect(res2.status).toBeGreaterThanOrEqual(200);

  // Ключевой контрактный инвариант
  expect(json2.id).toBe(json1.id);

  // Дополнительно: сравнение семантических полей
  expect(json2.status).toBe(json1.status);

  // Побочный эффект: убедиться, что ресурс создан один раз.
  // Способ зависит от модели данных:
  // - либо GET по json1.id,
  // - либо поиск по clientReference.
});

Подводные камни

• Конкурентная доставка / ретраи в сети
  Повтор может прилетать одновременно. Тесты должны быть устойчивыми:

  • использовать один и тот же ключ;
  • избегать ситуации, когда первый запрос ещё не успел завершить обработку, если ваша логика не гарантирует немедленную идемпотентность. Иногда нужен retry-with-wait на read-модель.

• Разные payload при одном ключе
  Некоторые системы допускают только “одинаковый запрос” на один ключ. В таком случае повтор с другим телом должен вернуть контрактную ошибку (например, 409 с кодом IDEMPOTENCY_MISMATCH). Это тоже часть контракта — стоит добавить отдельный тест.

• Повтор с истекшим ключом/таймаутом
  Если у идемпотентного ключа есть TTL, поведение после TTL становится контрактным: либо снова создаётся ресурс, либо возвращается ошибка. Это лучше зафиксировать тестом под вашу политику.

Регрессия при изменении версий API: как избежать “вечного обновления” тестов

Контрактные тесты живут в мире, где API меняется. Важно не сделать их инструментом бесконечной боли. Для этого стоит:

Разделить контракты по версиям

Не пытайтесь переиспользовать схемы “как есть”. Схемы под v1 и v2 должны быть отдельными артефактами:

• schemas/v1/order-created.json
• schemas/v2/order-created.json

И соответствующие наборы тестов.

Определить совместимость: что меняется, а что нет

Обычно правила такие:

• Добавление новых полей: часто допускается (клиенты не сломаются, если они игнорируют неизвестные поля).
• Удаление/переименование полей: обычно строго запрещено в minor/patch без миграции.
• Изменение типов: опасно, лучше запрещать.
• Изменение семантики статусов: почти всегда ломает клиента.
• Изменение набора error.code: может сломать обработку ошибок.

Контрактные тесты должны отражать именно эти правила.

Сделать “маятник” назад совместимости: тесты на стабильность ошибок

Если вы обновляете версию, важно проверить не только схему успешного ответа, но и “старые” сценарии ошибок:

• какие error.code возвращаются при известных входах;
• сохраняется ли структура details;
• меняется ли HTTP статус.

Хороший практический подход: для каждого “известного входа” (например, “пустой items”, “невалидный sku”, “несуществующий id”) хранить тест, который прогоняется на каждой целевой версии.

Контрактные тесты для изменений: сценарии “что может сломаться”

Чтобы тесты реально защищали, полезно заранее выделить категории изменений и покрыть их отдельными тестами:

1. Схема успеха

   • поля стали обязательными/необязательными;
   • изменились типы;
   • изменился формат даты/числа.

2. Схема ошибки

   • изменились error.code;
   • поменялась структура details;
   • исчез requestId/traceId.

3. Семантика статусов

   • статус получил другое значение;
   • статусы перестали соответствовать полям.

4. Поведение идемпотентности

   • на повтор создаётся второй ресурс;
   • повтор возвращает другой id;
   • повтор с несовпадающим payload не вызывает ожидаемую ошибку.

5. Стабильность при релизных миграциях

   • в переходный период интерфейс может возвращать “гибрид” старых и новых полей;
   • важно, чтобы тесты отлавливали смешение контрактов.

Практическая схема тестового набора

Рекомендуемая структура набора (логическая, не привязана к фреймворку):

• contract-tests/v1/
  • orders/create-success.test
  • orders/create-validation-error.test
  • orders/create-notfound-error.test (если есть зависимые ресурсы)
  • orders/create-idempotency.test
• contract-tests/v2/
  • те же категории, но с версиями схем и ожидаемых кодов/статусов

Внутри каждой категории:

• есть JSON Schema валидация тела;
• есть доменные проверки (invariants);
• есть проверки идемпотентности (для соответствующих методов);
• есть проверки на устойчивость структуры ошибок.

Механика: откуда брать контракт и как хранить его

Есть три источника контракта:

1. OpenAPI как источник схем

   • Плюсы: спецификация централизована.
   • Минусы: семантические инварианты обычно не описаны достаточно строго. Их всё равно придётся кодировать.

2. Ручные JSON Schema файлы

   • Плюсы: точность и независимость.
   • Минусы: нужно синхронизировать с реальным API.

3. Контракт, полученный из “наблюдения” (record/replay)

   • Плюсы: быстрее начать.
   • Минусы: легко зафиксировать неправильное поведение как “норму”.

На практике чаще всего удобно сделать гибрид:

• OpenAPI генерирует базовую схему/типы,
• а доменную семантику и детали ошибок дописывают в тестах.

Ошибки и анти-паттерны контрактного тестирования

1) Проверять только “наличие поля”, а не его формат

Поле может присутствовать, но быть пустым или в неправильном формате. Контрактные тесты должны проверять формат/диапазон.

2) Игнорировать дополнительные поля без стратегии

Если вы всегда используете additionalProperties: true, вы перестаёте ловить изменения, которые могут быть критичны. С другой стороны, если всегда делаете false, вы получите постоянные падения из-за расширений.

Практика: выберите стратегию по каждому endpoint:

• критичные контракты — строгие,
• расширяемые — более гибкие, но с проверкой обязательного ядра.

3) Snapshot-тесты без контроля намерений

Snapshots хороши, когда команда понимает: изменение ответа — это осознанная миграция контракта. Если это не так, snapshot начинает “съедать” реальные проблемы.

4) Не тестировать ошибки и идемпотентность

Самый распространённый перекос: покрывают “happy path”, но забывают:

• ошибки клиента,
• ошибки домена,
• поведение при ретраях.

5) Нет версионирования контрактов

Если тесты живут в одном пространстве схем и не привязаны к версии, при миграции вы теряете смысл контрактности: тест начнёт проверять уже не то.

Как встроить контрактные тесты в процесс разработки

Контрактные тесты эффективны, когда они встроены в CI/CD так, чтобы:

• выполнялись автоматически при изменениях API;
• падали до слияния;
• давали диагностируемые сообщения (какая схема не совпала, какой error.code исчез/изменился);
• поддерживали локальный прогон.

Рекомендация по практике: делайте отчётность в стиле “контрактная дифференциация”:

• “поле createdAt перестало быть date-time”;
• “ожидали error.code=VALIDATION_ERROR, получили MALFORMED_REQUEST”;
• “idempotency нарушена: id во втором ответе отличается”.

Это снижает стоимость исправлений и дисциплинирует изменения контракта.

Вывод: контрактные тесты — это тесты для клиента, а не для сервера

Тестирование API статусом — это проверка минимального уровня. Контрактное тестирование превращает API в предсказуемый интерфейс: вы фиксируете схему успешных ответов, структуру и коды ошибок, доменные инварианты, требования идемпотентности и поведение при изменениях версий.

Если ваша команда только начинает выстраивать эту практику, разумный путь — не “сразу всё покрыть”, а выбрать 2–3 критичных эндпоинта и внедрить строгую проверку семантики ошибок и идемпотентности. Это даст быстрый эффект: вы начнёте ловить реальные поломки интеграций до релиза.

Для углубления в подходы к проектированию API и контрактам можно также ознакомиться с курсом по теме контрактного тестирования и спецификаций: [ /course/ ] — он будет полезен как структурированное продолжение после ручной практики и первичных схем.

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