OpenAPI 파일을 관리하지만 실행 중인 서비스가 서서히 사양에서 벗어나는 경우, Specmatic은 바로 그 간극을 위해 만들어졌습니다. Specmatic은 사양을 실행 가능한 계약으로 취급한 다음, 실제 서비스를 대상으로 테스트하고 동일한 사양을 스마트 스텁으로 실행합니다. 이 가이드에서는 Specmatic이 무엇을 하는지, 계약 테스트가 예제 기반 테스트와 어떻게 다른지, 그리고 이 도구가 어디에 적합한지 설명하며, Apidog의 API 계약 테스트와 같은 광범위한 플랫폼 접근 방식과 어떻게 비교되는지에 대한 내용도 다룹니다. 이 모든 것의 기반이 되는 사양 형식으로는 OpenAPI Specification이 Specmatic이 읽어들이는 정보의 원천입니다.
Specmatic이란 무엇인가
Specmatic은 계약 기반 개발을 위한 오픈 소스 도구입니다. 핵심 아이디어는 간단합니다. API 사양이 계약이며, Specmatic은 이 계약을 실행 가능하게 만듭니다. OpenAPI 파일을 가리키면 두 가지 보완적인 작업을 수행할 수 있습니다.
- 사양을 실시간 서비스에 대한 테스트로 실행하여, 서비스가 사양에서 약속하는 모든 경로, 상태 코드 및 스키마를 준수하는지 확인합니다.
- 사양을 스텁 서버로 실행하여, 소비자가 계약에 명시된 대로 정확히 응답하는 목(mock)을 대상으로 개발할 수 있도록 합니다.
두 작업 모두 동일한 파일을 읽습니다. 별도의 "테스트 정의"와 "사양"을 동기화할 필요가 없으며, 이것이 핵심입니다. Specmatic은 OpenAPI를 넘어섭니다. 버전 2.0에서는 GraphQL과 gRPC를 추가했으며, Kafka 스타일 이벤트 계약을 위한 AsyncAPI, 그리고 WSDL 및 Avro와 같은 형식도 지원합니다. 하지만 대부분의 팀에게는 일반 OpenAPI YAML 또는 JSON 파일이 진입점입니다.
명령줄 또는 Docker 이미지에서 실행할 수 있으므로, 별도의 복잡한 과정 없이 CI에 쉽게 통합됩니다. 개발사는 상업용 애드온을 제공하지만, 계약 엔진 자체는 무료 오픈 소스입니다.
계약 테스트 vs 예제 테스트
이것은 대부분의 사람들을 혼란스럽게 하는 차이점이므로, 정확하게 설명할 가치가 있습니다.
예제 기반 테스트는 대부분의 API 클라이언트에서 수행하는 것입니다. 요청을 작성하고, 받은 응답에 대해 단언하며, 상태 코드와 한두 개의 필드를 확인할 수도 있습니다. 각 테스트는 수동으로 작성된 예제입니다. 사양에 40개의 엔드포인트가 있다면, 많은 예제를 작성하고 유지 관리해야 하며, 누락된 부분을 놓치기 쉽습니다.
계약 테스트는 모델을 뒤집습니다. 특정 예제에 대해 단언하는 대신, 서비스가 계약과 일치하는지 단언합니다. Specmatic은 스키마를 읽고 이를 기반으로 테스트를 생성합니다. 응답이 선언된 유형에 부합하는지, 필수 필드가 존재하는지, 상태 코드가 일치하는지, 그리고 서비스가 사양이 암시하는 방식으로 잘못된 형식의 요청을 거부하는지 확인합니다. 단언문을 하나씩 작성할 필요가 없습니다. 사양이 곧 단언문입니다.
| 측면 | 예제 기반 테스트 | Specmatic을 이용한 계약 테스트 |
|---|---|---|
| 진실의 원천 | 수동으로 작성된 테스트 케이스 | OpenAPI 사양 자체 |
| 유지 관리 대상 | 각 요청 및 단언 | 어차피 유지하는 사양 |
| 커버리지 | 기억하고 작성한 내용만 | 사양이 선언하는 모든 작업 |
| 드리프트 감지 | 수동 | 사양 변경 시 자동 |
| 일반적인 실패 | 특정 예제가 고장남 | 서비스가 더 이상 계약과 일치하지 않음 |
언급할 가치가 있는 두 번째 측면이 있습니다. 계약 테스트에는 여러 종류가 있으며, Specmatic은 그중 특정 한 가지에 속합니다. Pact 스타일의 소비자 주도 계약 테스트는 소비자가 브로커에게 기대치를 게시하고, 공급자는 그 기대치에 대해 검증합니다. 반면 Specmatic은 계약 주도 테스트를 수행합니다. 즉, 사양은 양측이 동의하는 단일 계약이며, Specmatic은 이를 기반으로 공급자를 검증하고 소비자에게는 공급자를 스텁으로 제공합니다. Specmatic은 Pact 브로커가 아니며, 소비자가 게시한 팩트를 관리하지 않습니다. 더 넓은 그림을 원하시면 API 계약 테스트 및 목(mock) 도구에 대한 이 개요를 참조하십시오.
Specmatic 실행 방법
CLI를 직접 설치하거나 Docker 이미지를 가져올 수 있습니다. Docker는 로컬 런타임 설정이 필요 없으므로 CI에서 주로 선택됩니다.
계약 테스트 실행
테스트 명령은 Specmatic이 사양과 실행 중인 서비스를 대상으로 하도록 합니다. 최소한의 로컬 실행은 다음과 같습니다.
# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
Specmatic은 api.yaml을 읽고, 해당 파일에 설명된 작업에 대한 요청을 생성하며, 이를 기본 URL로 전송하고, 모든 응답을 스키마에 대해 검증합니다. 테스트가 실패한다는 것은 서비스와 계약이 일치하지 않는다는 것을 의미합니다. 둘 중 하나를 수정해야 합니다. 이것이 반복 주기입니다.
사양을 스텁으로 실행하기
스텁 서버는 나머지 절반입니다. 이를 시작하면 Specmatic이 계약과 일치하는 응답을 제공하므로, 프론트엔드 또는 다운스트림 서비스는 실제 백엔드가 존재하기 전에 이를 대상으로 구축할 수 있습니다.
specmatic stub api.yaml --port=9000
기본적으로 Specmatic은 즉석에서 스키마에 유효한 응답을 생성합니다. 또한 구체적인 예제를 사양 옆의 _examples 디렉토리에 저장할 수 있으며, 요청이 일치하면 스텁이 해당 예제를 반환합니다. 이는 실제 백엔드를 구축하지 않고도 현실적이고 제어 가능한 데이터를 제공합니다. 여러 도구의 스텁 및 목(mock) 옵션을 비교하고 있다면, 계약 테스트 및 목 서버에 대한 요약에서 Specmatic의 위치를 확인할 수 있습니다.
Specmatic은 또한 사양을 처음부터 만드는 데 도움을 줄 수 있습니다. 기존 서비스 앞에 프록시로 위치하여 실제 트래픽을 캡처하고, 이를 통해 OpenAPI 문서와 예제 파일을 생성할 수 있습니다. 이는 서비스는 있지만 아직 테스트할 공식 사양이 없을 때 유용합니다.
계약 및 스텁으로서의 사양 모델
하나의 파일을 테스트와 스텁으로 모두 실행하는 것이 왜 중요한지 설명합니다. 사양이 계약일 때, 테스트 측과 스텁 측은 동일한 문서를 읽기 때문에 절대 불일치할 수 없습니다.
- 공급자 팀은 CI에서
specmatic test를 실행합니다. 사양을 업데이트하지 않고 API를 변경하면 계약 테스트가 실패합니다. - 소비자 팀은 로컬에서
specmatic stub을 실행합니다. 그들은 동일한 계약과 일치하는 것이 보장된 응답을 대상으로 개발합니다.
따라서 사양은 아무도 신뢰하지 않는 오래된 문서가 아니라 살아있는 합의가 됩니다. 이것이 스텁과 더 풍부한 목(mock)의 차이점이며, 워크플로우를 설계하기 전에 API 스터빙 vs 목킹의 기본 아이디어를 이해하는 것이 중요합니다.
Specmatic은 또한 하위 호환성 검사 기능을 추가합니다. backward-compatibility-check 명령은 사양의 새 버전에서 스텁을 시작하고, 이전 버전에서 테스트를 생성하여 새 스텁에 대해 실행합니다. 이전에 작동하던 것이 더 이상 작동하지 않으면 출시 전에 알 수 있습니다. 이는 독립적으로 배포되는 마이크로서비스에 강력한 안전장치이며, 양방향 계약 테스트에서 다루는 더 넓은 아이디어의 한 형태입니다.
Specmatic이 적합한 경우
Specmatic은 다음 사항들이 팀에 해당될 때 그 가치를 발휘합니다.
- 귀하의 OpenAPI (또는 AsyncAPI, GraphQL, gRPC) 사양이 실제적이고 합리적으로 완전할 때.
- 동기화 상태를 유지해야 하는 별도의 공급자 및 소비자 팀 또는 서비스가 있을 때.
- 사양 드리프트가 검토 중에 발견되는 것이 아니라 빌드를 자동으로 실패시키기를 원할 때.
- CLI 및 CI 우선 워크플로우에 익숙할 때.
사양을 유지하지 않거나, API를 설계하고 탐색하기 위한 시각적 작업 공간을 원하거나, 임시 디버깅, 문서화 및 팀 협업을 하나의 도구로 처리하기를 원한다면 적합하지 않습니다. Specmatic은 계약 엔진에 집중하며, 그 한 가지 작업을 잘 수행합니다.
이러한 집중은 Apidog와 같은 플랫폼이 다른 형태를 취하는 지점이기도 합니다. Apidog도 동일하게 스키마 기반입니다. OpenAPI 사양을 읽고, 스키마에 대해 응답을 검증하며, 코드 없이 OpenAPI 스키마에서 목(mock) 서버를 실행합니다. 솔직한 차이점은 범위입니다. Specmatic은 날카롭고 CLI 기반의 계약 도구입니다. Apidog는 시각적 편집기를 통해 설계, 테스트, 목킹 및 문서를 하나의 작업 공간으로 통합하므로, 작업하는 동안 사양, 테스트 및 목이 함께 존재하고 동기화 상태를 유지합니다. Apidog는 Pact 스타일의 소비자 주도 계약 브로커도 아니므로, 팀에서 특정하게 팩트 브로커가 필요한 경우 두 도구 모두 해당하지 않습니다.
이러한 작업 공간 내에서 사양에서 직접 실행 가능한 테스트를 생성하려면, Apidog가 OpenAPI 사양에서 API 테스트 컬렉션 생성을 처리하는 방법을 확인하십시오.
자주 묻는 질문
Specmatic은 무료인가요?
네. 핵심 계약 엔진은 오픈 소스이며 CLI 또는 Docker에서 무료로 사용할 수 있습니다. 주변에 상업적 오퍼링이 있지만, 비용을 지불하지 않고도 OpenAPI 사양에서 계약 테스트 및 스텁 서버를 실행할 수 있습니다. 유료 플랜에 대한 현재 자세한 내용은 공식 사이트 및 GitHub를 확인하십시오.
Specmatic은 OpenAPI에서만 작동하나요?
아니요. OpenAPI가 가장 일반적인 진입점이지만, Specmatic은 이벤트 기반 계약을 위한 AsyncAPI, 그리고 버전 2.0부터는 GraphQL과 gRPC도 지원하며, WSDL 및 Avro와 같은 형식도 지원합니다. 모든 형식에서 모델은 동일합니다. 즉, 사양이 실행 가능한 계약입니다. 해당 형식 자체에 익숙하지 않다면 이 OpenAPI Specification 튜토리얼부터 시작하십시오.
Specmatic은 Pact와 동일한가요?
정확히는 아닙니다. Pact는 소비자 주도입니다. 소비자가 브로커에게 기대치를 게시하고 공급자가 이에 대해 검증합니다. Specmatic은 계약 주도입니다. 사양이 단일 공유 계약이며, Specmatic은 이를 기반으로 공급자를 검증하고 소비자에게는 공급자를 스텁으로 제공합니다. 둘 다 통합 시 예상치 못한 문제를 줄여주지만, 계약을 구성하는 방식이 다릅니다.
Specmatic이 OpenAPI 사양을 생성해 줄 수 있나요?
네. Specmatic은 기존 서비스 앞에 프록시로 실행되어 실제 요청 및 응답 트래픽을 캡처하고, 이를 통해 OpenAPI 문서와 예제 파일을 생성할 수 있습니다. 이는 작동하는 서비스는 있지만 아직 테스트할 공식 사양이 없을 때 유용합니다.
결론
Specmatic은 특정하고 실제적인 문제에 대한 해답을 제공합니다. 즉, 실행 중인 서비스가 따라야 할 OpenAPI 사양에 대해 정직하게 유지되도록 하는 것입니다. 사양을 실행 가능하게 함으로써, 하나의 파일에서 계약 테스트와 일치하는 스텁을 제공하며, 여기에 하위 호환성 검사 기능까지 추가합니다. 터미널과 CI 환경에서 주로 작업하고 견고한 사양을 유지한다면 Specmatic은 완벽하게 들어맞습니다.
동일한 OpenAPI 파일을 읽는 하나의 시각적 작업 공간에서 계약, 테스트, 목(mock) 및 문서를 모두 가지고 싶다면 Apidog를 사용해보세요. Apidog는 스키마에 대해 응답을 검증하고, 코드 없이 엔드포인트를 목킹하며, 사양을 실행 가능한 테스트 컬렉션으로 변환합니다. Apidog를 다운로드하여 사양을 지정하고 전체 설계-테스트 루프를 한 곳에서 확인하십시오.