2nd/10_Wiki/Topics/Domain_Programming/Coding/Testing_Contract_Testing.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
testing-contract-testing	Contract Testing — 서비스 간 약속 검증	Coding	draft	B	conceptual	2026-05-09	2026-05-09	testing contract-test pact microservices vibe-coding	language applicable_to TypeScript / Pact Backend microservices		consumer-driven contract Pact schema test

Contract Testing

마이크로서비스 환경에서 E2E 테스트는 비싸고 느리다. 각 서비스가 "다른 서비스와의 약속(contract)" 만 검증 = consumer-driven contract. 약속 깨면 즉시 파이프라인 fail.

📖 핵심 개념

• Consumer 가 "이 형식의 응답을 기대한다" 라는 contract 작성.
• Provider 는 그 contract 를 받아 자기 코드가 약속을 지키는지 검증.
• 양쪽이 contract 를 통해 통신, E2E 환경 안 띄움.

💻 코드 패턴 (Pact)

Consumer 측 (Frontend / 다른 서비스)

import { PactV3, MatchersV3 } from '@pact-foundation/pact';
const { like, eachLike, integer } = MatchersV3;

const provider = new PactV3({ consumer: 'web-app', provider: 'user-service', port: 1234 });

test('GET /users/:id', async () => {
  await provider
    .given('user 1 exists')
    .uponReceiving('a request for user 1')
    .withRequest({ method: 'GET', path: '/users/1' })
    .willRespondWith({
      status: 200,
      headers: { 'Content-Type': 'application/json' },
      body: like({
        id: integer(1),
        email: like('a@a.com'),
        roles: eachLike('admin'),
      }),
    });

  await provider.executeTest(async (mock) => {
    const res = await fetch(`${mock.url}/users/1`).then(r => r.json());
    expect(res.id).toBe(1);
  });
});

실행 결과 = pacts/web-app-user-service.json 파일.

Provider 측 검증

import { Verifier } from '@pact-foundation/pact';

test('user-service satisfies web-app contract', async () => {
  const v = new Verifier({
    provider: 'user-service',
    providerBaseUrl: 'http://localhost:3000',
    pactUrls: ['./pacts/web-app-user-service.json'], // 또는 Pact Broker
    stateHandlers: {
      'user 1 exists': async () => {
        await db.users.upsert({ id: 1, email: 'a@a.com' });
      },
    },
  });
  await v.verifyProvider();
});

Pact Broker — 중앙 저장

• consumer CI: pact 파일 publish.
• provider CI: 최신 pact 받아 검증.
• can-i-deploy 명령으로 안전한 deploy 확인.

🤔 의사결정 기준

상황	권장
마이크로서비스 다수 (>3개)	Pact 도입
단일 서비스 + DB	unit + integration 만 충분
Public API (외부 사용자)	OpenAPI 스키마 + 검증
GraphQL	schema introspection + breaking change detector
gRPC	proto 가 자체 contract
Frontend ↔ Backend	Pact 또는 OpenAPI generator (zod, ts-rest)

❌ 안티패턴

• contract 안에 정확한 값 (literal) 만 명시: 실 응답이 약간만 달라도 fail. matcher 사용 (like / eachLike / regex).
• provider state handler 없음: contract 가 "user 1 exists" 가정 — handler 없으면 검증 못 함.
• breaking change 없이 contract 갱신: 옛 consumer 가 깨짐. semantic versioning + can-i-deploy.
• pact 만 있고 unit/integration test 없음: pact 는 약속만, 비즈니스 로직 안 검증.
• 양쪽 모두 mock: contract 가 양쪽에서 거짓말이면 의미 없음. provider 는 진짜 코드 검증.
• contract test 가 가짜 데이터 fixture 의존: stateHandlers 로 진짜 상태 만들어야.

🤖 LLM 활용 힌트

• consumer 측: matcher 사용 (literal X).
• provider 측: stateHandler 로 진짜 DB 상태.
• Pact Broker + can-i-deploy 가 deploy gate.

🔗 관련 문서

• Testing_Test_Pyramid
• Testing_Mocking_Boundaries