이 글에서 얻는 것

  • Consumer-Driven Contract Testing(CDCT)을 언제 도입해야 효과가 큰지, 조직/시스템 조건으로 판단할 수 있습니다.
  • “통합 테스트를 늘리면 안전하다”는 접근이 왜 한계에 부딪히는지, 시간/비용/실패 원인 기준으로 설명할 수 있습니다.
  • CI 파이프라인에 계약 테스트를 넣을 때 필요한 게이트 순서, 실패 처리 기준, 운영 지표를 바로 적용할 수 있습니다.

핵심 개념/이슈

1) 통합 테스트만으로는 왜 느리고 불안정해지는가

서비스가 2~3개일 때는 E2E/통합 테스트만으로도 충분합니다. 문제는 서비스가 8개, 12개로 늘어나면서 시작됩니다.

  • 테스트 환경이 실제와 달라서 재현이 어렵고
  • 다운스트림 mock/stub 유지 비용이 커지며
  • 작은 API 필드 변경에도 다수 테스트가 연쇄 실패합니다.

실무에서 자주 보는 패턴은 다음입니다.

  • PR당 테스트 시간 20분 이상
  • 실패 테스트 중 30% 이상이 flaky(환경/타이밍 이슈)
  • API 스펙 변경 시, 실제 런타임 장애보다 테스트 파이프라인 복구에 더 오래 걸림

이 상황에서 핵심 질문은 “더 많은 통합 테스트”가 아니라, 어떤 실패를 더 앞단에서 싸게 잡을 것인가입니다.

2) CDCT의 핵심: Consumer가 기대를 먼저 명세한다

CDCT는 Provider(제공자)가 API를 일방적으로 문서화하는 방식이 아니라, Consumer(사용자 서비스)가 실제 기대를 계약으로 선언합니다.

흐름은 단순합니다.

  1. Consumer 테스트에서 요청/응답 기대를 계약(Contract)으로 생성
  2. 계약을 Broker(또는 아티팩트 저장소)에 게시
  3. Provider CI에서 해당 계약을 검증
  4. 검증 통과 버전만 배포 후보로 인정

핵심 이점은 “실제 사용하는 필드/상태코드/에러 포맷”이 계약으로 남는다는 점입니다. 즉, 문서가 아니라 실행 가능한 합의가 됩니다.

3) OpenAPI 문서와 계약 테스트는 대체 관계가 아니다

팀에서 자주 나오는 오해가 있습니다. “OpenAPI만 잘 쓰면 계약 테스트가 필요 없지 않나?”

둘은 목적이 다릅니다.

  • OpenAPI: API 전체 능력을 문서화(가능한 인터페이스)
  • CDCT: 실제 소비 시나리오를 검증(사용되는 인터페이스)

실무에서는 OpenAPI + CDCT를 함께 쓰는 것이 안정적입니다. OpenAPI로 전역 가시성을 확보하고, CDCT로 회귀 위험을 줄이는 구조입니다.

실무 적용

1) 도입 판단 기준(숫자 기반)

아래 조건 중 3개 이상이면 CDCT 우선순위를 높이는 것이 좋습니다.

  • 독립 배포 서비스가 5개 이상
  • API 변경으로 인한 회귀 장애가 분기 2회 이상
  • 통합 테스트 파이프라인 시간이 15분 이상
  • 소비자 팀과 제공자 팀이 분리되어 릴리스 타이밍이 다름
  • 배포 전 호환성 확인을 사람 DM/회의에 의존

반대로 모놀리스 또는 단일 팀 소유 서비스라면, CDCT보다 단위/통합 테스트 품질 개선이 먼저일 수 있습니다.

2) CI 게이트 순서(권장)

운영성이 높은 순서는 아래와 같습니다.

  1. Consumer 단위 테스트 + Contract 생성
  2. Contract 게시(Broker)
  3. Provider 단위/컴포넌트 테스트
  4. Provider Contract 검증
  5. 선택적 소규모 E2E smoke

여기서 중요한 규칙은 하나입니다.

  • Provider Contract 검증 실패 시 배포 차단

예외를 허용해야 한다면 기준을 문서로 고정하세요.

  • P0/핵심 결제 흐름: 예외 없음
  • P1/내부 운영 API: 24시간 유예 가능

3) 버전 정책과 호환성 룰

계약 테스트를 도입해도 버전 정책이 없으면 결국 충돌합니다. 최소한 아래 4개는 정해야 합니다.

  • 필드 추가는 optional만 허용
  • 필드 삭제/이름 변경은 deprecation 기간(예: 2 릴리스 또는 30일) 의무화
  • 에러 코드 체계는 하위 호환 유지
  • 기본값 변경은 major 성격으로 취급

실무 의사결정 기준 예시:

  • 월 배포 20회 이상 팀: deprecation 기간을 “일수”가 아니라 “릴리스 횟수”로 정의
  • 배포 빈도가 낮은 팀: 45~60일로 고정

4) 운영 지표(대시보드 필수)

CDCT를 도입했으면 다음 지표를 추적해야 합니다.

  • 계약 검증 실패율(주간): 5% 이하 목표
  • 계약 변경 후 평균 복구 시간(MTTR): 1영업일 이하
  • 계약 미검증 배포 비율: 0%
  • 계약으로 사전 탐지된 회귀 건수(월): 증가 추세면 긍정 신호

이 지표가 없으면 “도입은 했는데 효과를 모르겠다” 상태가 됩니다.

트레이드오프/주의점

  1. 초기 설정 비용 증가
    Broker, 테스트 프레임워크, CI 통합까지 붙이면 첫 12주 생산성이 떨어질 수 있습니다. 하지만 회귀 사고 비용이 큰 팀일수록 12분기 내 회수됩니다.

  2. 과도한 계약 세분화 위험
    Consumer별로 계약을 과도하게 쪼개면 Provider가 유지 불가능해집니다. “핵심 시나리오 중심”으로 시작하고, 희귀 케이스는 통합 테스트로 남기세요.

  3. 테스트 데이터 품질 문제
    계약 테스트는 스키마 호환성은 잘 잡지만, 도메인 데이터 품질 문제(잘못된 상태 전이)는 놓칠 수 있습니다. 도메인 규칙 테스트와 병행해야 합니다.

  4. 조직 협업 규칙 부재
    기술보다 중요한 건 소유권입니다. 계약 변경 승인자, deprecation 알림 채널, 예외 승인 절차가 없으면 CDCT도 금방 형식화됩니다.

체크리스트 또는 연습

  • 서비스 간 API 의존도 맵(Consumer→Provider)을 최신 상태로 정리했다.
  • 핵심 API 3개에 대해 Consumer 계약 테스트를 먼저 만들었다.
  • Provider CI에 계약 검증 게이트를 추가하고 실패 시 배포를 차단한다.
  • 계약 파괴 변경의 deprecation 기간/공지 채널을 문서화했다.
  • 계약 실패율, 복구 시간, 미검증 배포율을 대시보드로 본다.

연습 과제:

  1. 현재 운영 중인 API 하나를 고르고, 실제 Consumer 호출 패턴 5개만 계약으로 추출해보세요.
  2. “응답 필드 제거” 변경을 가정하고, 어떤 Consumer가 깨지는지 계약 기준으로 확인해보세요.
  3. 통합 테스트 10개 중 회귀 탐지 가치가 낮은 3개를 계약 테스트로 치환해 CI 시간을 얼마나 줄일 수 있는지 계산해보세요.

관련 글