dpdpdndn 블로그

BE-04-kakao-geocoding-contract-test

NEW2 min read

[BE-04] 카카오 지오코딩(Kakao Local REST) 계약 검증 테스트

작업 내용 (설계 의도)

근거 TDD: ../TDD.md “Testing Plan”, ADR-002.

변경 사항

KakaoGeocodingGatewayImpl의 주소→좌표 변환 스키마(documents[].x/y)를 CI 상시 계약 테스트로 락하고, 실 키 존재 시 live 스모크를 추가한다. 프로덕션 코드 무변경(테스트만). BE-02와 같은 test 디렉토리이나 파일이 달라 충돌 없음.

  • fixture test/resources/fixtures/external/kakao-local/address.json — documents[].x(경도)·y(위도) 스키마 캡처.
  • 계약 테스트(infrastructure/facility/gateway/KakaoGeocodingContractTest.kt) — MockWebServer fixture → GeocodingGateway.geocode(address) → Coordinate(lat=y, lng=x) 매핑 검증 + Authorization 헤더(KakaoAK) 전송 확인.
  • 빈 documents·5xx → null degrade 검증(facility geocoding은 이미 graceful).
  • live 태그 스펙 — KAKAO_REST_API_KEY 존재 시 실 API 호출 무손실 역직렬화 확인, 부재 시 스킵.

의존

  • BE-01 (계약 하네스)

다이어그램

처리 흐름

sequenceDiagram
    participant T as ContractTest
    participant M as MockWebServer
    participant G as KakaoGeocodingGatewayImpl
    T->>M: enqueue(address.json)
    T->>G: geocode("서울 강남구 ...")
    G->>M: GET /v2/local/search/address.json (KakaoAK 헤더)
    M-->>G: fixture
    G-->>T: Coordinate(lat=y, lng=x) 검증

클래스 의존

flowchart LR
    CT["KakaoGeocodingContractTest"] --> ECS["ExternalContractSupport(BE-01)"]
    CT --> G["KakaoGeocodingGatewayImpl"]
    G --> GG["GeocodingGateway"]

테스트 케이스

  • fixture documents[0].y가 lat, x가 lng로 매핑된 Coordinate가 반환된다(해피 — 경도/위도 축 뒤바뀜 방지).
  • api-key가 있을 때 Authorization: KakaoAK {key} 헤더가 전송된다(해피).
  • 빈 주소 입력 시 API 호출 없이 null을 반환한다(엣지 — 조기 반환).
  • 빈 documents 또는 5xx(RestClientException) 시 null로 degrade한다(실패/예외).
  • live 스펙: KAKAO_REST_API_KEY 부재 시 스킵된다(스킵 경로).

그래프 뷰