Apidog CLI에서 API 테스트 실행 방법

API 테스트가 노트북에서는 통과합니다. 그러다가 누군가 새벽 2시에 변경 사항을 병합하고, 스테이징 엔드포인트는 잘못된 형식의 페이로드를 반환하기 시작하며, 다음 날 아침 고객이 티켓을 접수할 때까지 아무도 알아차리지 못합니다. 테스트는 존재했습니다. 단지 중요한 곳에서는 실행되지 않았을 뿐입니다. 파이프라인 내부에서, 모든 푸시마다, 사람이 버튼을 클릭하지 않고도 말이죠.

"존재하는 테스트"와 "자동으로 실행되는 테스트" 사이의 간극을 정확히 메워주는 것이 바로 명령줄 러너입니다. Apidog CLI는 Apidog 데스크톱 또는 웹 앱에서 이미 구축한 테스트 시나리오를 터미널에서 헤드리스 방식으로 실행합니다. GUI도, 수동 클릭도 필요 없습니다. 단 하나의 npm 명령으로 설치하고, 테스트 시나리오를 지정하면, 깔끔한 상태 코드와 어떤 CI 시스템에도 게시할 수 있는 보고서와 함께 종료됩니다. 이는 시각적 테스트 빌더와 CI/CD 플랫폼 사이의 다리 역할을 합니다.

요약 (TL;DR)

• Apidog CLI는 apidog-cli라는 npm 패키지입니다. npm install -g apidog-cli 명령으로 전역 설치한 다음, apidog run 명령으로 시나리오를 실행하세요.
• Apidog에서 설계한 테스트 시나리오를 실행합니다. 테스트를 코드로 다시 작성할 필요가 없으며, CLI는 액세스 토큰을 사용하여 동일한 시나리오를 ID로 실행합니다.
• 핵심 실행: apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• 리포터는 cli, html, json, junit 형식을 지원합니다. JUnit XML은 CI 테스트 대시보드에 바로 연결됩니다.
• 테스트 실패 시 0이 아닌 종료 코드를 반환하는 것이 CLI를 진정한 품질 게이트로 만듭니다. 기본적으로 실패한 테스트는 빌드를 실패시킵니다.
• Node.js가 있는 모든 CI 러너에서 작동합니다: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines 등.

Apidog CLI는 정확히 무엇인가요?

Apidog는 올인원 API 플랫폼입니다. 하나의 워크스페이스에서 스키마를 설계하고, 요청을 디버깅하고, 자동화된 테스트 시나리오를 구축하고, 엔드포인트를 모의하고, 문서를 게시할 수 있습니다. 대부분의 작업은 시각적 인터페이스에서 이루어집니다. 요청을 테스트 시나리오로 연결하고, 어설션을 추가하고, 한 응답에서 다음 응답으로 값을 가져오고, 데이터 파일을 반복할 수 있습니다.

CLI는 이러한 시나리오를 위한 헤드리스 실행기입니다. 자체 테스트 형식을 가지고 있지 않습니다. Apidog 프로젝트에 접속하여 ID로 지정한 시나리오를 앱이 실행하는 방식과 똑같이 실행한 다음 결과를 보고합니다. 빌드 도구와 소스 코드의 관계를 생각해보세요. 진실의 원천은 프로젝트에 있으며, CLI는 사람이 없어도 이를 실행하는 도구입니다.

이것이 중요한 이유는 API 테스트가 부패하는 가장 흔한 이유를 제거하기 때문입니다. 테스트가 데스크톱 앱에서 클릭 가능한 단계로만 존재하면, 누군가 기억할 때만 실행됩니다. 한 줄짜리 명령으로 실행되면, 파이프라인에 연결하여 모든 커밋, 모든 병합, 모든 야간 스케줄에 실행할 수 있습니다. 시각적 빌더는 빠른 작성을 제공하고, CLI는 자동화를 제공합니다. 둘 중 하나를 선택할 필요 없이 둘 다 얻을 수 있습니다.

Postman 세계에서 오셨다면, 이 정신적 모델이 깔끔하게 맞아떨어질 것입니다. Apidog CLI는 Postman CLI 또는 Newman이 Postman 컬렉션에 대해 수행하는 역할을 수행하지만, Apidog 테스트 시나리오를 실행하고 단일 패키지로 제공됩니다. 우리는 Postman CLI vs Newman에서 이 비교를 심층적으로 다루었으며, 마이그레이션하는 경우 Newman 없이 CI에서 컬렉션 실행에 대한 더 넓은 질문도 다루었습니다.

사전 준비 사항

단 하나의 명령을 실행하기 전에 세 가지가 필요합니다:

1. Node.js v16 이상. CLI는 npm 패키지로 제공되므로, Node 런타임이 유일한 시스템 종속성입니다. node -v로 버전을 확인하세요. Node 16+가 설치된 모든 CI 이미지는 이미 자격이 됩니다.
2. Apidog 테스트 시나리오. CLI는 개별 요청이 아닌 시나리오를 실행합니다. Apidog 앱에서 먼저 시나리오를 구축하세요: 요청을 연결하고, 어설션을 추가하고, 필요한 모든 데이터 기반 반복을 설정하세요. 어설션 작성에 익숙하지 않다면, API 어설션: 실용 가이드에서 응답 유효성 검사 방법을 설명합니다.
3. 액세스 토큰. 이는 CLI가 Apidog 계정에 인증하여 시나리오를 가져오고 실행할 수 있도록 합니다. 테스트 시나리오의 CI/CD 탭 내에서 생성합니다. 자세한 내용은 아래에 있습니다.

이것이 전부입니다. CI 박스에 별도의 Apidog를 설치할 필요도 없고, GUI도, 라이선스 파일도 필요 없습니다. 패키지와 토큰만 있으면 충분합니다.

Apidog CLI 설치

npm으로 전역 설치하세요:

npm install -g apidog-cli

그 다음 모든 것이 올바르게 해결되었는지 확인하세요:

node -v && apidog -v && which node && which npm && which apidog

버전 번호와 경로가 출력되면 완료된 것입니다. 실행 파일은 apidog이므로 모든 명령은 apidog run으로 시작합니다.

개발자 머신에서는 전역 설치가 괜찮습니다. CI에서는 두 가지 합리적인 패턴이 있습니다. 첫 번째는 각 파이프라인 실행 시 새로 설치하는 것으로, 최신 버전을 보장합니다:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

두 번째는 npx를 통해 영구적인 전역 설치 없이 실행하는 것으로, 러너의 전역 패키지를 변경하지 않습니다:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

둘 다 작동합니다. npx 방식은 일시적인 CI 러너에 더 깔끔하며, 전역 설치는 실행 사이에 캐시할 때 약간 더 빠릅니다.

액세스 토큰 및 시나리오 ID 가져오기

CLI는 두 가지를 알아야 합니다: 어떤 시나리오를 실행할지, 그리고 실행이 허용되는지 여부입니다. Apidog는 UI에서 직접 찾을 필요 없이 이 두 가지를 모두 생성해줍니다.

자동화하려는 테스트 시나리오를 엽니다. CI/CD 탭으로 전환합니다. 명령줄 옵션을 선택한 다음, '액세스 토큰 추가' 및 '토큰 생성'을 클릭합니다. Apidog는 액세스 토큰, 시나리오 ID, 환경 ID가 이미 채워진 완전한 apidog run 명령을 생성합니다. 명령을 클릭하여 복사합니다.

생성된 명령은 정식 시작점입니다. 다음과 같습니다:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

이 숫자들은 프로젝트의 실제 ID입니다. 605067은 테스트 시나리오 ID이고, 1629989는 환경 ID입니다. 이들을 수동으로 입력하는 경우는 거의 없을 것입니다. CI/CD 탭에서 한 번 복사한 다음 토큰을 매개변수화합니다.

미리 언급할 가치가 있는 한 가지 규칙: 액세스 토큰을 비밀번호처럼 다루십시오. 커밋된 설정 파일이나 공개 파이프라인 정의에 붙여넣지 마십시오. CI 시스템에 비밀로 저장하고 환경 변수로 참조하십시오. 아래의 모든 예시는 정확히 이러한 이유로 $APIDOG_ACCESS_TOKEN을 사용합니다.

apidog run 명령, 플래그별 설명

전체 CLI는 하나의 명령을 중심으로 작동합니다. 다음은 각 그룹이 제어하는 ​​항목별로 그룹화된 완전한 옵션 표면입니다.

실행할 항목 선택

범위에 따라 -t, -f, 또는 --test-suite 중 하나를 선택합니다. 집중적인 스모크 테스트를 위한 단일 시나리오, 기능 영역을 위한 폴더, 그리고 큐레이트된 시나리오 세트를 하나의 논리적 작업으로 함께 실행하고 싶을 때 테스트 스위트를 사용합니다.

인증

이것은 모든 CI 명령에 필요한 유일한 플래그입니다. 비밀 저장소에서 전달하고, 절대 인라인으로 사용하지 마세요.

환경 및 반복

환경 플래그는 시나리오를 복제하지 않고도, 풀 리퀘스트 확인 시 스테이징 환경을, 배포 후 스모크 테스트 시 프로덕션 환경을 동일한 시나리오로 지정하는 방법입니다. 반복 데이터는 하나의 시나리오를 50개의 입력 행에 대해 실행하고 각 행을 별도의 통과로 처리하는 방법입니다. 테스트 스위트를 사용한 자동화된 API 테스트 확장 가이드에서 데이터 기반 패턴에 대해 더 자세히 설명합니다.

보고서

이것이 CLI가 파이프라인에서 제 역할을 하는 부분입니다. 여러 형식을 쉼표로 구분하여 한 번에 전달할 수 있습니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./test-reports

cli는 빌드 로그를 읽는 사람들을 위한 읽기 쉬운 터미널 출력을 제공합니다. html은 빌드 아티팩트로 보관하고 브라우저에서 열 수 있는 자체 포함형 보고서를 생성합니다. junit은 거의 모든 CI 대시보드가 통과/실패 트리로 파싱하는 방법을 아는 표준 JUnit 형식의 XML을 출력합니다. json은 후처리하고 싶을 때 원시 구조화된 결과를 제공합니다.

오류 처리 및 종료 동작

--on-error는 시나리오 중간에 발생하는 상황을 제어합니다. end는 첫 번째 실패 시 실행을 중지하는데, 이는 빠르게 실패하는 스모크 테스트에서 일반적으로 원하는 동작입니다. continue는 모든 단계를 실행하여 하나의 보고서에서 모든 실패를 확인할 수 있도록 합니다. ignore는 단계가 불안정하여 실행을 방해하고 싶지 않은 드문 경우에 사용됩니다.

TLS 및 인증서

상호 TLS 또는 내부 CA 체인 뒤의 엔드포인트를 테스트할 때 이 옵션들을 사용하세요. -k는 인증서가 자체 서명된 신뢰할 수 있는 내부 호스트에만 사용해야 하며, 공개적인 대상에는 절대 사용하지 마세요.

출력 및 진단

--verbose는 테스트가 로컬에서는 통과하지만 CI에서 실패할 때 가장 먼저 시도해야 할 옵션입니다. 이는 러너가 보낸 정확한 요청과 받은 정확한 응답을 보여줍니다. --silent는 종료 코드와 저장된 보고서만 중요한 시끄러운 야간 작업에 사용됩니다.

종료 코드: CI를 작동시키는 핵심

테스트 러너는 파이프라인에 테스트 통과 여부를 알려줄 때만 유용합니다. Apidog CLI는 모든 잘 동작하는 명령줄 도구가 하는 방식과 동일하게 작동합니다. 모든 어설션이 통과하면 코드 0으로 종료하고, 무언가 실패하면 0이 아닌 코드로 종료합니다.

이 단일 동작이 apidog run을 품질 게이트로 만듭니다. CI 시스템은 각 단계의 종료 코드를 읽습니다. 0이 아닌 종료는 해당 단계를 실패로 표시하고, 이는 작업을 실패시키며, 병합 또는 배포를 차단합니다. 추가로 아무것도 구성할 필요가 없습니다. apidog run 단계가 파이프라인에 있는 한, 실패하는 테스트는 라인을 중단시킵니다.

이것은 --on-error로 제어할 수 있습니다. 기본 동작은 첫 번째 깨진 어설션에서 실패하여 빠른 피드백을 유지합니다. 빌드가 실패하기 전에 하나의 보고서에서 모든 실패를 확인하고 싶다면 --on-error continue로 전환하세요. 어느 쪽이든, 무언가 실패하면 실행은 여전히 0이 아닌 종료로 끝나므로 게이트는 유지됩니다.

GitHub Actions에서 실행

모든 풀 리퀘스트에서 Apidog 시나리오를 실행하고 보고서를 아티팩트로 게시하는 완전한 워크플로우입니다.

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

토큰은 리포지토리 비밀에 저장되며 환경 변수로 단계에 전달됩니다. 업로드 단계의 if: always()는 테스트가 실패하더라도 보고서를 받을 수 있음을 의미하며, 이는 정확히 보고서를 읽고 싶을 때입니다. 테스트가 실패하면 apidog run 단계는 0이 아닌 코드로 종료되고, 작업은 빨간색으로 표시되며, PR에는 실패한 검사가 표시됩니다.

GitLab CI에서 실행

.gitlab-ci.yml에서도 동일한 패턴입니다:

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은 파일에 저장하지 않고, 설정에서 마스킹된 보호된 CI/CD 변수로 저장해야 합니다. 그리고 reports: junit: 블록은 GitLab이 JUnit XML을 파싱하여 병합 요청 위젯에 결과를 렌더링하도록 지시하므로, 검토자는 아무것도 다운로드하지 않고도 어떤 어설션이 실패했는지 확인할 수 있습니다.

Jenkins에서 실행

선언형 파이프라인에서 토큰을 Jenkins 자격 증명 또는 전역 환경 변수로 저장한 다음, 단계에서 CLI를 호출합니다:

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을 직접 호출하세요. post 블록의 junit 단계는 XML을 Jenkins의 테스트 추세 그래프로 전달하고, archiveArtifacts는 HTML 보고서를 빌드에 첨부합니다. Jenkins와 다른 러너를 비교하고 있다면, ReadyAPI Jenkins CI 설정 및 더 간단한 대안에서 장단점을 다룹니다.

일반적인 패턴 및 레시피

배포 후 스모크 테스트. 릴리스 직후 프로덕션 환경을 대상으로 하나의 빠른 시나리오를 실행합니다:

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

데이터 기반 실행. 테스트 케이스 CSV 파일에 대해 하나의 시나리오를 반복 실행합니다:

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를 추가하여 러너가 생성한 정확한 와이어 레벨 요청 및 응답을 확인하세요.

문제 해결

인증 오류. 실행이 인증 오류로 실패하면 토큰이 잘못되었거나, 만료되었거나, 명령에 도달하지 않은 것입니다. 마스킹된 확인(전체 토큰은 절대 안 됨)을 에코하여 CI 비밀이 실제로 채워져 있는지 확인하세요. 필요한 경우 시나리오의 CI/CD 탭에서 토큰을 다시 생성하세요.

"시나리오를 찾을 수 없습니다." 시나리오 ID, 프로젝트 ID 또는 브랜치가 일치하지 않습니다. ID가 최신 상태임을 보장하기 위해 CI/CD 탭에서 명령을 다시 복사하고, --branch가 예상한 곳을 가리키는지 확인하세요.

테스트는 로컬에서는 통과하지만 CI에서는 실패합니다. 거의 항상 환경 차이 때문입니다. CI 러너가 다른 -e 환경을 대상으로 하거나, 도달할 수 없는 호스트에 연결하거나, 시나리오가 의존하는 변수가 없을 수 있습니다. --verbose로 실행하여 CI 러너가 보낸 요청과 로컬에서 보낸 요청을 비교하세요.

내부 호스트에 대한 네트워크 또는 TLS 실패. 엔드포인트가 내부 CA를 사용하는 경우 --ssl-extra-ca-certs를 전달하세요. -k는 인증서가 자체 서명된 신뢰할 수 있는 내부 호스트에서 최후의 수단으로만 사용하세요.

테스트가 실패해야 하는데도 빌드가 계속 성공합니다. apidog run 단계의 종료 코드가 실제로 CI에 도달하고 있는지 확인하세요. 쉘 파이프라인으로 감싸거나 || true를 추가했다면, 0이 아닌 종료 코드가 무시되어 게이트가 작동하지 않습니다. 종료 코드를 가리는 모든 것을 제거하세요.

Apidog CLI가 실제 워크플로우에 어떻게 적용되는가

CLI는 루프의 한 부분입니다. Apidog 앱에서 요청을 설계하고 디버깅합니다. 어설션과 함께 시나리오로 연결합니다. 작업을 커밋하면 CLI는 모든 변경 사항에 대해 CI에서 해당 시나리오를 실행합니다. 문제가 발생하면 보고서에서 어떤 어설션이 실패했는지 알려주고 종료 코드가 배포를 중지합니다. 수정하고 다시 푸시하면 동일한 게이트가 수정 사항을 확인합니다.

테스트를 시각적으로 구축하고 헤드리스로 실행하는 장점은 아무도 동일한 테스트의 두 가지 표현을 유지 관리할 필요가 없다는 것입니다. 프로젝트의 시나리오가 테스트입니다. CLI는 사람이 있을 수 없는 곳에서 이를 실행할 뿐입니다. 이는 테스트와 실행이 동일한 취약한 파일인 스크립트 우선 러너와는 다른 모델이며, 팀이 API 테스트를 위한 Postman 대안으로 Apidog로 전환하는 큰 이유 중 하나입니다.

아직 테스트를 구축하지 않았다면, 앱에서 시작하여 하나의 시나리오를 통과시킨 다음, CI/CD 탭에서 CLI 명령을 연결하십시오. Apidog 다운로드를 통해 첫 번째 자동화된 시나리오를 설정하면, 당일 오후에 파이프라인을 제어할 수 있을 것입니다.

자주 묻는 질문

Apidog CLI는 무료인가요? CLI 자체는 무료 npm 패키지입니다. npm install -g apidog-cli로 설치합니다. 이는 Apidog 프로젝트의 테스트 시나리오를 실행하므로, 실행할 수 있는 내용은 Apidog 요금제에 따라 다르지만, 명령줄 러너는 별도의 유료 제품이 아닙니다.

CLI를 사용하려면 테스트를 코드로 다시 작성해야 하나요? 아닙니다. 이것이 스크립트 우선 러너와의 주요 차이점입니다. Apidog에서 시각적으로 시나리오를 구축하고, CLI는 ID로 시나리오를 실행합니다. 시나리오가 테스트이고, CLI는 단지 실행기입니다.

Apidog CLI와 Newman의 차이점은 무엇인가요? Newman은 명령줄에서 Postman 컬렉션을 실행합니다. Apidog CLI는 Apidog 테스트 시나리오를 실행합니다. 역할은 비슷하지만, Apidog 러너는 Apidog 앱에서 작성한 시나리오를 실행하고 단일 apidog-cli 패키지로 제공됩니다. 해당 비교의 Postman 측면은 Postman CLI vs Newman을 참조하세요.

CI에서 어떤 보고서 형식을 사용해야 하나요? CI 대시보드가 통과/실패 트리로 파싱하는 기계가 읽을 수 있는 결과에는 junit를 사용하고, 빌드 아티팩트로 저장할 수 있는 탐색 가능한 보고서를 원한다면 html을 추가하세요. 일반적인 선택은 -r html,junit입니다. 빌드 로그에서 읽기 쉬운 출력을 원한다면 cli도 계속 켜두세요.

CLI는 빌드를 어떻게 실패시키나요? 종료 코드를 통해 실패시킵니다. 어떤 어설션이든 실패하면 apidog run은 0이 아닌 코드로 종료합니다. CI 시스템은 해당 종료 코드를 읽고 단계를 실패로 표시하며 병합 또는 배포를 차단합니다. 이 작업을 위해 추가로 아무것도 구성할 필요가 없습니다.

CLI를 전역으로 설치하지 않고 실행할 수 있나요? 예. npx apidog-cli run ...을 사용하여 영구적인 전역 설치 없이 실행할 수 있으며, 이는 임시 CI 러너에서 편리합니다.

어떤 Node.js 버전이 필요한가요? Node.js v16 이상입니다. Node 16+가 설치된 모든 최신 CI 이미지는 이미 요구 사항을 충족합니다.

액세스 토큰과 시나리오 ID는 어디서 얻나요?** 둘 다 Apidog의 테스트 시나리오 CI/CD 탭에서 얻을 수 있습니다. 명령줄 옵션을 선택하고, 액세스 토큰을 생성한 다음, ID가 이미 채워진 Apidog가 생성한 전체 apidog run 명령을 복사하세요. 그런 다음 토큰을 CI 비밀 저장소로 옮기십시오.