서버팀은 “API 문서대로 응답했습니다”라고 말하고, 화면팀은 “어제까지 되던 기능이 오늘 깨졌다”고 말합니다. 둘 다 맞을 수 있습니다. OpenAPI 스키마에 필드가 선택 사항이라고 적혀 있어도 화면은 그 필드가 항상 있다고 가정했을 수 있고, 오류 코드의 형식은 같아도 의미가 바뀌었을 수 있습니다. 여러 팀과 고객 시스템이 한 API를 쓸수록 문서와 실제 의존 관계 사이의 간극이 커집니다. 소비자 주도 계약 테스트는 소비자가 실제로 기대하는 요청과 응답을 실행 가능한 계약으로 남기는 방법입니다.
문서 검증과 계약 검증은 무엇이 다른가
OpenAPI 같은 스키마는 제공자가 공개하는 인터페이스의 전체 모양을 설명합니다. 필드 타입, 필수 여부, 경로와 상태 코드를 점검하는 데 유용합니다. 반면 소비자 계약은 특정 화면이나 연동 작업이 어떤 입력을 보내고 어떤 응답 부분을 사용하는지 기록합니다. 예를 들어 “주문 목록에서 고객명을 표시하려면 고객 ID와 이름이 함께 와야 한다”는 기대를 테스트로 표현합니다. 두 검증은 경쟁 관계가 아닙니다. 스키마는 공통 약속이고 계약 테스트는 실제 사용자 의존성을 드러냅니다.
Pact 문서가 설명하는 전형적인 흐름은 소비자 테스트가 계약을 만들고, 제공자 테스트가 그 계약을 실제 API 구현에 대해 다시 검증하는 것입니다. 소비자 쪽에서는 실제 제공자 대신 계약 기반 모의 응답으로 화면 로직을 시험합니다. 제공자 쪽에서는 같은 계약을 가져와 테스트 서버에 요청을 보내고 응답이 맞는지 확인합니다. 중요한 것은 계약 파일을 공유하는 데 그치지 않고 검증 결과를 배포 결정에 연결하는 것입니다.
계약은 모든 응답을 고정하는 스냅샷이 아니다
테스트를 지나치게 엄격하게 만들면 제공자가 안전하게 새 필드를 추가해도 실패합니다. 소비자가 필요한 필드와 의미를 명확히 적고, 생성 시각이나 ID처럼 변하는 값은 타입과 패턴을 확인해야 합니다. 반대로 금액 단위나 상태값의 의미처럼 비즈니스에 중요한 부분은 느슨하게 넘겨서는 안 됩니다. 경계 사례도 포함하세요. 데이터가 없는 경우, 권한이 없는 경우, 페이지가 끝난 경우, 일시적 오류 응답은 정상 경로만큼 자주 화면을 깨뜨립니다.
제공자 검증에는 재현 가능한 상태가 필요합니다. “고객에게 주문이 하나 있고 승인 대기 중” 같은 사전 조건을 테스트 환경에서 만들고, 테스트가 서로 영향을 주지 않도록 정리합니다. 운영 데이터의 우연한 상태에 기대면 결과가 불안정해집니다. 인증도 테스트 전용 우회로 무시하기보다 실제 호출과 가까운 방식으로 검증하되 비밀 값을 계약 파일에 넣지 않아야 합니다.
계약의 소유 관계도 중요합니다. 오래된 소비자가 더 이상 사용하지 않는 필드를 계속 계약에 붙들고 있으면 제공자는 개선할 수 없습니다. 반대로 소비자 팀이 새 요구사항을 계약에 올렸는데 제공자가 검증하지 않은 채 배포하면 보호 효과가 없습니다. 소비자 버전과 실제 운영 여부를 기록하고, 폐기된 계약은 합의된 절차로 정리하세요. 계약 변경이 실패했을 때는 “테스트 실패”라는 알림보다 어느 소비자의 어떤 상호작용이 깨졌는지 보여 주어야 수정이 빠릅니다.
배포 순서가 달라도 안전해야 한다
실제 서비스는 소비자와 제공자가 동시에 배포되지 않습니다. 제공자가 먼저 새 필드를 내보내고 구버전 소비자가 계속 동작할 수도 있고, 새 소비자가 먼저 배포되어 구버전 제공자를 만날 수도 있습니다. 따라서 “최신끼리 통과”만으로는 충분하지 않습니다. 운영 중인 소비자 버전들이 새 제공자 버전과 호환되는지, 반대로 새 소비자가 현재 제공자와 호환되는지 확인해야 합니다. Pact의 제공자 검증 안내도 검증 결과를 공유하고 소비자 배포 판단에 활용하는 흐름을 강조합니다.
계약 테스트가 모든 통합 시험을 대체하지는 않습니다. 두 시스템 간 네트워크 설정, 실제 인증서, 대량 데이터 성능, 비동기 이벤트의 최종 결과는 별도 검증이 필요합니다. 계약 테스트의 강점은 자주 발생하는 인터페이스 불일치를 각 팀의 CI에서 빠르게 잡는 데 있습니다. 처음부터 모든 API를 계약화하기보다 장애 비용이 큰 주문·결제·승인 같은 상호작용 한두 개로 시작하세요. 계약의 소유자, 검증 시점, 실패 시 연락할 팀을 정하면 도구보다 훨씬 오래가는 품질 장치가 됩니다.
