Tavern은 영리한 엔지니어링 작품입니다. pytest에 연결하여 API 테스트를 YAML 파일로 기술하고, 일반 pytest 테스트처럼 해당 파일을 실행합니다. pytest의 전체 생태계를 무료로 얻을 수 있습니다: 픽스처, 플러그인, pytest-xdist를 사용한 병렬 실행, 커버리지, Python 팀이 이미 사용하는 동일한 명령입니다. pytest를 주로 사용하는 백엔드 팀에게는 단위 테스트 옆에 test_*.tavern.yaml 파일을 하나 더 작성하는 것이 자연스럽게 느껴집니다.
문제는 YAML이 커지면서 나타납니다. 본문을 보내고, 토큰을 저장하고, 몇 가지 응답 필드를 확인하는 단일 요청은 request, response, save, verify_response_with 키가 중첩된 블록이 되어 정확하게 들여쓰기를 해야 합니다. 다단계 흐름(로그인, 리소스 생성, 다시 읽기, 삭제)은 이러한 블록을 하나의 긴 파일로 쌓아 올려 잘못된 공백 하나가 파싱을 깨뜨리고, 테스트가 확인하는 API 계약은 완전히 다른 곳에 존재하게 됩니다: 스웨거 파일, 위키 페이지, 몇 달 전에 구식이 된 포스트맨 컬렉션 등입니다.
Tavern의 장점
Tavern은 칭찬받을 만한 점이 많으므로 먼저 장점부터 이야기하겠습니다.
pytest를 대체하는 대신 활용합니다. Tavern은 pytest 플러그인입니다. pip install tavern으로 설치하고, 테스트 디렉토리에 YAML 파일을 놓으면 pytest가 다른 테스트처럼 이를 찾아 실행합니다. 이는 팀이 이미 가지고 있는 모든 pytest 습관을 유지할 수 있다는 의미입니다: 필터링을 위한 -k, 첫 실패 시 중단을 위한 -x, 보고서를 위한 pytest-html, 병렬 실행을 위한 pytest-xdist, 공유 설정을 위한 픽스처. 러너에 대한 아무것도 변경되지 않습니다. Python 개발사에게는 이것이 진정한 장점이며, 기존 스위트에 이렇게 깔끔하게 통합되는 API 테스트 도구는 거의 없습니다.
YAML은 선언적이고 가독성이 좋습니다. 간단한 Tavern 테스트는 실제로 쉽게 읽을 수 있습니다:
test_name: Get a single order
stages:
- name: Fetch order 1042
request:
url: https://api.shop.test/orders/1042
method: GET
response:
status_code: 200
json:
id: 1042
status: shipped
글루 코드(glue code)도 없고, 가져올 어설션 라이브러리도 없으며, 작성할 테스트 하니스(test harness)도 없습니다. 요청과 예상 응답이 나란히 배치됩니다. 상태 코드와 몇 가지 필드를 확인하는 데 있어, 이는 동등한 requests + assert Python 코드보다 더 읽기 쉽습니다.
변수 저장 및 연결. Tavern은 한 응답에서 값을 추출하여 save 및 {variable} 대체를 통해 다음 단계에 주입할 수 있으므로, 사용자 지정 코드 없이 로그인-호출 흐름이 작동합니다:
stages:
- name: Log in
request:
url: https://api.shop.test/auth/login
method: POST
json:
username: tester
password: hunter2
response:
status_code: 200
save:
json:
token: access_token
- name: Read the profile with the saved token
request:
url: https://api.shop.test/me
method: GET
headers:
Authorization: "Bearer {token}"
response:
status_code: 200
HTTP 외에도 다양한 기능을 지원합니다. Tavern은 MQTT도 테스트하는데, 이는 IoT 또는 메시지 구동 시스템에서 작업하는 경우 중요합니다. 그리고 기본적으로 pytest이기 때문에, YAML API 테스트와 일반 Python 테스트를 동일한 실행 및 동일한 보고서에서 혼합할 수 있습니다.
이것들은 마케팅이 아닙니다. Tavern은 견고한 도구입니다. 문제는 그 가정이 당신의 가정과 일치하는지 여부입니다.
YAML 상용구 코드가 쌓이는 곳
Tavern 모델에는 세 가지 비용이 함께 따르며, 이는 스위트의 규모에 따라 중요성이 달라집니다.
YAML은 공백에 민감하며, 스키마가 깊습니다. 위 간단한 예제는 깔끔합니다. 현실적인 테스트는 그렇지 않습니다. 헤더, 쿼리 매개변수, 요청 본문, 응답 본문 어설션, 타입 검사, 저장된 변수, verify_response_with 외부 함수를 추가하면, 잘못된 공백 하나가 명확한 메시지가 아닌 파싱 오류를 일으키는 형식에서 네다섯 단계 깊이로 중첩됩니다. 편집기는 IDE가 Python 메서드를 자동 완성하는 것처럼 Tavern의 키를 자동 완성하지 않으므로, 새 필드를 추가할 때마다 status_code인지 status인지, json인지 body인지 문서를 확인해야 합니다.
테스트와 API 계약은 두 개의 별도 아티팩트입니다. Tavern YAML은 URL, 메서드, 예상 필드 및 해당 타입을 하드코딩합니다. 실제 API 정의는 OpenAPI 파일, 프레임워크의 라우트 데코레이터 또는 아무도 정확히 모르는 어딘가에 있습니다. API가 필드 이름을 변경하면, YAML에는 아무것도 알려주지 않습니다. 테스트는 CI에서 실패하거나, 더 나쁘게는 오래된 예상과 일치하여 계속 통과할 때까지 이전 형태를 계속 어설션합니다. 누군가는 두 가지를 수동으로 동기화해야 하며, 보통 새벽 2시에 실패 메시지를 받는 사람이 그 역할을 맡게 됩니다.
Python 툴체인과 Python 개발자를 가정합니다. 테스터가 Python을 작성하는 경우 Tavern은 훌륭합니다. 하지만 QA 그룹, 프런트엔드 엔지니어 또는 제품 담당자가 테스트를 추가하거나 읽고 싶다면, HTTP 요청을 보내고 응답을 확인하기 위해 pip, 가상 환경, pytest 규칙, YAML 스키마 규칙을 한꺼번에 접해야 합니다. Python 세계 밖에 있는 사람들에게는 진입 장벽이 높습니다.
YAML을 건너뛰는 방법
대안은 텍스트 파일로 테스트를 작성하는 것을 멈추고, 이미 가지고 있는 API 정의에 대해 테스트를 구축하기 시작하는 것입니다.
Apidog에서는 API 사양, 요청, 테스트가 동일한 객체입니다. API를 한 번 가져오거나 설계하고(OpenAPI, Swagger 또는 Postman 컬렉션은 한 번의 클릭으로 가져옴), 각 엔드포인트는 실제 스키마를 함께 가져갑니다. 이러한 엔드포인트를 시각적으로 연결하여 테스트 시나리오를 구축합니다: 로그인 호출을 끌어다 놓고, 토큰이 필요한 호출을 끌어다 놓은 다음, save: 블록이나 {variable} 문자열을 직접 작성하지 않고 값을 전달합니다. 어설션은 기억해야 하는 들여쓰기 된 YAML 키가 아니라 패널의 체크박스와 표현식입니다.
테스트가 사양에 대해 구축되기 때문에, 사양이 단일 진실의 원천이 됩니다. 디자인에서 응답 필드를 변경하면, 이를 참조하는 테스트 시나리오가 조용히 표류하는 대신 변경 사항을 드러냅니다. 이것이 Tavern이 구조적으로 할 수 없는 부분입니다: Tavern의 YAML은 계약으로 다시 연결되는 링크가 없습니다.
그리고 자동화할 때가 오면, Tavern을 매력적으로 만들었던 헤드리스(headless), CI 친화적 속성을 잃지 않습니다. Apidog CLI는 pytest가 오늘날 Tavern 파일을 실행하는 방식과 똑같이, GUI 없이, CI에서 명령줄을 통해 동일한 시나리오를 실행합니다.
Apidog CLI 설치 및 실행
러너는 apidog-cli라는 무료 npm 패키지입니다. 전역적으로 설치하세요:
npm install -g apidog-cli
그런 다음 apidog run 명령으로 테스트 시나리오를 실행합니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
각 부분이 하는 일은 다음과 같습니다:
--access-token은 Apidog 계정에 대한 실행을 인증합니다. 시나리오의 CI/CD 탭에서 토큰을 생성하고 파일에 저장하지 말고 비밀로 저장하세요.-t는 테스트 시나리오 ID입니다.-e는 환경 ID(dev, staging, prod)이므로 동일한 시나리오가 올바른 기본 URL 및 변수를 사용합니다.-r은 리포터를 선택합니다.cli는 터미널에 읽기 쉬운 출력을 인쇄합니다.
이 ID를 모두 기억할 필요는 없습니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 전환한 다음, 명령줄 옵션을 선택하고 토큰 생성을 클릭합니다. Apidog는 시나리오 ID와 환경 ID가 이미 채워진 상태로 전체 apidog run 명령을 생성합니다. 이를 복사한 다음 토큰을 CI 비밀로 이동하세요.
전역적으로 설치하고 싶지 않다면, 특히 임시 CI 러너에서는 npx로 실행하세요:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
리포터는 cli, html, json, junit을 포함합니다. CI의 경우 유용한 조합은 -r html,junit입니다: junit는 거의 모든 CI 대시보드가 통과/실패 트리로 파싱하는 표준 XML을 내보내고, html은 빌드 아티팩트로 보관할 수 있는 탐색 가능한 보고서를 생성합니다. 보고서가 저장될 위치를 제어하려면 --out-dir을 추가하세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
설치된 버전의 전체 플래그 목록을 보려면 apidog run --help를 실행하세요.
비교
| Tavern | Apidog | |
|---|---|---|
| 테스트 형식 | YAML 파일 (*.tavern.yaml) |
사양에 대해 구축된 시각적 시나리오 |
| 런타임 | Python + pytest | 헤드리스 apidog run (npm 패키지) |
| 작성 | YAML을 직접 작성하고 들여쓰기 | 엔드포인트 드래그 앤 체인, 체크박스 어설션 |
| API 계약 | 별도의 아티팩트, 수동으로 동기화 | 사양이 테스트의 단일 진실 원천 |
| 변수 체이닝 | save: 블록 및 {var} 대체 |
UI에서 단계 간 값 전달 |
| 리포터 | pytest-html, pytest 플러그인을 통한 JUnit |
cli, html, json, junit 내장 |
| 테스트를 작성할 수 있는 사람 | Python에 익숙한 테스터 | 비개발자를 포함한 팀의 모든 구성원 |
| 프로토콜 | HTTP 및 MQTT | HTTP, SOAP, WebSocket, gRPC 등 |
팀이 Python에 전적으로 집중하고 테스트를 단위 테스트와 동일한 저장소 및 동일한 pytest 실행에 포함시키고 싶다면 Tavern이 유리합니다. YAML 유지보수를 줄이고, 계약과 테스트를 하나로 유지하며, Python을 작성하지 않는 사람들도 테스트에 기여할 수 있도록 하고 싶다면 Apidog가 유리합니다.
CI에 연결하기
로컬 테스트 파일에서 파이프라인으로 이동하는 핵심은 헤드리스 실행입니다. GitHub Actions 구성은 다음과 같습니다:
name: API tests
on: [push, pull_request]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Install Apidog CLI
run: npm install -g apidog-cli
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r html,junit \
--out-dir apidog-reports
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
- name: Upload report
if: always()
uses: actions/upload-artifact@v4
with:
name: apidog-report
path: apidog-reports
토큰은 저장소 비밀에서 가져와 환경 변수로 단계에 도달합니다. 업로드 단계의 if: always()는 테스트가 실패하더라도 보고서를 계속 받을 수 있음을 의미하며, 이는 보고서를 읽고 싶을 때와 정확히 일치합니다. 어설션이 실패하면 apidog run 단계는 0이 아닌 값으로 종료되고, 작업은 빨간색으로 표시되며, 풀 리퀘스트는 실패하는 검사를 보여줍니다.
이 종료 코드 동작은 품질 게이트이며, Tavern과 동일한 방식으로 작동합니다: CI는 각 단계의 종료 코드를 읽고, 0이 아닌 종료는 작업을 실패로 표시하며, 실패한 작업은 병합 또는 배포를 차단합니다. 이를 위해 추가로 아무것도 구성할 필요가 없습니다. 더 깊은 파이프라인 설정에 대해서는 CI/CD 파이프라인의 Apidog CLI 및 GitHub Actions 튜토리얼에서 GitLab CI 및 Jenkins 변형도 다룹니다.
pytest와 더 넓은 Python 테스트 세계에 대한 참고 사항
Tavern의 YAML에서 벗어난다고 해서 pytest를 포기하는 것은 아닙니다. 많은 팀들이 순수 Python 단위 및 통합 테스트를 pytest에 유지하고, API 계약 계층, 즉 테스트가 사양을 추적하고 Python을 사용하지 않는 기여자도 실행할 수 있어야 하는 부분에는 Apidog를 사용합니다. 이 둘은 상호 배타적이지 않습니다. Tavern의 가치는 항상 pytest 사용자가 원시 requests 코드보다 가벼운 형식으로 API 테스트를 작성할 수 있게 하는 것이었습니다. Apidog의 가치는 이러한 API 테스트가 계약을 추적하고, 파일 몇 개를 넘어서 스위트가 커질 때도 읽기 쉽게 유지되도록 하는 것입니다.
다른 러너를 고려하고 있다면, 동일한 논리가 Postman CLI vs Newman의 Postman 명령줄 스토리와 Postman 없이 API 테스트에서 추가 도구 없이 컬렉션을 실행하는 데에도 적용됩니다.
FAQ
Apidog CLI는 무료인가요? 예. apidog-cli npm 패키지는 npm install -g apidog-cli를 통해 무료로 설치 및 실행할 수 있습니다. Apidog 프로젝트의 테스트 시나리오를 실행하므로, 실행할 수 있는 내용은 Apidog 플랜에 따라 다르지만, 명령줄 러너 자체는 별도의 유료 제품이 아닙니다.
Apidog와 함께 pytest를 계속 사용할 수 있나요? 예. Python 단위 및 통합 테스트는 pytest에 유지하고, API 계약 테스트 계층에는 Apidog를 사용하세요. 많은 팀이 둘 다 실행합니다. 차이점은 Apidog 테스트는 별도의 파일에 하드코딩하는 대신 사양을 추적한다는 것입니다.
Apidog는 CI에서 잘못된 병합을 어떻게 차단하나요? 종료 코드를 통해 차단합니다. 어떤 어설션이라도 실패하면 apidog run은 0이 아닌 값으로 종료됩니다. CI는 해당 종료 코드를 읽고, 단계를 실패로 표시하며, 병합 또는 배포를 차단합니다. 이 기능을 위해 추가로 아무것도 구성할 필요가 없습니다.
CI에 어떤 리포터를 사용해야 하나요? CI 대시보드가 통과/실패 트리로 파싱하는 기계 판독 가능한 결과에는 junit을 사용하고, 아티팩트로 저장할 탐색 가능한 보고서를 원한다면 html을 추가하세요. 일반적인 선택은 -r html,junit이며, 읽기 쉬운 빌드 로그 출력을 위해 cli를 유지합니다.
Apidog는 Tavern의 HTTP 모드처럼 HTTP만 테스트하나요? 아니요. Apidog는 HTTP 외에 SOAP, WebSocket, Server-Sent Events, gRPC를 지원합니다. Tavern은 HTTP에 MQTT를 추가하는데, 이는 프로토콜 지원 면에서 Apidog가 지원하지 않는 유일한 부분이므로, MQTT가 스택의 핵심이라면 이 점을 염두에 두세요.
솔직한 결론
Tavern은 pytest와 YAML에 익숙하다면 API 테스트를 작성하는 깔끔한 방법이며, pytest 통합은 진정으로 최고의 기능입니다. 비용은 YAML 자체입니다: 스위트가 확장될수록 깊고 취약해지며, 확인하는 API 계약으로 다시 연결되는 링크가 없습니다. YAML을 수동으로 들여쓰기하지 않고, 사양의 두 번째 복사본을 유지보수하지 않으면서 동일한 헤드리스, CI에서 명확하게 실패하는 동작을 원한다면, 계약에 대해 테스트를 구축하고 apidog run으로 실행하는 것이 더 가벼운 경로입니다.
약속하기 전에 Apidog를 다운로드하고 기존 API를 가져와 사양-테스트 워크플로를 경험해 보세요. 시작은 무료입니다.