API 테스트를 작성했습니다. 테스트는 개발자님의 컴퓨터에서는 통과합니다. 하지만 테스트는 딱 거기까지입니다. 왜냐하면 테스트를 실행하는 것은 누군가 기억해야 할 일이기 때문이죠. 팀원이 금요일 오후에 변경사항을 배포하고, 인증 엔드포인트는 특정 코드 경로에서 조용히 500 오류를 반환하기 시작하며, 이를 처음 알게 되는 사람은 월요일의 사용자입니다. 테스트 커버리지는 항상 존재했지만, 회귀를 감지할 수 있었던 바로 그 순간에 아무도 테스트를 실행하지 않았습니다.
해결책은 테스트를 에디터에서 파이프라인으로 옮겨, 사람의 개입 없이 모든 푸시에 대해 실행되도록 하는 것입니다. 즉, API 테스트를 헤드리스로 실행하고, 명확한 통과 또는 실패를 반환하며, 현재 사용 중인 모든 CI 시스템에 통합될 수 있는 명령이 필요합니다. Apidog CLI가 이 역할을 수행합니다. Apidog에서 시각적으로 테스트 시나리오를 구축한 다음, Node.js가 설치된 모든 CI 러너가 실행할 수 있는 단일 터미널 명령을 통해 실행할 수 있습니다. GUI도, 테스트 코드를 다시 작성할 필요도, 호스팅할 추가 서비스도 필요 없습니다.
이것은 복사-붙여넣기 가이드입니다. 아래에서 GitHub Actions, GitLab CI, Jenkins, CircleCI 및 Azure Pipelines에 즉시 사용할 수 있는 파이프라인 파일과 녹색 빌드를 유지하는 데 필요한 몇 가지 패턴을 찾을 수 있습니다. 플랫폼에 맞는 블록을 선택하고, ID와 시크릿을 교체하면, 그날 안에 모든 병합을 제어하는 API 테스트를 갖게 됩니다. 자세한 플래그 참조를 원한다면, CI/CD에서 API 테스트를 자동화하는 방법에 대한 더 넓은 주제가 전략을 다루고 있으며, 이 페이지는 작동하는 파이프라인을 붙여넣는 것에 관한 것입니다.
무엇을 연결하는가
Apidog CLI는 npm 패키지인 apidog-cli입니다. 이는 Apidog 앱에서 작성한 테스트 시나리오(체인 요청, 단언, 한 응답에서 다음 응답으로 가져온 값, 데이터 기반 반복)를 실행합니다. CLI는 자체적인 테스트 형식을 만들지 않습니다. 프로젝트에 접근하여 ID로 시나리오를 찾고, 앱과 동일한 방식으로 실행하며, 종료 코드를 반환합니다.
이 종료 코드가 핵심입니다. 모든 단언이 통과하면 실행은 0으로 종료됩니다. 무언가 실패하면 0이 아닌 값으로 종료됩니다. CI 시스템은 이 종료 코드를 읽어 단계를 실패로 표시하고, 병합 또는 배포를 차단합니다. 게이트를 따로 구성할 필요가 없습니다. 게이트는 종료 코드 자체입니다. 파이프라인에 apidog run 단계가 있는 한, 깨진 단언은 진행을 멈춥니다.
세 가지 요소가 실행을 작동시키며, 아래의 모든 블록에서 이 요소들을 볼 수 있습니다.
- 실행이 시나리오를 실행할 권한이 있음을 증명하는 액세스 토큰입니다. 비밀번호처럼 취급하세요. CI 시크릿으로 저장하고, 커밋된 파일에는 절대 넣지 마세요.
- 무엇을 실행할지 지정하는 시나리오 ID (또는 폴더 ID, 또는 테스트 스위트 ID)입니다.
- 어디에서 실행할지 지정하는 환경 ID입니다: 개발, 스테이징 또는 프로덕션.
이러한 ID를 수동으로 입력할 필요는 없습니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 전환한 다음, 명령줄 옵션을 선택하고 액세스 토큰을 생성하세요. Apidog는 시나리오 ID와 환경 ID가 이미 채워진 완전한 apidog run 명령을 제공합니다. 한 번 복사한 다음, 토큰을 시크릿으로 옮기세요. 아직 시나리오를 구축하지 않았다면, Apidog로 테스트 시나리오 작성 방법부터 시작하여 하나라도 통과하는 시나리오를 만들고 돌아오세요.
모든 것이 구축되는 단일 명령
다음은 표준 실행 명령입니다. 모든 파이프라인 파일은 이 한 줄을 감싸는 형태로 구성됩니다.
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir ./apidog-reports
각 부분이 하는 일:
--access-token은 실행을 인증합니다. 시크릿에서 채워 넣는$APIDOG_ACCESS_TOKEN환경 변수에서 값을 읽어옵니다.-t 605067은 해당 ID의 테스트 시나리오를 실행합니다. 전체 폴더를 실행하려면-t를-f <folderId>로 바꾸거나, 선별된 스위트를 실행하려면--test-suite <id>를 사용하세요.-e 1629989는 환경을 지정합니다. 이는 동일한 시나리오가 PR 검사에서는 스테이징 환경을, 배포 후 스모크 테스트에서는 프로덕션 환경을 대상으로 하는 방식입니다.-n 1은 시나리오를 한 번 실행합니다. 반복하려면 숫자를 늘리거나, CSV 또는 JSON 데이터 파일에서 반복을 구동하려면-d <file>과 함께 사용하세요.-r html,junit는 보고서 형식을 선택합니다.junit는 CI 대시보드가 통과/실패 트리로 구문 분석하는 XML을 내보냅니다.html은 빌드 아티팩트로 저장할 수 있는 탐색 가능한 보고서입니다. 로그에서도 읽기 쉬운 출력을 원하면cli를 추가하세요.--out-dir ./apidog-reports는 보고서가 저장될 위치입니다.
보고서는 "빌드가 실패했다"와 "실패한 단언과 문제를 일으킨 응답은 다음과 같다"의 차이입니다. JUnit XML은 거의 모든 플랫폼이 기본적으로 이해하는 형식이므로, 아래의 다섯 가지 블록 모두에 나타납니다.
GitHub Actions
이 내용을 .github/workflows/api-tests.yml에 넣으세요. main 브랜치에 대한 모든 풀 리퀘스트에서 시나리오를 실행하고, 보고서를 아티팩트로 업로드하며, 단언이 실패하면 검사를 실패 처리합니다.
name: API tests
on:
pull_request:
branches: [main]
jobs:
api-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- 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 \
-n 1 \
-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
중요한 두 가지 세부 사항이 있습니다. 토큰은 APIDOG_ACCESS_TOKEN으로 Settings → Secrets and variables → Actions에 저장되며, env:를 통해 단계에 도달합니다. 그리고 업로드 단계의 if: always()는 테스트가 실패하더라도 보고서를 받을 수 있음을 의미하며, 이는 실제로 보고서를 읽어야 하는 유일한 경우입니다. 시나리오가 실패하면 apidog run 단계는 0이 아닌 값으로 종료되고, 작업은 실패로 표시되며, PR에는 실패한 검사가 나타납니다. 이 플랫폼에 대한 자세한 내용은 GitHub Actions에서 API 테스트를 자동화하는 방법을 참조하세요.
GitLab CI
.gitlab-ci.yml에서도 동일한 개념입니다. node:20 이미지는 이미 런타임을 포함하고 있으므로, 유일한 설정은 설치뿐입니다.
stages:
- test
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- >
apidog run
--access-token "$APIDOG_ACCESS_TOKEN"
-t 605067
-e 1629989
-r junit,cli
--out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
APIDOG_ACCESS_TOKEN을 Settings → CI/CD → Variables 아래에 마스킹되고 보호된 변수로 저장하여 로그에 절대 출력되지 않도록 하세요. reports: junit: 블록은 GitLab 사용자들이 놓치기 쉬운 부분입니다. 이는 GitLab에게 XML을 구문 분석하고 병합 요청 위젯에 결과를 바로 렌더링하도록 지시합니다. 검토자는 아무것도 다운로드하지 않고 어떤 단언이 실패했는지 확인할 수 있습니다.
Jenkins
선언형 파이프라인의 경우, 토큰을 Jenkins 자격 증명으로 저장하고 환경으로 가져온 다음, 스테이지에서 CLI를 호출합니다. post 블록은 JUnit XML을 Jenkins의 테스트 추세 그래프로 공급하고, HTML 보고서를 빌드에 유지합니다.
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'npm install -g apidog-cli'
sh '''
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t 605067 \
-e 1629989 \
-n 1 \
-r html,junit \
--out-dir apidog-reports
'''
}
}
}
post {
always {
junit 'apidog-reports/*.xml'
archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
}
}
}
빌드 에이전트에 이미 CLI가 캐시되어 있다면, npm install 라인을 제거하고 apidog run을 직접 호출하세요. 쉘 단계 대신 플러그인 방식을 원한다면 Apidog는 Jenkins 전용 통합 가이드도 제공합니다: CI/CD를 위해 Apidog 자동화 테스트를 Jenkins와 통합하기.
CircleCI
.circleci/config.yml에서 Node 편의 이미지를 사용하고, 토큰을 Project Settings → Environment Variables 아래의 프로젝트 환경 변수로 저장하세요.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run API test scenario
command: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli \
--out-dir ./apidog-reports
- store_test_results:
path: ./apidog-reports
- store_artifacts:
path: ./apidog-reports
destination: apidog-reports
workflows:
test:
jobs:
- api-tests
store_test_results는 GitLab의 JUnit 블록과 동일한 CircleCI 기능입니다. 이를 보고서 디렉터리를 가리키게 하면 CircleCI는 테스트 탭에 실패한 단언을 표시합니다. store_artifacts는 HTML 보고서를 첨부하여 빌드 페이지에서 열 수 있도록 합니다.
Azure Pipelines
azure-pipelines.yml에서 태스크를 사용하여 Node를 설치하고, CLI를 실행하며, JUnit 결과를 게시하세요. APIDOG_ACCESS_TOKEN을 파이프라인의 비밀 변수(또는 Azure Key Vault 변수 그룹에서 가져오기)로 추가한 다음, 스크립트 단계의 env에 매핑하세요.
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- task: NodeTool@0
inputs:
versionSpec: '20.x'
displayName: 'Install Node.js'
- script: npm install -g apidog-cli
displayName: 'Install Apidog CLI'
- script: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,html \
--out-dir ./apidog-reports
displayName: 'Run API test scenario'
env:
APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: 'JUnit'
testResultsFiles: 'apidog-reports/*.xml'
testRunTitle: 'Apidog API tests'
$(APIDOG_ACCESS_TOKEN) 매크로는 비밀 파이프라인 변수를 읽습니다. env를 통해 매핑하면 가시적인 명령줄에서 제외됩니다. condition: always()가 있는 PublishTestResults@2는 실행 성공 여부와 관계없이 테스트 탭에 결과를 표시합니다. 이 플랫폼에 대한 더 자세한 내용은 Apidog의 Azure DevOps 파이프라인 API 테스트 전용 가이드를 참조하세요.
게이트를 정직하게 유지하는 패턴
테스트를 실행하는 파이프라인은 기본입니다. 다음의 방법들은 매일매일 유용하게 활용되도록 만듭니다.
배포 직후 스모크 테스트. 릴리스가 배포되는 즉시 프로덕션 환경을 대상으로 하나의 빠른 시나리오를 실행하고, 첫 번째 실패에서 중단합니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end
야간 전체 회귀 테스트. 예약된 시간에 전체 폴더의 시나리오를 실행하고, 첫 번째 실패에서 중단하지 않고 모든 실패를 하나의 보고서로 모읍니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports
--on-error가 여기서 핵심 옵션입니다. end는 배포 게이트에 필요한 빠른 실패를 유도합니다. continue는 모든 단계를 실행하여 야간 보고서에서 모든 실패를 한 번에 보여줍니다. 어떤 방식이든, 실패가 발생하면 실행은 여전히 0이 아닌 값으로 종료되므로 게이트는 유지됩니다.
많은 입력에 대해 하나의 시나리오 실행. 데이터 파일에서 반복을 구동하고 각 행을 개별 통과로 처리합니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit
main이 아닌 피처 브랜치 테스트. 브랜치에 존재하는 시나리오를 그대로 실행합니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
CI에서만 발생하는 실패 디버그. 시나리오가 로컬에서는 통과하지만 파이프라인에서 실패할 경우, --verbose를 추가하세요. 이는 러너가 보낸 정확한 요청과 받은 정확한 응답을 출력하며, 이는 거의 항상 차이를 유발하는 환경적 요인을 찾는 방법이 됩니다.
빌드가 거짓말을 할 때
몇 가지 실패 모드는 게이트를 조용히 무력화시키기 때문에 충분히 자주 발생하여 언급할 가치가 있습니다.
테스트가 실패해야 할 때 빌드가 계속 녹색인 경우. 이것은 위험한 경우입니다. 이는 거의 항상 종료 코드가 무시되고 있음을 의미합니다. 명령을 쉘 파이프라인으로 래핑했거나, "빌드를 깨는 것을 막기 위해" || true를 추가했다면, 아무것도 감지하지 못하게 한 것입니다. 0이 아닌 종료를 숨기는 모든 것을 제거하세요. apidog run 단계는 CI 단계가 읽어야 하는 것이어야 합니다.
인증 오류. 토큰이 잘못되었거나, 만료되었거나, 명령에 도달하지 못했습니다. CI 시크릿이 실제로 채워져 있는지 확인하고 (값 대신 길이만 마스킹된 에코로 확인), 필요한 경우 시나리오의 CI/CD 탭에서 재생성하세요.
“시나리오를 찾을 수 없습니다.” 시나리오 ID, 프로젝트 ID 또는 브랜치가 일치하지 않습니다. CI/CD 탭에서 명령을 다시 복사하여 ID가 최신 상태인지 확인하고, --branch가 의도한 곳을 가리키는지 다시 확인하세요.
로컬에서는 통과하지만 CI에서는 실패하는 경우. 거의 항상 환경 차이 때문입니다. 러너가 다른 -e 환경을 대상으로 하거나, 호스트에 접근할 수 없는 방화벽 뒤에 있거나, 시나리오에 필요한 변수가 없을 수 있습니다. --verbose를 사용하여 실행하고, 러너가 생성한 요청과 로컬에서 보낸 요청을 비교하세요.
내부 호스트에 대한 TLS 실패. 엔드포인트가 내부 CA를 사용하는 경우, 검증을 비활성화하는 대신 추가 CA 인증서를 전달하세요. -k (SSL 검증 건너뛰기)는 자체 서명된 인증서를 사용하는 신뢰할 수 있는 내부 호스트에서 최후의 수단으로만 사용하고, 공개적인 대상에 대해서는 절대 사용하지 마세요.
왜 시각적으로 구축하고 헤드리스로 실행하는가
이 모든 것 밑바닥에는 진정한 설계상의 선택이 있으며, 한 단락을 할애할 가치가 있습니다. 스크립트 우선 러너를 사용하면 테스트와 실행이 동일한 파일이므로, 깨지기 쉬운 스크립트는 테스트이자 병목 현상이 됩니다. Apidog를 사용하면 프로젝트의 시나리오가 테스트이고, CLI는 사람이 있을 수 없는 곳에서 이를 실행합니다. 아무도 동일한 검사에 대한 두 가지 표현을 유지 관리하지 않습니다. 시각적 빌더에서 빠르게 작성하고, 파이프라인에서 자동으로 실행하며, 둘은 동일한 아티팩트이기 때문에 동기화 상태를 유지합니다. 이것이 CI가 도입되면 팀들이 Apidog를 API 테스트를 위한 Postman 대안으로 취급하는 큰 이유이며, 견고한 API 단언이 이를 감싸는 러너보다 더 중요한 이유입니다.
일단 실행되면 루프는 간단합니다. 앱에서 요청을 설계하고 디버그합니다. 이를 단언과 함께 시나리오로 연결합니다. 코드를 푸시하면 CLI가 모든 변경 사항에 대해 CI에서 해당 시나리오를 실행합니다. 무언가 깨지면 보고서가 단언을 명시하고, 종료 코드는 배포를 중단합니다. 수정하고 다시 푸시하면 동일한 게이트가 수정 사항을 확인합니다.
만약 테스트가 여전히 누군가의 에디터 안에 머물러 있다면, 이번 주에 그 간극을 메워야 합니다. Apidog를 다운로드하고, 하나의 시나리오를 통과시킨 다음, CI/CD 탭에서 apidog run 명령을 복사하여 해당 플랫폼에 맞는 위의 블록에 붙여넣으세요. 같은 날 오후에 모든 병합을 제어하는 API 테스트를 갖게 될 것입니다.
자주 묻는 질문
CI에서 Apidog CLI는 무료로 사용할 수 있나요? CLI는 무료 npm 패키지입니다: npm install -g apidog-cli. Apidog 프로젝트의 시나리오를 실행하므로, 실행할 수 있는 내용은 Apidog 플랜에 따라 다르지만, 명령줄 러너 자체는 별도의 유료 제품이 아닙니다.
테스트를 코드로 다시 작성해야 하나요? 아닙니다. Apidog에서 시각적으로 시나리오를 구축하면 CLI가 ID로 실행합니다. 시나리오가 테스트이고, CLI는 단지 실행기일 뿐입니다. 이것이 스크립트 우선 러너와 구분되는 주요 특징입니다.
실패하는 테스트가 실제로 빌드를 어떻게 실패시키나요? 종료 코드를 통해 실패합니다. 단언이 실패하면 apidog run은 0이 아닌 값으로 종료됩니다. CI 시스템은 이를 읽어 단계를 실패로 표시하고, 병합 또는 배포를 차단합니다. 게이트가 작동하도록 추가적인 설정을 할 필요가 없습니다.
어떤 보고서 형식을 사용해야 하나요? CI 대시보드가 통과/실패 결과로 구문 분석하는 기계가 읽을 수 있는 XML을 위해 junit를 사용하고, 빌드 아티팩트로 저장될 탐색 가능한 보고서를 원하면 html을 추가하세요. 일반적인 조합은 -r junit,html입니다. 빌드 로그에서 읽기 쉬운 출력을 원하면 cli도 계속 사용하세요.
CI 서버에 Apidog를 설치해야 하나요? 아닙니다. CI 러너는 Node.js (v16 이상)와 apidog-cli 패키지만 있으면 됩니다. 데스크톱 앱, GUI, 라이선스 파일은 필요 없습니다. 패키지와 액세스 토큰만으로 충분합니다.
글로벌 설치 없이 실행할 수 있나요? 예. npx apidog-cli run ...을 사용하여 영구적인 글로벌 설치 없이 실행할 수 있으며, 이는 각 작업 후에 해체되는 임시 러너에서 더 깔끔합니다.
이것은 Newman과 어떻게 다른가요? Newman은 명령줄에서 Postman 컬렉션을 실행합니다. Apidog CLI는 Apidog 테스트 시나리오를 실행합니다. 역할은 유사하지만, Apidog 러너는 앱에서 작성한 시나리오를 실행하며 단일 apidog-cli 패키지로 제공됩니다. 해당 비교의 Postman 측면에 대해서는 Postman CLI 대 Newman을 참조하세요.
액세스 토큰과 ID는 어디에서 얻을 수 있나요? Apidog의 테스트 시나리오 CI/CD 탭에서 모두 얻을 수 있습니다. 명령줄 옵션을 선택하고, 액세스 토큰을 생성한 다음, Apidog가 시나리오 및 환경 ID를 이미 채워 넣은 완전한 apidog run 명령을 복사하세요. 그런 다음 토큰을 CI 시크릿으로 옮기고 $APIDOG_ACCESS_TOKEN으로 참조하세요.