dpdpdndn 블로그

BE-01-external-contract-test-harness

NEW3 min read

[BE-01] 외부 API 계약 검증 하네스 (MockWebServer + live 태그 + gradle task)

작업 내용 (설계 의도)

근거 TDD: ../TDD.md “Possible Solutions 방안 B”, ADR-002.

변경 사항

후행 계약 테스트 3종(BE-02/03/04)이 공통으로 import하는 검증 하네스를 선행 확립한다. 연관 병목(테스트 의존성 + 공통 지원 + gradle task)을 하나로 묶어 wave 1에 끝낸다.

  • backend/build.gradle.kts에 okhttp mockwebserver 테스트 의존성 추가.
  • verifyExternalLive gradle task 정의 — live 태그 스펙만 실행(기본 test에서 live 태그 제외). 키가 env에 있을 때만 실 API를 호출하는 opt-in 실행 경로.
  • 공통 지원 ExternalContractSupport (test, infrastructure/external) — MockWebServer 기동 헬퍼, test/resources/fixtures/external/** fixture 로더, requireLiveKey(envName)(null이면 live 스펙 스킵) 제공.
  • fixture 디렉토리 규약 확립: backend/src/test/resources/fixtures/external/{issuer}/{service}.json.

Kotest 태그 필터로 live를 분리한다(클래스별 와이어업 불요 — BE-02/03/04는 태그만 부여). 마지막 통합 티켓이 필요 없는 트리형 구조.

의존

  • 없음 (선행 병목)

다이어그램

처리 흐름

sequenceDiagram
    participant T as ContractTest(후행)
    participant S as ExternalContractSupport
    participant M as MockWebServer
    T->>S: startMockServer()
    S-->>T: MockWebServer(url)
    T->>S: loadFixture("external/kakao-local/address.json")
    S-->>T: json
    T->>M: enqueue(json)
    Note over T,S: requireLiveKey(env)==null 이면 live 스펙 skip

클래스 의존

flowchart LR
    BE02["BE-02 test"] --> ECS["ExternalContractSupport"]
    BE03["BE-03 test"] --> ECS
    BE04["BE-04 test"] --> ECS
    ECS --> MW["MockWebServer(okhttp)"]
    GT["verifyExternalLive task"] --> TAG["Kotest live tag"]

테스트 케이스

  • startMockServer()가 기동한 서버 URL로 GET 요청 시 enqueue한 fixture 본문이 그대로 반환된다.
  • loadFixture()가 존재하는 fixture 경로를 읽어 비어 있지 않은 JSON 문자열을 반환한다.
  • 존재하지 않는 fixture 경로를 loadFixture()에 주면 명확한 예외 메시지로 실패한다(엣지).
  • requireLiveKey("KAKAO_REST_API_KEY")가 env 부재 시 null을 반환해 live 스펙이 스킵된다(실패/스킵 경로).
  • ./gradlew verifyExternalLive가 live 태그 스펙만 선택하고 일반 계약 테스트는 실행하지 않는다.

그래프 뷰