re:re:actable
Урок 045 минут чтения

Контрактное тестирование и проверка схем API

На этой странице
Кратко

Фронтенд-тесты с моками сети (MSW) быстрые, но у них есть слепая зона: мок может разойтись с настоящим API. Бэкенд переименовал поле total в totalAmount, все фронтенд-тесты зелёные (моки старые), а в продакшене — undefined ₽. Контрактное тестирование закрывает эту зону. Подходы: schema-first — один источник правды (OpenAPI/GraphQL-схема), из которого генерируются типы клиента и моки (Orval, openapi-typescript, openapi-msw), а изменения схемы проверяются на обратную совместимость в CI (oasdiff, GraphQL Inspector); валидация в рантайме — Zod-схемы на границе (ответ API парсится, расхождение даёт понятную ошибку, а не тихий undefined) и проверка моков теми же схемами; consumer-driven contracts (Pact) — фронтенд-тесты записывают ожидания от API в контракт, а CI бэкенда проверяет, что настоящий сервис им соответствует, и can-i-deploy не даёт выкатить ломающее изменение. Выбор зависит от организации: монорепо с общими типами (tRPC) почти не нуждается в контрактах, независимые команды и публичные API — нуждаются.

Вопрос

Что такое контрактное тестирование и зачем оно фронтенду? Как не допустить расхождения между моками в тестах и настоящим API?

Проблема

Фронтенд-тесты:  компонент ──▶ MSW-мок { total: 1500 } ──▶ ✓ зелёные
Продакшен:       компонент ──▶ API      { totalAmount: 1500 } ──▶ «undefined ₽»
 
Моки отражают представление фронтенда об API, а не сам API.

Уровни защиты

ПодходЧто ловитЦена
Общие типы (tRPC, монорепо)Расхождение на этапе компиляцииТолько при общем TS-коде
Генерация типов и моков из OpenAPIСтарые типы/моки после обновления схемыНужна актуальная схема
Проверка совместимости схем в CIЛомающее изменение API до мержа бэкендаНизкая
Валидация ответов Zod в рантаймеРасхождение в проде видно сразу и понятноНемного CPU, нужна схема
Pact (consumer-driven)Сервис не выполняет конкретные ожидания клиентаИнфраструктура (Pact Broker), дисциплина
E2E против настоящего бэкендаВсё, но поздно и дорогоМедленно

Schema-first: генерация

openapi.yaml (бэкенд публикует)
   ├─▶ openapi-typescript / Orval  → типы и клиент фронтенда
   ├─▶ Orval / openapi-msw          → MSW-хэндлеры с типизированными ответами
   └─▶ oasdiff в CI                 → «breaking change: removed property total»
// Типизированные хэндлеры: ответ проверяется по схеме на этапе компиляции
import { createOpenApiHttp } from "openapi-msw";
import type { paths } from "@/shared/api/schema";   // сгенерировано из OpenAPI
 
const http = createOpenApiHttp<paths>({ baseUrl: "https://api.test" });
 
export const handlers = [
  http.get("/orders/{id}", ({ params, response }) =>
    response(200).json({ id: params.id, totalAmount: 1500, status: "paid" }),   // TS: нет поля total → ошибка
  ),
];

После обновления схемы и регенерации устаревшие моки перестают компилироваться — расхождение видно в PR фронтенда.

# CI бэкенда/контрактов: сравнить схему с main
oasdiff breaking openapi.main.yaml openapi.yaml --fail-on ERR

Валидация на границе

const OrderDto = z.object({ id: z.string(), totalAmount: z.number(), status: z.enum(["pending", "paid", "cancelled"]) });
 
export async function getOrder(id: string) {
  const json = await http.get(`/orders/${id}`);
  return toOrder(OrderDto.parse(json));          // расхождение → ZodError с путём поля → Sentry
}
// Тест: моки тоже проходят через схему — устаревший мок упадёт
it("моки заказов соответствуют контракту", () => {
  for (const order of [buildOrderDto(), buildOrderDto({ status: "cancelled" })]) {
    expect(() => OrderDto.parse(order)).not.toThrow();
  }
});

Consumer-driven contracts: Pact

1. Фронтенд (consumer) пишет тест: «GET /orders/42 → 200 { id, totalAmount: number, status }»
2. Тест выполняется против мок-сервера Pact и генерирует контракт (JSON)
3. Контракт публикуется в Pact Broker / PactFlow
4. CI бэкенда (provider) скачивает контракты всех потребителей и прогоняет их против настоящего сервиса
5. can-i-deploy: можно ли выкатить версию X бэкенда/фронтенда, не сломав пары
import { PactV4, MatchersV3 } from "@pact-foundation/pact";
const { like, string, regex } = MatchersV3;
 
const provider = new PactV4({ consumer: "shop-web", provider: "orders-api" });
 
it("получает заказ по id", async () => {
  await provider
    .addInteraction()
    .given("существует заказ 42")
    .uponReceiving("запрос заказа 42")
    .withRequest("GET", "/orders/42")
    .willRespondWith(200, (b) => b.jsonBody({
      id: string("42"),
      totalAmount: like(1500),                              // важен тип, не значение
      status: regex(/pending|paid|cancelled/, "paid"),
    }))
    .executeTest(async (mockServer) => {
      const order = await createApiClient(mockServer.url).getOrder("42");
      expect(order.total).toBe(1500);
    });
});

Pact проверяет только то, что реально использует клиент — бэкенд может свободно менять остальное. Цена — поддержка брокера и дисциплина обеих сторон.

GraphQL

  • Схема — контракт; graphql-codegen генерирует типы для каждой операции.
  • GraphQL Inspector / Apollo Studio проверяют изменения схемы на совместимость с реально используемыми операциями клиентов.
  • Persisted queries дают серверу список операций клиента для проверки.

Что выбрать

СитуацияПодход
Next.js fullstack, один репозиторийОбщие типы/схемы Zod, Server Actions; контракты почти не нужны
Фронтенд и бэкенд — разные команды, есть OpenAPIГенерация типов и моков + oasdiff в CI + Zod на границе
Много потребителей одного API, независимые релизыPact + can-i-deploy
Публичный API для партнёровВерсионирование + проверка совместимости схем

Что важно помнить

  • Моки сети могут разойтись с реальным API — это слепая зона интеграционных тестов.
  • Один источник правды (схема) → типы, клиент и моки.
  • Проверка ломающих изменений схемы в CI.
  • Zod на границе делает расхождение заметным и понятным.
  • Pact — для независимых команд и многих потребителей.

Мини-шпаргалка

  • OpenAPI → openapi-typescript/Orval → openapi-msw.
  • oasdiff breaking old.yaml new.yaml.
  • Dto.parse(json) на границе + проверка моков схемой.
  • Pact: consumer test → контракт → provider verification → can-i-deploy.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам