유용한 정보를 전혀 출력하지 않는 테스트 실행은 아무도 신뢰하지 않는 테스트 실행입니다. 파이프라인이 빨간색으로 바뀌고, 누군가 빌드 로그를 열었을 때, 타임스탬프의 벽과 0이 아닌 종료 코드만 발견합니다. 어떤 어설션이 깨졌나요? 어떤 환경에서? 데이터 파일의 몇 번째 행에서? 실행은 알고 있었지만, 나중에 읽을 수 있는 곳에 기록하지 않았을 뿐입니다.
리포터가 채워주는 부분이 바로 이 간극입니다. 명령줄에서 API 테스트를 실행할 때, 리포트는 실제로 함께하는 부분입니다. 즉, 아카이브하는 아티팩트이자 CI 대시보드가 파싱하는 파일이며, 새벽 2시에 파이프라인을 지켜보지 않았던 팀원에게 오전 9시에 건네주는 것입니다. 테스트 결과는 작업의 절반에 불과합니다. 나머지 절반은 그 결과를 사람과 기계가 동시에 읽을 수 있도록 만드는 것입니다.
Apidog 명령줄 러너는 이 둘을 모두 처리합니다. Apidog는 앱에서 시각적으로 구축한 테스트 시나리오를 실행하는 CLI를 제공하며, -r, --reporters 플래그 하나로 생성되는 모든 보고서를 제어합니다. 쉼표로 구분된 목록을 전달하면, 러너는 각 형식을 디스크에 기록하고, 누가 무엇을 읽을지 결정합니다. 이 가이드는 해당 플래그와 그것이 생성하는 파일에 대한 것입니다. 즉, 각 리포터의 용도, 디스크에 기록되는 내용, 기록되는 위치, 그리고 각 리포터를 실제 워크플로에 연결하는 방법입니다. 러너가 허용하는 모든 플래그에 대한 더 넓은 개요를 원하시면, apidog run 명령어 참조에서 전체 내용을 다루고 있습니다. 이 페이지는 보고서에 중점을 둡니다.
실행보다 보고서가 더 중요한 이유
로컬에서 시나리오를 실행하면 그 과정을 직접 볼 수 있습니다. 각 요청이 실행되고, 각 어설션이 초록색으로 바뀌고, 마지막에 요약이 나타나는 것을 봅니다. 피드백 루프는 눈앞의 터미널에서 실시간으로 이루어집니다.
CI에서는 그 루프가 사라집니다. 실행은 당신이 볼 수 없는 머신에서, 당신이 지켜보지 않는 시간에 일어나며, 유일한 기록은 러너가 종료되기 전에 디스크에 기록된 내용뿐입니다. 실행이 보고서를 생성하지 않았다면, 실패는 단지 무언가가 고장 났다는 것만 알려줍니다. 당신은 전체를 로컬에서 다시 실행하고 같은 방식으로 고장 나기를 바랄 수밖에 없습니다.
좋은 보고서는 그 간극을 메워줍니다. 어떤 시나리오가 어떤 환경에서 몇 번 반복되었는지, 어떤 어설션이 통과하고 어떤 어설션이 실패했는지, 그리고 각 실패의 배경이 되는 요청 및 응답 세부 정보를 기록합니다. 이 정보를 디스크에 저장하면 새벽 2시의 실패가 다음 날 아침 재현 시도 대신 5분 만에 해결되는 문제가 됩니다. 이것이 바로 리포터 플래그가 존재하는 모든 이유이며, 각 대상에 맞는 올바른 형식을 선택하는 것이 몇 분간의 고민할 가치가 있는 이유입니다.
모든 보고서를 제어하는 단 하나의 플래그
Apidog CLI는 apidog-cli라는 npm 패키지입니다. 한 번 설치하면 단일 바이너리 apidog를 얻게 되며, 주 하위 명령어는 run입니다. 전역으로 설치하세요:
npm install -g apidog-cli
러너가 생성할 수 있는 모든 보고서는 해당 명령의 단일 플래그 -r, --reporters에서 나옵니다. 이것은 쉼표로 구분된 목록을 받으며, 허용하는 네 가지 값은 cli, html, json, junit입니다. 아무것도 전달하지 않으면 기본값은 cli입니다.
두 개의 리포터가 있는 완전한 실행은 다음과 같습니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
이것은 토큰으로 인증하고, 환경 1629989에 대해 테스트 시나리오 605067을 한 번 실행하며, HTML 파일과 읽기 쉬운 터미널 출력을 모두 생성합니다. ID는 시나리오 ID와 환경 ID이며, 액세스 토큰과 함께 Apidog의 시나리오 CI/CD 탭에서 복사하는 것이 수동으로 입력하는 것보다 낫습니다. 만약 이러한 설정이 익숙하지 않다면, Apidog CLI 전체 가이드에서 설치, 토큰 및 첫 실행 과정을 처음부터 끝까지 안내합니다.
핵심 아이디어: 한 번의 실행으로 여러 보고서를 동시에 생성할 수 있습니다. 단일 형식을 선택하는 것이 아닙니다. 각 출력에 대한 대상을 선택하고 함께 나열하는 것입니다. 일반적인 CI 라인은 동일한 실행에서 사람이 읽을 수 있는 HTML 파일과 기계가 읽을 수 있는 JUnit 파일을 생성하므로, 동일한 실행이 사람과 대시보드 모두에 서비스를 제공합니다.
cli: 빌드 로그에서 읽는 보고서
cli 리포터는 읽기 쉬운 요약을 터미널에 직접 출력합니다. 이것이 기본값이며, 사람이 가장 먼저 살펴보는 것입니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
이것이 제공하는 것은 실시간 결과입니다. 즉, 몇 개의 요청이 실행되었는지, 몇 개의 어설션이 통과하고 실패했는지, 그리고 어떤 특정 어설션이 고장 났는지 보여줍니다. CI 빌드 로그에서, 이것은 실패한 작업을 클릭했을 때 사람들이 읽는 블록입니다. 무엇이든 다운로드하기 전에 실패가 하나의 깨진 어설션 때문인지 50개 때문인지, 그리고 어떤 엔드포인트가 관련되어 있는지 한눈에 알 수 있습니다.
기계 형식을 작성할 때도 cli를 켜두세요. 비용이 들지 않으며 빌드 로그 자체를 유용하게 유지합니다. JUnit XML만 내보내는 파이프라인은 완벽한 대시보드를 생성하지만 쓸모없는 로그를 만듭니다. 원본 출력을 읽는 사람은 러너가 시작하고 종료하는 것 외에는 아무것도 보지 못합니다. 목록에 cli를 추가하면 이 문제가 해결됩니다:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
두 개의 플래그가 cli가 출력하는 내용을 형성합니다. --verbose는 각 단계에 대한 전체 요청 및 응답으로 확장하는데, 이는 시나리오가 노트북에서는 통과하지만 파이프라인에서는 실패할 때 가장 먼저 취해야 할 조치입니다. 와이어 세부 정보는 러너가 정확히 무엇을 보내고 받았는지 보여줍니다. --silent는 그 반대로 콘솔 출력을 완전히 억제하는데, 이는 종료 코드와 저장된 파일에만 관심 있는 시끄러운 예약 작업에 적합합니다.
html: 사람에게 건네주는 보고서
html 리포터는 자체 포함된 HTML 파일을 작성합니다. 어떤 브라우저에서든 열면 전체 실행 과정이 시각적으로 배치된 것을 볼 수 있습니다. 즉, 모든 요청, 그에 대한 어설션, 통과 및 실패 상태, 그리고 각 단계의 배경이 되는 요청 및 응답 세부 정보입니다. 설치할 것도 없고, 실행할 서버도 없습니다. 그냥 더블클릭하는 하나의 파일입니다.
이것은 아카이브하고 공유하는 형식입니다. 빌드 아티팩트로 저장하면 보고서가 파이프라인 실행보다 오래 지속되므로, 일주일 후에도 고장난 배포에서 생성된 정확한 보고서를 열어볼 수 있습니다. 또한 CLI를 설치하거나 아무것도 다시 실행하게 할 필요 없이 "무엇이 실패했나요?"라고 묻는 사람에게 보내는 것입니다. 그들은 파일을 열고, 빨간색 단계를 보고, 어설션을 유발한 응답 본문을 읽으면 끝입니다.
HTML은 데이터 기반 실행에서 가장 큰 가치를 발휘합니다. 하나의 시나리오가 50행의 CSV를 반복할 때, HTML 보고서는 각 반복당 결과를 보여주므로, 1행부터 49행까지는 통과했지만 50행은 한 계정에 오래된 토큰이 있었기 때문에 실패했음을 알 수 있습니다. 단순한 통과/실패 카운트만으로는 알 수 없습니다. 데이터 파일을 사용하여 시나리오를 실행하는 경우, 해당 패턴은 CSV 및 JSON을 이용한 데이터 기반 API 테스트에서 다룹니다.
트레이드오프: HTML은 눈으로 보는 것이지 파싱하기 위한 것이 아닙니다. 스크립트에서 통과/실패 상태를 얻기 위해 스크래핑하려고 하지 마세요. 그것은 JSON과 JUnit의 역할입니다.
junit: CI 대시보드가 파싱하는 보고서
junit 리포터는 표준 JUnit 형식으로 XML을 내보냅니다. 이 형식이 중요한 이유는 CI 테스트 보고의 공통 언어(lingua franca)이기 때문입니다. GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines 등 거의 모든 CI 시스템은 JUnit XML을 읽고 이를 통과/실패 트리로 변환하고, 병합 요청 위젯에 실패를 표시하며, 시간 경과에 따른 빌드 전반의 결과를 추세 분석하는 방법을 알고 있습니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
CI를 위해 정확히 하나의 기계 형식을 선택한다면, 이것을 선택하세요. 그 보상은 테스트 결과가 로그 파일에만 존재하는 것이 아니라 팀이 이미 보고 있는 대시보드에서 나타나기 시작한다는 것입니다. 리뷰어는 풀 리퀘스트를 열고 어떤 어설션이 실패했는지 인라인으로 렌더링된 것을 봅니다. 로그를 깊이 파고들거나 아티팩트를 다운로드할 필요가 없습니다.
연결하는 것은 두 단계입니다: XML을 생성한 다음, CI 시스템에 어디에서 찾을 수 있는지 알려줍니다. GitLab CI에서 그 두 번째 단계는 reports: junit: 블록입니다:
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
Jenkins에서는 동일한 파일들을 가리키는 post 블록의 junit 단계가 이에 해당합니다. GitHub Actions에서는 디렉토리를 아티팩트로 업로드하고 JUnit을 인식하는 액션이 이를 렌더링하게 합니다. 테스트가 실패해도 실행되는 아티팩트 업로드를 포함한 전체 GitHub 워크플로는 GitHub Actions에서 Apidog CLI 테스트 실행하기에 있습니다.
json: 스크립트가 후처리하는 보고서
json 리포터는 원시 구조화된 결과를 생성합니다. HTML은 눈으로 보는 것이고 JUnit은 대시보드를 위한 것이라면, JSON은 직접 작성하는 코드를 위한 것입니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
내장된 형식이 결과로 하고 싶은 작업에 맞지 않을 때 이 형식을 사용하세요. 합격률 메트릭을 모니터링 시스템으로 푸시합니다. 사용자 정의 Slack 요약을 만듭니다. 배포를 롤백할지 결정하는 스크립트에 결과를 공급합니다. 오늘의 실행 결과를 어제의 실행 결과와 비교합니다. 모든 프로그래밍 작업은 JSON에서 시작합니다. 구조를 추측할 필요 없이 파싱할 수 있는 형식이기 때문입니다.
JSON 출력만을 위해 특별히 만들어진 보고서 플래그가 하나 있습니다. --out-json-failures-separated <value>는 실패를 자체 JSON 파일로 분리합니다. 이는 실패만을 담은 문서를 제공하여, 깨진 몇 단계를 찾기 위해 전체 결과를 스캔하는 것보다 훨씬 쉽게 읽고 비교할 수 있습니다. 대부분의 단계가 통과하는 대규모 회귀 테스트에서는 실패 전용 파일이 훑어보는 것과 grep하는 것의 차이입니다.
파일이 저장되는 곳: --out-dir, --out-file 및 플레이스홀더
형식을 선택하는 것은 전체 그림의 절반에 불과합니다. 나머지 절반은 파일이 어디에 저장되고 어떤 이름으로 지정되는지를 제어하는 것인데, 이는 여러 번의 실행 보고서를 보관할 때 중요해집니다.
--out-dir <dir>은 보고서가 작성될 디렉토리를 설정합니다. 기본값은 ./apidog-reports입니다. CI에서는 아티팩트 단계가 찾을 수 있는 곳을 가리키고, 업로드 구성이 변경될 필요가 없도록 일관성을 유지하세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name>은 보고서 파일 이름을 설정하며, 여기서부터 유용해집니다. 이 플래그가 없으면 각 실행은 이전 실행을 덮어쓰는 경향이 있어 가장 최근 보고서만 보관하게 됩니다. 이 플래그는 러너가 작성 시점에 채워 넣는 플레이스홀더를 허용합니다:
{SCENARIO_NAME}은 실행된 시나리오의 이름이 됩니다.{FOLDER_NAME}은 시나리오 폴더를 실행할 때 폴더 이름이 됩니다.{GENERATE_TIME}은 타임스탬프가 됩니다.
시나리오 이름과 타임스탬프로 파일 이름을 지정하면 모든 실행이 이전 파일을 덮어쓰는 대신 고유하고 자체 설명적인 파일을 작성합니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
이제 보고서 디렉토리가 마치 역사서처럼 읽힙니다. 파일을 하나도 열어보지 않고도 어떤 보고서가 어떤 시나리오에서 왔고 언제 실행되었는지 알 수 있습니다. 이것은 야간 실행 폴더를 스캔하여 처음 문제가 발생한 것을 찾을 때 정확히 원하는 것입니다.
클라우드 측면을 완성하는 하나의 보고서 플래그가 더 있습니다. --upload-report [value]는 보고서 개요를 Apidog 클라우드에 업로드하므로, 로컬 파일과 함께 프로젝트 기록에도 실행 결과가 표시됩니다. CI 러너의 파일뿐만 아니라 Apidog 자체 내에서도 결과가 보이기를 원할 때 사용할 수 있는 옵션입니다.
대상별 리포터 전략
가장 깔끔한 결정 방법은 각 리포터를 누가 읽을지에 매핑한 다음, 필요한 것들을 함께 전달하는 것입니다.
- 지금 빌드 로그를 스캔하는 사람은
cli를 읽습니다. 항상 포함하세요. - 나중에 저장된 보고서를 여는 사람은
html을 읽습니다. 아티팩트로 아카이브하세요. - CI 대시보드는
junit을 읽습니다. 이것은 병합 요청에서 실패를 렌더링하고 빌드 전반에 걸쳐 결과를 추세 분석하는 것입니다. - 당신이 작성한 스크립트는
json을 읽습니다. 이것은 당신의 코드에 의해 파싱되도록 의도된 유일한 형식입니다.
대부분의 CI 파이프라인에서 주력 조합은 사람을 위한 HTML과 대시보드를 위한 JUnit이며, 원시 로그를 읽을 수 있도록 CLI를 켜두는 것입니다.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
한 번의 실행으로 읽기 쉬운 로그, 브라우징 가능한 아티팩트, 그리고 파싱 가능한 XML 파일이 생성됩니다. 세 가지 대상, 하나의 실행, 중복 없음.
명확하게 언급할 가치가 있는 한 가지 주의사항: 보고서는 무슨 일이 일어났는지 알려주지만, 파이프라인이 이에 따라 작동하게 하는 것은 종료 코드입니다. Apidog CLI는 어떤 어설션이든 실패하면 0이 아닌 값으로 종료되며, 빌드를 실패시키고 병합을 차단하는 것은 보고서가 아니라 그 종료 코드입니다. 보고서는 실패를 설명하고, 종료 코드는 이를 강제합니다. 셸에서 || true를 추가하는 것처럼 그 코드를 삼키는 것으로 명령어를 감싸지 마세요. 그렇지 않으면 여전히 초록색으로 진행된 빌드에 완벽한 빨간색 보고서가 첨부될 것입니다. 품질 게이트 로직의 더 심층적인 버전은 CI/CD에서 API 테스트 자동화 가이드에 있습니다.
종합하기
CI에서 시나리오를 실행하고 세 가지 대상을 위해 세 가지 유용한 아티팩트를 모두 내보내세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
야간 폴더 스윕을 실행하고, 모든 실패를 하나의 보고서에 수집하고, 각 파일에 자체 설명적인 이름을 부여하세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
데이터 기반 시나리오를 실행하고 빠른 비교를 위해 실패 전용 JSON을 유지하세요:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
일시적인 러너에 CLI를 전역으로 설치하고 싶지 않다면, 설치를 npx로 바꾸고 동일한 리포터 플래그를 유지하세요:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
리포터 동작은 어느 쪽이든 동일합니다. 전역 설치와 npx 사이의 선택은 어떤 보고서를 얻느냐에 대한 것이 아니라 러너 위생에 관한 것입니다.
플래그 이름, 기본값, 리포터는 CLI 릴리스에 따라 변경될 수 있으므로, 러너는 항상 자체적인 정보의 원천입니다. 설치된 버전에서 apidog run --help를 실행하고, 이 글을 포함한 어떤 기사보다 그 정보를 신뢰하세요. CLI가 실행하는 시나리오를 먼저 설정하려면, Apidog 다운로드, 앱에서 시나리오 하나를 구축한 다음, 해당 시나리오의 CI/CD 탭에서 생성된 명령어를 복사하고 필요한 리포터를 추가하세요.