Контрактное тестирование и проверка схем 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.