Контрактное тестирование API с Pact

+-------------------------------------------------------------------------+
|                  ФАЗА 1: Фронтенд-потребитель (React / Vitest)          |
|                                                                         |
|  1. Тест выполняет реальный HTTP-запрос к локальному Pact Mock Server   |
|  2. Mock Server сверяет запрос и возвращает синтетический ответ         |
|  3. Генерация артефакта: order-web-order-service.json                   |
+-------------------------------------------------------------------------+
                                     |
                                     v pact-broker publish
+-------------------------------------------------------------------------+
|                              Pact Broker                                |
|  - Хранение контракта с привязкой к Git SHA фронтенда                   |
|  - Матрица совместимости (Matrix): Consumer SHA <-> Provider SHA        |
|  - Отправка Webhook в репозиторий бэкенда при обновлении контракта      |
+-------------------------------------------------------------------------+
                                     |
                                     v Trigger CI Provider Verification
+-------------------------------------------------------------------------+
|                   ФАЗА 2: Бэкенд-провайдер (Node.js / Go)               |
|                                                                         |
|  1. Загрузка контракта из Pact Broker                                   |
|  2. Установка Provider State (например: "user with ID 10 exists in DB") |
|  3. Воспроизведение запроса из контракта на реальный контроллер         |
|  4. Проверка структуры ответа с помощью гибких Matchers                 |
|  5. Публикация результатов проверки в Pact Broker                       |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                 ФАЗА 3: Quality Gate перед деплоем в Production         |
|                                                                         |
|             $ pact-broker can-i-deploy --pacticipant OrderWeb           |
|                                        --version $GIT_SHA               |
|                                        --to-environment production      |
|                                     |                                   |
|                  +------------------+------------------+                |
|                  |                                     |                |
|               [PASS]                                [FAIL]              |
|                  v                                     v                |
|         Разрешение деплоя                      Блокировка пайплайна     |
|   (Бэкенд в проде совместим)                (Несовместимая версия API)  |
+-------------------------------------------------------------------------+

export interface OrderItem {
  id: string;
  sku: string;
  quantity: number;
  unitPrice: number;
}

export interface OrderSummary {
  orderId: string;
  status: 'PENDING' | 'CONFIRMED' | 'SHIPPED';
  totalAmount: number;
  items: OrderItem[];
  createdAt: string;
}

export class OrderApiClient {
  constructor(private readonly baseUrl: string) {}

  async getOrder(orderId: string): Promise<OrderSummary> {
    const response = await fetch(`${this.baseUrl}/api/v2/orders/${orderId}`, {
      method: 'GET',
      headers: {
        Accept: 'application/json',
      },
    });

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Order not found: ${orderId}`);
      }
      throw new Error(`Failed to fetch order: ${response.statusText}`);
    }

    const data = (await response.json()) as OrderSummary;
    return data;
  }
}

import { describe, it, expect } from 'vitest';
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
import path from 'path';
import { OrderApiClient } from '../OrderApiClient';

const { like, eachLike, regex, integer, decimal } = MatchersV3;

// Инициализация контракта между Потребителем и Поставщиком
const provider = new PactV3({
  consumer: 'OrderWebClient',
  provider: 'OrderBackendService',
  dir: path.resolve(process.cwd(), 'pacts'),
});

describe('Контракт API заказов: OrderWebClient -> OrderBackendService', () => {
  it('успешно возвращает сводку заказа по идентификатору', async () => {
    // 1. Описание ожидаемого взаимодействия
    provider
      .given('заказ с идентификатором ord-9910 существует в системе')
      .uponReceiving('запрос на получение информации о заказе ord-9910')
      .withRequest({
        method: 'GET',
        path: '/api/v2/orders/ord-9910',
        headers: {
          Accept: 'application/json',
        },
      })
      .willRespondWith({
        status: 200,
        headers: {
          'Content-Type': 'application/json; charset=utf-8',
        },
        body: {
          orderId: like('ord-9910'),
          status: regex(/^(PENDING|CONFIRMED|SHIPPED)$/, 'CONFIRMED'),
          totalAmount: decimal(1499.5),
          createdAt: regex(
            /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/,
            '2026-09-10T14:30:00.000Z'
          ),
          items: eachLike(
            {
              id: like('item-001'),
              sku: like('KB-MECH-RGB'),
              quantity: integer(2),
              unitPrice: decimal(749.75),
            },
            { min: 1 }
          ),
        },
      });

    // 2. Выполнение реального сетевого запроса к локальному серверу Pact
    await provider.executeTest(async (mockServer) => {
      const client = new OrderApiClient(mockServer.url);
      const order = await client.getOrder('ord-9910');

      // 3. Валидация типизированного ответа на клиенте
      expect(order.orderId).toBe('ord-9910');
      expect(order.status).toBe('CONFIRMED');
      expect(order.items.length).toBeGreaterThanOrEqual(1);
      expect(order.items[0].sku).toBe('KB-MECH-RGB');
    });
  });
});

# Переменные окружения CI
export PACT_BROKER_BASE_URL="https://broker.internal.company.net"
export PACT_BROKER_TOKEN="secret-broker-auth-token"
export GIT_COMMIT=$(git rev-parse HEAD)
export GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Публикация контракта с указанием хэша коммита и текущей ветки
npx pact-broker publish ./pacts \
  --broker-base-url "$PACT_BROKER_BASE_URL" \
  --broker-token "$PACT_BROKER_TOKEN" \
  --consumer-app-version "$GIT_COMMIT" \
  --branch "$GIT_BRANCH"

import { Verifier } from '@pact-foundation/pact';
import { describe, it, beforeAll, afterAll } from 'vitest';
import { app } from '../src/server';
import type { Server } from 'http';

describe('Pact Provider Verification: OrderBackendService', () => {
  let server: Server;
  const PORT = 8089;

  beforeAll(async () => {
    // Запуск бэкенд-сервера на выделенном тестовом порту
    server = app.listen(PORT);
  });

  afterAll(async () => {
    server.close();
  });

  it('удовлетворяет контрактам всех активных потребителей из Pact Broker', async () => {
    const verifier = new Verifier({
      provider: 'OrderBackendService',
      providerBaseUrl: `http://127.0.0.1:${PORT}`,
      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
      // Публикация результатов проверки обратно в брокер
      publishVerificationResult: !!process.env.CI,
      providerVersion: process.env.GIT_COMMIT || '1.0.0',
      providerVersionBranch: process.env.GIT_BRANCH || 'main',
      // Обработка предусловий Provider State
      stateHandlers: {
        'заказ с идентификатором ord-9910 существует в системе': async () => {
          // Инициализация тестовой записи в БД или мок-хранилище
          await mockDatabase.seedOrder({
            id: 'ord-9910',
            status: 'CONFIRMED',
            totalAmount: 1499.5,
            items: [
              { id: 'item-001', sku: 'KB-MECH-RGB', quantity: 2, unitPrice: 749.75 },
            ],
            createdAt: new Date().toISOString(),
          });
        },
      },
    });

    // Запуск прогона верификации
    await verifier.verifyProvider();
  });
});

name: Deploy Consumer Frontend

on:
  push:
    branches: [main]

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      # Генерация контракта через Vitest
      - run: pnpm test:pact

      # Публикация контракта в Pact Broker
      - name: Publish Pact Contract
        run: |
          npx pact-broker publish ./pacts \
            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
            --broker-token ${{ secrets.PACT_BROKER_TOKEN }} \
            --consumer-app-version ${{ github.sha }} \
            --branch main

  quality-gate:
    needs: contract-test
    runs-on: ubuntu-latest
    steps:
      # Запрос матрицы совместимости: можно ли выкатывать этот коммит в прод?
      - name: Can I Deploy?
        run: |
          npx pact-broker can-i-deploy \
            --pacticipant OrderWebClient \
            --version ${{ github.sha }} \
            --to-environment production \
            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
            --broker-token ${{ secrets.PACT_BROKER_TOKEN }}

      - name: Deploy to Cloud
        run: pnpm run deploy:prod