CI/CD 탭에서 명령어를 복사하여 파이프라인에 붙여넣었더니 잘 작동했습니다. 그런데 팀 동료가 테스트가 명백히 실패했는데도 빌드가 계속 초록색으로 표시되는 이유를 묻거나, 동일한 실행을 프로덕션 대신 스테이징으로 지정할 수 있는지, 또는 CI 대시보드가 실제로 구문 분석할 수 있는 보고서를 얻는 방법을 묻습니다. 갑자기 한 줄짜리 명령어로는 충분하지 않게 됩니다. 각 부분이 무엇을 하는지 알아야 합니다.
apidog run은 Apidog 명령줄 러너의 핵심이 되는 단일 명령어입니다. 이 명령어는 Apidog에서 구축한 API 테스트 시나리오를 터미널에서 GUI나 사람이 버튼을 클릭하지 않고도 헤드리스 방식으로 실행합니다. 러너가 할 수 있는 모든 것은 이 단일 명령어의 플래그를 통해 수행됩니다. 어떤 시나리오를 실행할지, 어떤 환경을 대상으로 할지, 몇 번 반복할지, 어떤 보고서를 생성할지, 그리고 무엇이 실패로 간주되는지 등을 제어합니다. 플래그 인터페이스를 한 번 익히면 맹목적으로 복사하여 붙여넣는 일을 멈출 수 있습니다.
apidog run이란 무엇인가요
Apidog CLI는 apidog-cli라는 npm 패키지로 제공됩니다. 한 번 설치하면 apidog라는 단일 바이너리를 얻게 되며, 이 바이너리의 주요 하위 명령어는 run입니다. 이 하위 명령어는 Apidog 테스트 시나리오 중 하나를 데스크톱 앱과 동일한 방식으로 실행한 다음, 종료 코드와 요청한 모든 보고서 파일을 반환합니다.
전역으로 설치하세요:
npm install -g apidog-cli
정상적으로 설치되었는지 확인하세요:
apidog -v
플래그를 이해하기 전에 apidog run이 무엇을 대상으로 작동하는지 이해해야 합니다. 자체적인 테스트 형식을 정의하지 않습니다. 테스트는 Apidog 앱에서 작성한 시나리오입니다. 즉, 연결된 요청, 어설션, 한 응답에서 다음 응답으로 가져온 값, 선택적 데이터 기반 반복 등으로 구성됩니다. CLI는 프로젝트에 접근하여 ID로 시나리오를 찾아 실행합니다. 따라서 대부분의 플래그는 러너에게 무엇을 가져오고 실행 중에 어떻게 동작해야 하는지를 알려주는 것이며, 테스트를 인라인으로 작성하는 것과는 관련이 없습니다.
최소한의 실제 명령어는 다음과 같습니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
이 명령어는 이 토큰으로 인증하고, 테스트 시나리오 605067을 환경 1629989에 대해 한 번 실행하며, HTML 보고서와 읽을 수 있는 터미널 출력을 생성하라는 의미입니다. 이 줄에 있는 모든 플래그는 아래에 설명되어 있으며, 이 명령어에 빠져 있는 플래그도 함께 설명되어 있습니다.
전체 옵션 표면 한눈에 보기
작업별로 그룹화된 전체 옵션 세트입니다. 이를 참조표로 사용하십시오. 이 표 이후의 섹션에서는 한 문장 이상 설명이 필요한 옵션들을 설명합니다.
| 그룹 | 플래그 | 인수 | 제어하는 기능 |
|---|---|---|---|
| 선택 | -t, --test-scenario |
<testScenarioId> |
ID로 단일 시나리오 실행 |
| 선택 | -f, --test-scenario-folder |
<folderId> |
폴더 내의 모든 시나리오 실행 |
| 선택 | --test-suite |
<testSuiteId> |
ID로 테스트 스위트 실행 |
| 선택 | --project |
<projectId> |
시나리오가 속한 프로젝트 |
| 선택 | --branch |
<branchName> |
브랜치에 대해 실행 (기본값: main) |
| 인증 | --access-token |
<accessToken> |
실행 인증; 온라인에서 필수 |
| 환경 | -e, --environment |
<environmentId> |
대상 환경 |
| 반복 | -n, --iteration-count |
<n> |
시나리오를 n번 실행 |
| 반복 | -d, --iteration-data |
<path> |
JSON 또는 CSV 파일에서 반복 데이터 가져오기 |
| 반복 | --variables |
<path> |
로컬 파일에서 변수 로드 |
| 반복 | --global-var |
<value> |
전역 변수를 인라인 설정 (key=value 형식) |
| 반복 | --env-var |
<value> |
환경 변수를 인라인 재정의 (key=value 형식) |
| 보고서 | -r, --reporters |
[reporters] |
보고서 형식: cli, html, json, junit |
| 보고서 | --out-dir |
<outDir> |
보고서가 작성될 위치 |
| 보고서 | --out-file |
<outFile> |
이름 자리표시자가 포함된 보고서 파일명 |
| 보고서 | --out-json-failures-separated |
<value> |
실패를 별도의 JSON 파일로 작성 |
| 보고서 | --upload-report |
[value] |
Apidog 클라우드에 보고서 개요 업로드 |
| 오류 | --on-error |
<behavior> |
실패 시 ignore, continue, end 중 선택 |
| 오류 | --ignore-redirects |
HTTP 리다이렉션을 따르지 않음 | |
| 오류 | --delay-request |
[n] |
요청 사이에 n 밀리초 대기 |
| 오류 | --timeout-request |
[n] |
요청당 시간 제한(밀리초) |
| 오류 | --timeout-script |
[n] |
스크립트 실행 시간 제한(밀리초) |
| TLS | -k, --insecure |
SSL 인증서 확인 비활성화 | |
| TLS | --ssl-client-cert |
<path> |
클라이언트 인증서 (PEM) |
| TLS | --ssl-client-key |
<path> |
클라이언트 인증서의 개인 키 |
| TLS | --ssl-client-passphrase |
<passphrase> |
클라이언트 인증서의 암호 |
| TLS | --ssl-client-cert-list |
<path> |
인증서를 호스트에 매핑하는 구성 |
| TLS | --ssl-extra-ca-certs |
<path> |
추가 신뢰할 수 있는 CA 인증서 |
| 출력 | --verbose |
전체 요청 및 응답 세부 정보 출력 | |
| 출력 | --silent |
콘솔 출력 억제 | |
| 출력 | --color |
<value> |
색상 출력 강제 활성화 또는 비활성화 |
| 출력 | --external-program-path |
<path> |
사용자 지정 로직을 위한 외부 프로그램 파일 |
| 출력 | --database-connection |
<path> |
DB를 쿼리하는 단계에 대한 데이터베이스 구성 |
| 출력 | --preferred-http-version |
<version> |
선호하는 HTTP 프로토콜 버전 |
| 출력 | -b, --bigint |
큰 숫자 값에 대해 BigInt 활성화 | |
| 출력 | --lang |
<language> |
CLI 언어 |
| 출력 | -h, --help |
도움말 출력 |
CLI 릴리스에 따라 플래그 이름과 기본값이 변경될 수 있습니다. 의심스러울 때는 러너 자체가 진실의 원천입니다. 설치된 버전에서 apidog run --help를 실행하고 이 문서를 포함한 다른 어떤 문서보다 그 결과를 신뢰하십시오.
무엇을 실행할지 선택하기
세 가지 플래그가 실행 범위를 결정하며, 명령어당 이 중 정확히 하나를 선택해야 합니다.
-t, --test-scenario <id>는 단일 시나리오를 실행합니다. 이는 일반적인 경우로, 집중적인 스모크 테스트 하나, 회귀 시나리오 하나, 또는 풀 리퀘스트에서 게이트하고 싶은 하나의 작업을 의미합니다.
-f, --test-scenario-folder <id>는 폴더 내의 모든 시나리오를 실행합니다. 기능 영역을 폴더로 구성하고 야간 회귀 스윕처럼 전체 그룹을 하나의 작업으로 실행하고 싶을 때 이 옵션을 사용하십시오.
--test-suite <id>는 하나의 논리적 단위로 함께 실행하도록 구성한 시나리오 집합인 테스트 스위트를 실행합니다. 스위트는 원하는 시나리오가 모두 한 폴더에 있지 않지만 동일한 테스트 패스에 속할 때 적절한 도구입니다.
두 개의 선택자가 러너가 찾는 위치를 구체화합니다. --project <id>는 시나리오가 위치한 프로젝트를 지정하며, 토큰이 여러 프로젝트에 접근할 수 있을 때 유용합니다. --branch <name>은 main 대신 특정 브랜치에 존재하는 시나리오를 실행하여, 피쳐 브랜치의 테스트 변경 사항을 병합 전에 검증할 수 있도록 합니다.
# 단일 시나리오
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
# 전체 폴더
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit
# 선별된 스위트
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit
실행 인증하기
--access-token <token>은 모든 온라인 실행에 필요한 유일한 플래그입니다. 이는 실행이 시나리오를 가져오고 실행할 권한이 있음을 증명합니다. Apidog의 테스트 시나리오 CI/CD 탭에서 토큰을 생성할 수 있으며, 이 탭에서 앱은 시나리오 ID와 환경 ID가 이미 채워진 완전한 apidog run 명령어를 자동으로 생성해 줍니다.
토큰을 비밀번호처럼 다루세요. 커밋된 파이프라인 파일이나 공유 스크립트에 붙여넣지 마십시오. CI 시스템에 비밀로 저장하고 환경 변수를 통해 전달하십시오. 이 때문에 여기의 모든 예제에서는 리터럴 문자열 대신 $APIDOG_ACCESS_TOKEN을 참조합니다. 토큰이 유출되면 동일한 CI/CD 탭에서 다시 생성하면 이전 토큰은 작동을 멈춥니다.
환경 지정 및 반복
환경 플래그는 하나의 시나리오가 여러 목적을 수행하도록 합니다. -e, --environment <id>는 특정 환경을 대상으로 실행을 지정하므로, 동일한 시나리오가 중복 없이 풀 리퀘스트 게이트에서 스테이징을 확인하고 배포 후 스모크 테스트에서 프로덕션을 확인할 수 있습니다. 여러 환경에서 값을 관리하는 경우, API 클라이언트를 위한 환경 및 비밀 관리 가이드에서 해당 값의 흐름을 다룹니다.
-n, --iteration-count <n>는 시나리오를 n번 연속으로 실행합니다. 빠른 안정성 확인이나 멱등성을 가져야 하는 흐름을 반복하는 데 유용합니다.
-d, --iteration-data <path>는 데이터 기반 플래그입니다. JSON 또는 CSV 파일을 지정하면 러너는 각 행을 자체 입력 값을 가진 자체 패스로 처리하여 행당 한 번씩 시나리오를 실행합니다. 이렇게 50개 계정에 대해 하나의 로그인 시나리오를 실행하거나, 페이로드 테이블에 대해 하나의 주문 생성 흐름을 실행할 수 있습니다. 더 자세한 패턴은 CSV 및 JSON을 사용한 데이터 기반 API 테스트에 있습니다.
세 가지 플래그는 시나리오를 편집하지 않고 값을 주입합니다. --variables <path>는 로컬 파일에서 변수를 로드합니다. --global-var key=value는 전역 변수를 인라인으로 설정합니다. --env-var key=value는 이 실행에 대해서만 단일 환경 변수를 재정의합니다. 이는 파이프라인마다 값(기본 URL, 기능 플래그)이 다르고 각 파이프라인에 대해 별도의 환경을 원치 않을 때 CI에서 유용합니다. Apidog의 변수가 생소하다면 Apidog에서 변수 마스터하기에서 스코프에 대해 설명합니다.
# 입력 CSV를 사용하여 시나리오 50회 실행
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit
# 이 실행에 대해서만 환경 변수 하나 재정의
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli
보고서: apidog run이 생성할 수 있는 모든 출력 형식
이 그룹은 사람들이 가장 많이 찾는 부분이므로, 각 보고서와 그 용도를 설명합니다. -r, --reporters로 선택하며, 쉼표로 구분하여 여러 개를 한 번에 전달할 수 있습니다. 기본값은 cli입니다.
cli는 터미널에 읽기 쉬운 요약을 출력합니다. 사람이 빌드 로그에서 통과/실패 수와 어떤 어설션이 실패했는지 확인하는 데 사용됩니다. 로그가 유용하도록 기계 형식과 함께 계속 사용하십시오.
html은 자체 포함된 HTML 보고서를 작성합니다. 빌드 아티팩트로 보관하고 브라우저에서 열어 요청 및 응답 세부 정보가 포함된 전체 실행 결과를 확인하십시오. 이는 파이프라인을 지켜보지 않은 사람에게 전달할 수 있는 형식입니다.
junit는 표준 JUnit 형식의 XML을 출력합니다. 거의 모든 CI 대시보드는 JUnit XML을 통과/실패 트리로 구문 분석하고, 병합 요청 위젯에 실패를 표시하며, 시간 경과에 따른 결과를 추적하는 방법을 알고 있습니다. CI를 위해 하나의 기계 형식을 선택해야 한다면, 이것을 선택하십시오.
json은 원시 구조화된 결과를 생성합니다. 결과를 직접 후처리하고 싶을 때 사용하십시오. 즉, 스크립트에 전달하거나, 어딘가에 메트릭을 푸시하거나, 사용자 지정 요약을 구축할 수 있습니다.
일반적인 CI 조합은 사람을 위한 HTML과 대시보드를 위한 JUnit입니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports
나머지 보고서 플래그는 출력이 저장될 위치와 포함될 추가 정보를 제어합니다:
--out-dir <dir>는 보고서가 작성될 디렉토리를 설정합니다. 기본값은./apidog-reports입니다.--out-file <name>은 보고서 파일명을 설정하며,{FOLDER_NAME},{SCENARIO_NAME},{GENERATE_TIME}자리표시자를 허용하므로, 매번 하나의 파일을 덮어쓰는 대신 시나리오 이름과 타임스탬프로 파일을 표시할 수 있습니다.--out-json-failures-separated <value>는 실패를 별도의 JSON 파일로 분리하여, 실패만 포함된 차이를 쉽게 읽을 수 있도록 합니다.--upload-report [value]는 보고서 개요를 Apidog 클라우드에 업로드하여 로컬 파일과 함께 프로젝트 기록에 실행 결과가 표시되도록 합니다.
실패 제어: 오류 처리 및 종료 코드
러너는 테스트가 통과했는지 파이프라인에 알려줄 때만 파이프라인에서 유용합니다. apidog run은 잘 작동하는 명령줄 도구처럼 동작합니다. 모든 어설션이 통과하면 0으로 종료하고, 무엇이든 실패하면 0이 아닌 코드로 종료합니다. 이 단일 동작이 전체 품질 게이트입니다. CI는 종료 코드를 읽고, 단계를 실패로 표시하며, 병합 또는 배포를 차단합니다. 게이트를 구성하는 것이 아니라, 종료 코드가 바로 게이트입니다.
--on-error <behavior>는 시나리오 중간에 단계가 실패할 때 발생하는 상황을 설정하며, 세 가지 값을 가집니다:
end는 첫 번째 실패한 단계에서 실행을 중지합니다. 무언가 즉시 오류가 발생했을 때 피드백을 원하는 빠른 실패 스모크 테스트에 사용하십시오.continue는 모든 나머지 단계를 실행하여 모든 실패를 하나의 보고서에 수집합니다. 모든 오류를 한 번에 확인하여 불필요한 반복을 줄이는 회귀 스윕에 사용하십시오.ignore는 알려진 불안정한 단계를 치명적이지 않은 것으로 간주하여 실행을 계속 진행합니다. 드물게 사용하십시오. 무시된 단계가 실제 회귀를 숨겨서는 안 됩니다.
어떤 경우든, 어설션이 실패하면 실행은 0이 아닌 코드로 종료되므로, 어떤 동작을 선택했는지와 관계없이 게이트는 유지됩니다. 조용히 게이트를 무너뜨리는 한 가지는 셸에서 || true를 추가하는 것처럼 종료 코드를 삼키는 방식으로 명령어를 래핑하는 것입니다. 그렇게 하지 마십시오. 0이 아닌 종료 코드가 핵심입니다.
네 가지 플래그가 실행 중 요청 동작을 조정합니다:
--ignore-redirects는 러너가 HTTP 리다이렉션을 자동으로 따르는 것을 중지하여, 리다이렉트 응답 자체에 대해 어설션할 수 있도록 합니다.--delay-request [n]은 요청 사이에n밀리초를 대기하여, 속도 제한 또는 부하에 민감한 엔드포인트에 도움이 됩니다.--timeout-request [n]은 단일 요청이 걸릴 수 있는 최대 시간을 밀리초 단위로 제한합니다.--timeout-script [n]은 사전 또는 사후 요청 스크립트가 실행될 수 있는 최대 시간을 밀리초 단위로 제한합니다.
# 스모크 테스트: 첫 번째 실패에서 중지
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end
# 회귀 테스트: 모든 것을 실행하고 모든 실패 수집
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
TLS 및 인증서
상호 TLS 또는 내부 인증 기관 뒤에 있는 엔드포인트를 테스트할 때, 이 그룹은 연결을 설정하는 방법입니다.
-k, --insecure는 SSL 인증서 확인을 완전히 비활성화합니다. 자체 서명 인증서를 가진 신뢰할 수 있는 내부 호스트에 대해서만 사용하십시오. 공용 대상에는 절대 사용하지 마십시오. 연결을 보호하는 확인 기능을 비활성화하기 때문입니다.
적절한 상호 TLS를 위해서는 클라이언트 자격 증명을 대신 제공하십시오. PEM 인증서용으로 --ssl-client-cert <path>, 해당 개인 키용으로 --ssl-client-key <path>, 키가 암호화된 경우 --ssl-client-passphrase <passphrase>를 사용합니다. 다른 호스트에 다른 인증서가 필요한 경우, --ssl-client-cert-list <path>는 이를 매핑하는 구성 파일을 가리킵니다. 그리고 --ssl-extra-ca-certs <path>는 신뢰할 수 있는 CA 인증서를 추가하는데, 이는 러너가 인식하지 못하는 내부 CA 체인을 -k를 사용하는 것보다 더 깔끔하게 해결하는 방법입니다.
출력 및 진단
마지막 그룹은 러너가 출력하는 내용과 몇 가지 실행 세부 정보를 제어합니다.
--verbose는 모든 단계에 대한 전체 요청 및 응답을 출력합니다. 시나리오가 로컬에서는 통과하지만 CI에서는 실패할 때 가장 먼저 시도할 방법입니다. 러너가 보내고 받은 정확한 바이트를 보여주므로, 수동으로 보낸 것과 비교할 수 있습니다. --silent는 그 반대로, 종료 코드와 저장된 보고서만 중요한 시끄러운 예약 작업에 대해 콘솔 출력을 억제합니다. --color <value>는 색상 출력을 강제로 켜거나 끄는데, CI 로그 뷰어가 ANSI 코드를 손상시킬 때 유용합니다.
나머지는 특정 시나리오 기능을 위한 것입니다:
--external-program-path <path>는 시나리오가 호출하는 사용자 지정 로직을 위한 외부 프로그램 파일을 가리킵니다.--database-connection <path>는 데이터베이스를 직접 쿼리하는 단계를 포함하는 시나리오를 위한 데이터베이스 구성을 제공합니다.--preferred-http-version <version>은 러너가 선호하는 HTTP 프로토콜 버전을 설정합니다.-b, --bigint는 BigInt 처리를 활성화하여 큰 숫자 값이 정밀도를 잃지 않도록 합니다.--lang <language>는 CLI의 표시 언어를 설정합니다.-h, --help는 도움말 텍스트를 출력하며, 이는 설치된 버전에 대한 권위 있는 목록입니다.
종합: 실제로 실행할 명령어
배포 직후 프로덕션에 대한 스모크 테스트, 빠른 실패:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end
폴더에 대한 전체 야간 회귀 테스트, 모든 실패를 하나의 HTML 및 JUnit 보고서에:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
CSV를 통한 데이터 기반 실행, CI를 위한 기계 판독 가능 출력:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit
병합 전 피쳐 브랜치의 테스트 변경 사항 검증:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
와이어 세부 정보를 덤프하여 CI에서만 발생하는 실패 디버깅:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose
임시 CI 러너에서 CLI를 실행하며 전역 설치를 원치 않는다면, 설치 대신 npx를 사용하세요:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
이것도 동일한 기능을 수행합니다. 전역 설치와 npx 중 선택은 러너의 청결도에 관한 것이지 기능에 관한 것이 아닙니다. CLI가 실행할 시나리오를 설정하려면 Apidog를 다운로드하고, 앱에서 하나의 시나리오를 구축한 다음, 해당 시나리오의 CI/CD 탭에서 생성된 명령어를 복사하여 토큰을 매개변수화하십시오.\