Apidog CLI를 이용한 트래비스 CI API 테스트 자동화 방법

API는 내 머신에서는 잘 작동합니다. 단위 테스트는 모두 통과했습니다. 코드를 병합하고 배포한 지 한 시간 후, 팀원이 메시지를 보냅니다. 장바구니가 비어 있는 사용자는 /checkout 엔드포인트에서 500 에러를 반환한다는 내용이었습니다. 버그는 내가 변경한 코드에 있던 것이 아니었습니다. 두 단계 떨어진 서비스 간의 계약(contract)에 있었고, 아무도 다시 테스트하지 않았던 부분이죠. 이것이 바로 통합(integration) 수준의 API 테스트가 채워주는 간극이며, 누군가의 머릿속에만 있는 것이 아니라 모든 커밋마다 자동으로 실행되기를 원하는 바로 그런 종류의 검사입니다.

Travis CI는 가장 오래된 호스팅형 지속적 통합(CI) 서비스 중 하나이며, 여전히 한 가지를 잘 수행합니다. Git 리포지토리를 감시하고, 모든 푸시 및 풀 리퀘스트에 대해 깨끗한 환경을 구축하며, .travis.yml 파일에 지정된 모든 명령을 실행합니다. 대부분의 팀은 컴파일 및 단위 테스트 루프에 Travis CI를 사용합니다. 하지만 실행 중인 API에 대해 실제 HTTP 테스트를 실행하는 경우는 훨씬 적은데, 바로 그곳에 값비싼 버그들이 숨어있기 때문입니다. 그 이유는 마찰(friction) 때문입니다. CI 박스에 API 테스트 러너를 연결하고, 비밀 정보를 안전하게 전달하며, 성공/실패 신호를 다시 받는 것이 너무 번거로워서 사람들이 건너뛰곤 합니다.

이 가이드는 Apidog 명령줄 러너를 사용하여 그 간극을 메우는 방법을 안내합니다. Apidog 데스크톱 앱에서 API 테스트를 시각적으로 설계하고 디버그하여 요청과 어설션을 확인할 수 있으며, 그 다음 Travis CI 내에서 단일 명령으로 동일한 테스트를 헤드리스 방식으로 실행할 수 있습니다. 테스트 로직을 코드로 다시 작성할 필요도 없고, 별도의 테스트 하네스를 유지보수할 필요도 없습니다. 이 글은 최소한의 .travis.yml 구성, 러너 설치, 접근 토큰 안전하게 전달, 실행할 테스트 선택, 보고서 생성, 엔드포인트가 손상될 때 빌드를 명확하게 실패시키는 방법에 대한 전체 과정을 다룹니다. 따라 하고 싶다면 Apidog를 다운로드하세요.

CI에서 API 테스트를 실행해야 하는 이유

단위 테스트는 함수가 올바른 값을 반환하는지 확인합니다. API 테스트는 전체 요청-응답 사이클이 올바르게 작동하는지 확인합니다: 경로가 존재하는지, 인증이 적용되는지, 상태 코드가 올바른지, JSON 스키마가 일치하는지, 그리고 본문(body) 내부의 값들이 합리적인지 등입니다. 이들은 서로 다른 실패 모드이며, 두 번째 유형은 사용자들이 실제로 경험하는 실패입니다.

로컬에서 테스트를 실행하는 것은 괜찮지만, 언젠가는 문제가 발생합니다. 로컬 실행은 개발자가 테스트 실행을 기억해야 하고, 개발자의 머신이 프로덕션 환경 구성과 일치해야 하며, 회귀 버그가 발생했을 때 커피를 마시고 있지 않아야 합니다. 지속적 통합은 이 세 가지 변명을 모두 제거합니다. 모든 푸시는 동일한 환경에서 동일한 테스트 스위트를 트리거하며, 그 결과는 모든 사람이 볼 수 있도록 커밋 및 풀 리퀘스트에 첨부됩니다.

특히 API 팀에게는 더 깊은 이점이 있습니다. 테스트가 API 설계와 함께 존재할 때, 호환성이 깨지는 변경(breaking change)은 푸시되는 순간 실패하는 어설션(assertion)으로 나타나지, 지원 티켓으로 나타나지 않습니다. 이것이 배포 파이프라인에서 어디에 적합한지에 대한 개념적 배경이 궁금하다면, CI/CD란 무엇인가 설명 글을 함께 읽어보는 것이 좋습니다. 이 글은 Travis CI 빌드에 대한 실용적인 부분에 초점을 맞춥니다.

시작하기 전에 필요한 것

세 가지가 필요하며, 아마도 그 중 두 가지는 이미 가지고 있을 것입니다.

• Travis CI에 연결된 Git 리포지토리. travis-ci.com의 무료 등급은 사용량 제한 내에서 공개 및 비공개 리포지토리 모두에 작동합니다.

• 데스크톱 앱에서 이미 성공적으로 구축하고 실행한 최소 하나 이상의 테스트 시나리오가 포함된 Apidog 프로젝트. Apidog의 테스트 시나리오는 어설션이 있는 순서가 지정된 API 요청 세트입니다. "로그인, 주문 생성, 주문 가져오기, 삭제"와 같은 하나의 엔드투엔드 흐름으로 생각하면 됩니다.
• Node.js. Apidog CLI는 Node에서 실행되며, 버전 16 이상이 필요합니다. Travis는 node_js 언어 환경에서 Node를 기본으로 제공하므로, 대부분 한 줄 선언으로 해결됩니다.

아직 테스트 시나리오를 구축하지 않았다면, 앱에서 먼저 구축하세요. 이 워크플로우의 요점은 한 번 시각적으로 디버그한 다음 영원히 자동화하는 것입니다. CI 로그 내에서 테스트를 맹목적으로 작성하려고 시도하는 것은 느린 길입니다. 좋은 검사를 작성하는 기본 사항에 대해서는 API 어설션: 실용 가이드에서 푸시하기 전에 상태 코드, 응답 본문 및 JSON 스키마를 검증하는 방법을 다룹니다.

1단계: 접근 토큰 및 시나리오 ID 가져오기

Apidog CLI는 클라우드에 저장된 테스트를 헤드리스 방식으로 실행하므로, 두 가지 신원 정보가 필요합니다.

1. 러너가 프로젝트를 읽을 수 있도록 허용함을 증명하는 **접근 토큰**. Apidog 계정 설정의 접근 토큰 섹션에서 생성하세요. 비밀번호처럼 취급해야 합니다. 프로젝트 데이터에 대한 API 접근 권한을 부여합니다.
2. **테스트 시나리오 ID.** 데스크톱 앱에서 시나리오를 열고 해당 ID를 복사하거나, "CI/CD에서 실행" 옵션을 사용하여 ID가 이미 채워진 명령을 생성할 수 있습니다.

올바른 첫 명령을 얻는 가장 쉬운 방법은 Apidog가 대신 작성하도록 하는 것입니다. 테스트 시나리오 내에서 CI/CD 실행 옵션은 다음과 같은 것을 생성합니다.

apidog run --access-token <your-access-token> -t 5564321 -e 4417023 -r cli

이것이 전체 형태입니다: 인증, 시나리오 지정(-t), 환경 지정(-e), 리포터 선택(-r). 이것을 복사하여 먼저 자신의 노트북에서 실행되는지 확인한 다음, Travis로 옮기세요. 로컬에서 확인하면 토큰의 오타를 디버그하는 데 드는 수십 번의 실패 빌드를 절약할 수 있습니다.

2단계: 토큰을 암호화된 Travis 변수로 저장

접근 토큰을 .travis.yml에 절대로 붙여넣지 마세요. 이 파일은 Git에 커밋되며, 토큰이 유출되면 누구나 API 프로젝트에 대한 읽기 접근 권한을 갖게 됩니다. Travis에는 두 가지 안전한 옵션이 있습니다.

깔끔한 방법은 Travis 웹 UI에서 리포지토리 환경 변수를 설정하는 것입니다. Travis에서 리포지토리 설정으로 이동하여 환경 변수를 찾아 다음을 추가합니다:

• APIDOG_ACCESS_TOKEN (토큰 값 포함)
• APIDOG_ENV_ID (테스트할 환경 ID 포함)

"빌드 로그에 값 표시" 토글은 끄세요. 그래야 토큰이 인쇄되지 않습니다. Travis는 이들을 모든 빌드에 실제 환경 변수로 주입하며, 구성은 이름으로 이들을 참조합니다. 이렇게 하면 비밀 정보가 리포지토리에서 완전히 분리되어, 원하는 동작을 얻을 수 있습니다. 기여자가 리포지토리를 포크해도 토큰은 함께 이동하지 않습니다.

모든 것을 파일에 담는 것을 선호한다면, Travis는 CLI를 통해 암호화된 변수도 지원합니다:

travis encrypt APIDOG_ACCESS_TOKEN="your-token-here" --add env.global

이것은 리포지토리의 빌드만 해독할 수 있는 암호화된 데이터를 .travis.yml에 작성합니다. 두 접근 방식 모두 작동합니다. 대부분의 팀에게는 UI 경로가 더 간단하고 토큰이 만료되었을 때 교체하기 더 쉽습니다.

3단계: .travis.yml 작성

다음은 Apidog CLI를 설치하고 모든 푸시 및 풀 리퀘스트에 대해 하나의 시나리오를 실행하는 완전하고 최소한의 구성입니다:

language: node_js
node_js:
  - "18"

cache:
  npm: true

install:
  - npm install -g apidog-cli

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli

세 가지 블록이 작업을 수행합니다. language: node_js와 버전은 CLI에 충분히 새로운 Node 런타임을 제공합니다. install 단계는 apidog-cli를 전역으로 설치하여 apidog 명령이 경로에 있도록 합니다. script 단계는 테스트를 실행합니다. -r cli 리포터는 가독성 있는 성공/실패 요약을 Travis 로그에 직접 출력하며, 무언가 고장났을 때 보게 될 내용입니다.

시나리오 ID는 하드코딩되어 있지만 비밀 정보는 환경 변수에서 가져옵니다. 이것이 올바른 분할입니다: ID는 민감하지 않지만, 토큰은 민감합니다. 이 파일을 커밋하고 푸시하면 Travis가 API 테스트를 자동으로 실행합니다. 첫 번째 성공(green) 빌드는 API가 안전망을 갖추는 순간입니다.

여러 서비스를 유지보수하고 러너 간에 공유된 개념 모델을 원한다면, CI/CD에서 API 테스트 자동화 가이드는 다른 플랫폼에 적용된 동일한 패턴을 보여주며, GitHub Actions 버전은 나중에 마이그레이션할 경우 정신적으로 거의 동일합니다.

4단계: 테스트 실패 시 빌드 실패시키기

이것은 팀들이 잊어버리는 부분이며, 조용히 전체 작업을 무력화시킵니다. CI 작업은 실패하는 테스트가 빌드를 실패(red)로 만들 때만 유용합니다. 러너가 어떤 상황에서도 0을 반환한다면, 매우 비싼 로그 프린터를 만든 셈이 됩니다.

좋은 소식: Apidog CLI는 이미 올바른 작업을 수행합니다. 어설션이 실패하면 apidog run 프로세스는 0이 아닌 상태 코드로 종료되며, Travis는 script 단계에서 0이 아닌 모든 종료를 빌드 실패로 처리합니다. 따라서 위의 최소 구성은 이미 기본적으로 올바르게 실패합니다. 추가적인 연결 작업이 필요하지 않습니다.

조정할 수 있는 부분은 단일 요청 오류가 발생했을 때 시나리오 중간에 실행이 어떻게 동작할지입니다. --on-error 플래그가 이를 제어합니다:

• --on-error end는 첫 번째 실패에서 시나리오를 중지합니다. 가장 빠른 피드백을 제공하지만, 출력은 적습니다.
• --on-error continue는 나머지 단계를 실행하여 한 번에 모든 실패를 볼 수 있도록 합니다.
• --on-error ignore는 계속 진행하며 오류가 실행을 중지하지 못하게 합니다.

CI의 경우, continue가 일반적으로 가장 적절한 지점입니다. 첫 번째 실패 어설션 후에 작업이 중단되지 않고 무엇이 고장났는지 전체 그림을 보고 싶으면서도, 빌드를 실패시키기 위해 0이 아닌 종료 코드를 유지하고 싶을 때 유용합니다. 합리적인 스크립트 라인은 다음과 같습니다:

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli --on-error continue

명령에 || true를 추가하여 "빌드를 통과시키려는" 유혹을 피하세요. 그렇게 하면 종료 코드를 무시하고 제거하려고 했던 바로 그 사각지대를 다시 도입하게 됩니다.

5단계: HTML 보고서 생성 및 유지

cli 리포터는 빠른 확인에 적합하지만, 빌드가 실패할 때 종종 더 풍부한 아티팩트(어떤 요청, 어떤 어설션, 실제 응답 본문 등)를 원하게 됩니다. CLI는 html 리포터를 사용하여 HTML 보고서를 생성하며, 한 번의 실행에서 여러 리포터를 스택할 수 있습니다.

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -r cli,html --out-dir ./apidog-reports

-r cli,html은 로그에 출력하고 독립형 HTML 파일을 작성합니다. --out-dir은 보고서가 저장될 위치를 설정하며, 기본값은 ./apidog-reports입니다. 빌드가 끝난 후에도 해당 보고서를 유지하려면, deploy 블록에서 S3 버킷이나 GitHub Pages와 같이 Travis가 배포할 수 있는 곳에 배포하세요. 일반적인 패턴은 다음과 같습니다:

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: apidog-reports
  on:
    branch: main

아티팩트 스토리지를 전혀 관리하고 싶지 않다면, CLI는 --upload-report를 사용하여 보고서를 Apidog 클라우드로 푸시할 수 있으며, 팀은 추가 호스팅 없이 링크를 통해 열 수 있습니다. 이는 분산 팀에게 가장 낮은 유지보수 옵션입니다.

6단계: 환경, 데이터 및 매트릭스 실행 추가

단일 환경에 대한 단일 시나리오는 좋은 시작입니다. 실제 파이프라인은 세 가지 방향으로 확장되며, CLI 플래그는 각 방향에 명확하게 매핑됩니다.

여러 환경. -e 플래그는 사용할 환경의 기본 URL과 변수를 선택합니다. 환경 ID를 바꿔가며 모든 푸시에 대해 스테이징 환경에서, 야간 크론 빌드에 대해 프로덕션 환경에서 동일한 시나리오를 실행하세요. Travis 크론 작업은 설정 UI에서 리포지토리별로 구성됩니다.

데이터 기반 실행. -d 플래그(긴 형식 --iteration-data)는 CSV 또는 JSON 파일을 시나리오에 공급하여 각 행마다 한 번씩 실행되도록 합니다. 이것은 유효한 입력, 누락된 필드, 과도한 페이로드, 특수 문자 등 모든 엣지 케이스를 하나의 시나리오 정의에서 다루는 방법입니다. 파일 기반 반복 대신 고정된 수의 반복을 원할 때는 -n (--iteration-count)과 함께 사용하세요.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564321 -e $APIDOG_ENV_ID -d ./test-data.csv -r cli

병렬 시나리오. Travis 빌드 매트릭스를 사용하면 여러 시나리오를 병렬 작업에서 동시에 실행할 수 있습니다. 각 항목이 다른 시나리오 ID를 포함하는 환경 변수 매트릭스를 정의하고, 각 매트릭스 작업은 하나를 실행합니다. 빌드는 모든 작업이 통과해야 성공(green)으로 간주됩니다.

env:
  - SCENARIO_ID=5564321   # checkout flow
  - SCENARIO_ID=5564322   # auth flow
  - SCENARIO_ID=5564323   # search flow

script:
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t $SCENARIO_ID -e $APIDOG_ENV_ID -r cli

스위트가 커짐에 따라, 시나리오를 자동화된 API 테스트를 위한 테스트 스위트로 구성하면 매트릭스가 ID의 벽이 되는 대신 관리하기 쉽게 유지됩니다.

CI 스크립트에서 테스트를 직접 코딩하는 것보다 이것이 더 나은 이유

curl과 jq를 사용하여 Travis 스크립트에 API 테스트를 직접 작성하거나, 내보낸 컬렉션을 Newman으로 실행할 수도 있습니다. 둘 다 작동하지만, 둘 다 시간이 지남에 따라 나빠집니다.

curl과 셸 스크립트 방식은 모든 어설션을 깨지기 쉬운 문자열 비교로 만듭니다. 중첩된 JSON 필드를 확인하는 것은 jq 마법이 되고, 스키마를 확인하는 것은 기본적으로 불가능합니다. 그리고 API에 필드가 추가되는 순간, 절반의 `grep`이 다시 작성되어야 합니다. 결국 Bash에서 API 지식의 두 번째, 더 나쁜 복사본을 유지보수하게 됩니다.

컬렉션 러너 방식은 더 낫지만, CI를 내보내기-동기화 의식에 묶어놓습니다. 한 도구에서 테스트를 편집하고, 내보내고, JSON을 커밋하며, 현실과 멀어지지 않기를 바랍니다. 이러한 편차는 실제하며, "테스트는 통과하지만 API가 고장났다"는 불평의 원인입니다. 우리는 Postman 컬렉션이 진실의 근원이 아닌 이유에 대해 이 정확한 실패 모드를 작성했으며, 오늘날 CI에서 컬렉션을 실행하고 있다면, Newman 없이 CI에서 Postman 컬렉션을 실행하는 방법에서 마이그레이션 경로를 다룹니다.

Apidog 모델은 루프를 단축시킵니다. 테스트, API 설계, 환경 및 목 서버가 한 곳에 있습니다. CLI는 해당 테스트의 실시간, 최신 버전을 실행합니다. 내보낼 것도 없고, 벗어날 것도 없습니다. 앱에서 불안정한 어설션을 시각적으로 디버그하고 저장하면, 다음 CI 실행이 변경 사항을 반영합니다. 이 단일 진실 공급원(single source of truth)이 셸 스크립트 더미 대신 전용 러너를 사용하는 전체 이유입니다. 현재 설정과 비교하여 평가하고 있다면, API 테스트를 위한 최고의 Postman 대안 비교 글이 옵션을 나란히 놓고 설명합니다.

Travis CI에 대한 특별 참고 사항

Travis는 수년 동안 오픈 소스 CI의 기본이었고, 많은 오래된 리포지토리가 여전히 Travis에서 실행됩니다. 2026년에 새로 시작한다면, 이 분야가 변화했다는 점을 아는 것이 좋습니다. GitHub Actions, GitLab CI, CircleCI가 현재 대부분의 새로운 프로젝트를 처리하며, 최고의 CI/CD 도구 비교 글은 각 도구가 어디에 적합한지 분석합니다. 좋은 소식은 Apidog CLI가 처음부터 플랫폼 독립적으로 설계되었다는 것입니다. .travis.yml에서 작동하는 것과 동일한 apidog run 명령은 GitHub Actions 단계, GitLab .gitlab-ci.yml 또는 Jenkins 스테이지에서도 작동합니다. Travis에서 다른 플랫폼으로 이동하더라도 API 테스트는 변경 없이 이동합니다. 주변의 YAML 키만 다를 뿐입니다. 이러한 이식성은 CI 특정 구문에서 테스트 로직을 분리함으로써 얻을 수 있는 조용하지만 실제적인 이점입니다.

자주 묻는 질문

CI 박스에 Apidog 데스크톱 앱을 설치해야 하나요? 아니요. 데스크톱 앱은 테스트를 설계하고 디버그하기 위한 것입니다. Travis는 apidog-cli npm 패키지와 Node 16+ 런타임만 필요하며, 이는 node_js 언어 환경에서 이미 제공됩니다. CLI는 클라우드에 저장된 시나리오를 헤드리스 방식으로 가져와 실행합니다.

접근 토큰과 시나리오 ID는 어디서 찾을 수 있나요? 접근 토큰은 Apidog 계정 설정의 접근 토큰 섹션에서 생성할 수 있습니다. 시나리오 ID는 각 테스트 시나리오의 데스크톱 앱에서 볼 수 있습니다. 내장된 "CI/CD에서 실행" 옵션은 ID가 미리 채워진 전체 명령을 생성하므로, 작동하는 기준선을 얻는 가장 빠른 방법입니다.

토큰을 리포지토리 외부에 어떻게 유지하나요? Travis 웹 UI에서 빌드 로그 표시를 끈 상태로 리포지토리 환경 변수로 설정한 다음, 구성에서 $APIDOG_ACCESS_TOKEN으로 참조하세요. 또는 travis encrypt를 사용하여 암호화된 값을 .travis.yml에 저장할 수 있습니다. 원시 토큰을 절대로 커밋하지 마세요.

테스트가 실패하면 빌드가 실제로 실패하나요? 예. 어설션이 실패하면 apidog run 명령은 0이 아닌 값으로 종료되며, Travis는 script 단계에서 0이 아닌 모든 종료를 실패한 빌드로 처리합니다. 다만 || true로 종료 코드를 억제하지 마세요. 모든 실패를 한 번의 실행에서 보고하면서도 빌드를 실패시키고 싶다면 --on-error continue를 사용하세요.

여러 환경에 대해 또는 여러 데이터 세트로 테스트를 실행할 수 있나요? 예. -e를 사용하여 환경을 전환하고(푸시 시 스테이징, 야간 크론 시 프로덕션), -d를 사용하여 CSV 또는 JSON 데이터 파일을 데이터 기반 반복을 위해 공급하고, Travis 빌드 매트릭스를 사용하여 여러 시나리오를 병렬 작업에서 실행할 수 있습니다.

Travis CI를 사용하지 않는 경우에도 이것을 사용할 수 있나요? 예. CLI 명령은 플랫폼마다 동일합니다. GitHub Actions, GitLab CI 또는 Jenkins의 주변 YAML을 바꾸면 apidog run 라인은 동일하게 유지됩니다.

마무리

API 테스트를 Travis CI에 통합하는 것은 네 가지 핵심 단계로 요약됩니다. 접근 토큰을 암호화된 변수로 저장하고, 설치 단계에서 apidog-cli를 설치하고, 스크립트 단계에서 apidog run으로 시나리오를 실행하며, 0이 아닌 종료 코드가 빌드를 실패하도록 두는 것입니다. 그 다음부터는 스위트가 성장함에 따라 HTML 보고서, 여러 환경, 데이터 기반 반복 및 병렬 매트릭스를 계층적으로 추가합니다.

수많은 curl 호출 대신 전용 러너를 사용하는 이유는 단일 진실 공급원(single source of truth) 때문입니다. 시각적으로 설계하고 디버그한 다음, 모든 커밋마다 해당 테스트의 라이브 버전을 실행하며, 동기화 오류가 발생할 수 있는 내보내기 단계가 없습니다. /checkout 회귀 버그는 프로덕션이 아닌 풀 리퀘스트에서 발견됩니다.

첫 번째 테스트 시나리오를 구축한 다음, Apidog를 다운로드하여 다음 푸시에 연결하세요. 첫 번째 빌드가 성공(green)으로 바뀌면, 그 이후의 모든 커밋은 안전망을 갖추게 됩니다.