Contract Testing(Pact) 입문: API 변경을 '사고'가 아니라 '검증'으로 바꾸기

Contract Testing(Pact) 입문: API 변경을 '사고'가 아니라 '검증'으로 바꾸기

API 변경이 무서운 이유는, 언제 깨질지 모르기 때문입니다. 계약 테스트는 그 불확실성을 줄입니다.
Pact를 기준으로 소비자/제공자 테스트를 어떻게 운영하면 효과가 나는지 정리합니다.

이 글의 목표는 '개념 정리'보다, "어떤 기준으로 결정할지"와 "어떻게 운영에서 사고를 줄일지"를 남기는 것입니다.

왜 이게 어려운가(운영 관점)

API/HTTP 영역은 '작은 정책'이 전체 사용자 경험과 운영 비용을 바꿉니다. 그래서 실무에서는 구현보다도 기준(정책)과 검증 루프가 중요합니다.

특히 프록시/CDN/게이트웨이가 있는 환경에서는 서버 코드만 보면 원인을 놓치기 쉽습니다. 레이어를 같이 정리해두면 같은 장애를 반복하지 않게 됩니다.

실전 내용(바로 적용)

API 변경이 무서운 이유는, 언제 깨질지 모르기 때문입니다. 계약 테스트는 그 불확실성을 줄입니다.
Pact를 기준으로 소비자/제공자 테스트를 어떻게 운영하면 효과가 나는지 정리합니다.

핵심 요약(결론부터)

• 기준(정책)을 먼저 정하고, 구현/도구는 그 다음에 선택한다
• 실패/예외/회귀를 운영 체크리스트로 막는다
• 공식 문서를 최종 근거로 삼고, 팀 문서로 재가공한다

계약 테스트가 맞는 팀

서비스가 여러 개고 배포가 독립적
프론트/백이 동시에 움직이며 변경이 잦음

운영 흐름(추천)

소비자가 기대하는 계약을 생성 -> 제공자가 계약을 검증 -> 통과한 계약만 배포

흐름(개념)

Consumer Test -> pact file publish
Provider CI pulls pact -> verifies
Only verified pact versions are considered compatible

운영 체크리스트(바로 적용)

• 계약은 최소 단위(핵심 엔드포인트)부터 시작
• 브레이킹 체인지 기준을 팀에서 합의
• 계약 파일 버전/보관 정책을 정함

FAQ

Q. OpenAPI랑 뭐가 다른가요?
A. OpenAPI는 명세이고, Pact는 실행 가능한 검증(테스트)입니다. 둘을 함께 쓰면 문서와 동작이 더 잘 맞습니다.

마무리: 다음 액션

• 팀의 기본값(정책)을 1페이지로 문서화한다
• 대표 시나리오 1개를 코드/설정 예시로 고정한다
• 배포 전후 지표(p95/p99, 오류율)를 비교해 효과를 확인한다

자주 하는 실수(사고 패턴)

• 결정 기준 없이 팀원 취향으로 기술을 고른다
• 문서(스키마)와 구현이 어긋난 상태를 장기간 방치한다
• 재시도/타임아웃을 '늘리기'만 하고 예산/정렬을 안 맞춘다
• 장애 시나리오(429/timeout/partial failure)를 테스트에 넣지 않는다

적용 순서(추천)

• 1) 바꾸려는 것(성능/보안/호환성/운영 단순화)을 한 문장으로 정의한다
• 2) 기본값과 예외를 먼저 정하고, 예외는 만료일/사유/소유자를 남긴다
• 3) 대표 시나리오(요청/응답 예시)를 만들어 계약으로 고정한다
• 4) 지표(p95/p99, 오류율, 재시도율)로 배포 전후를 비교한다
• 5) CI/PR에서 자동 검증(린트/스키마 diff/계약 테스트)을 걸어 회귀를 막는다

검증/회귀 방지

• 배포 전후 지표(p95/p99, 4xx/5xx, 재시도율)를 동일 조건으로 비교
• 프록시/CDN/게이트웨이 설정 변경 이력을 남기고, 롤백 플랜을 준비
• 대표 시나리오를 e2e 테스트로 고정(문서가 아니라 테스트가 계약이 되게)

팀 합의 템플릿(복붙용)

# 팀 합의 템플릿(복붙용)
목표: (예) 구버전 클라이언트 유지하면서 응답 스키마 변경
기본값: (예) /v1 경로 버전 사용
예외: (예) 내부 API는 헤더 버전 허용(게이트웨이 필수)
대표 시나리오: (요청/응답 예시 첨부)
모니터링: (오류율/지연/트래픽) 대시보드 링크
EOL/변경 정책: (날짜/공지 채널/롤백 규칙)

FAQ

Q. OpenAPI랑 뭐가 다른가요?
A. OpenAPI는 명세이고, Pact는 실행 가능한 검증(테스트)입니다. 둘을 함께 쓰면 문서와 동작이 더 잘 맞습니다.

참고/출처

버전/환경에 따라 동작이 달라질 수 있으니, 최종 기준은 공식 문서를 확인합니다.

• Pact Documentation