대부분의 API 테스트는 GUI에서 시작됩니다. 클릭하고, 몇 가지 어설션을 추가하고, 수동으로 실행합니다. 이는 매 푸시마다, 매일 밤마다, 또는 아무도 지켜보지 않는 파이프라인 안에서 동일한 테스트를 실행해야 할 때까지는 잘 작동합니다. 그 시점에는 입력하고, 스크립트화하고, CI에 파이프라인할 수 있는 하나의 명령이 필요합니다.
그 명령이 바로 Apidog CLI입니다. 이 튜토리얼은 터미널에서 실제 REST API를 처음부터 끝까지 테스트하는 방법을 안내합니다: 도구 설치, API 가져오기, 환경 설정, 테스트 시나리오 구축, 어설션을 통한 실행, 데이터 공급, 그리고 보고서 수집까지. 아래의 모든 명령과 출력은 Apidog CLI 버전 2.2.2를 실제 공개 API에 대해 실행한 결과이므로, 그대로 따라하여 동일한 결과를 얻을 수 있습니다.
동일한 플랫폼의 시각적인 부분을 원한다면, Apidog를 다운로드하여 앱에서 먼저 테스트를 설계할 수 있습니다. 하지만 여기서는 모든 과정이 명령줄에서 진행됩니다.
무엇을 만들게 될까요?
실제 /objects 리소스를 통해 CRUD를 수행하는 무료 공개 REST API인 restful-api.dev를 테스트할 것입니다. 마지막에는 다음을 갖게 될 것입니다:
- OpenAPI 파일에서 시드된 Apidog 프로젝트
- 객체를 생성하고, 다시 읽어오고, 삭제하며 각 단계에서 어설션을 수행하는 3단계 테스트 시나리오
- 테스트 데이터의 각 행당 한 번씩 요청을 반복하는 데이터 기반 실행
- CLI, HTML, JSON, JUnit 보고서, 그리고 공유 가능한 클라우드 보고서
동일한 흐름이 여러분 자신의 API에도 확장 적용되며, CI/CD에서 API 테스트를 실행하기 위한 기반이 됩니다.
시작하기 전에
Node.js 16 이상과 Apidog 계정이 필요합니다. 러너를 먼저 비교하고 있다면, 간단히 말해 Apidog CLI는 전체 테스트 시나리오를 실행하고 API 리소스를 코드로 관리하므로, Newman 및 Postman CLI와 차별화됩니다.
단계 1: 설치 및 로그인
npm에서 CLI를 전역으로 설치하세요:
npm install -g apidog-cli@latest
설치 여부를 확인하세요:
apidog --version
# 2.2.2
이제 인증하세요. 아바타 아래의 Apidog 앱, 계정 설정, API 액세스 토큰에서 토큰을 가져온 다음 실행하세요:
apidog login --with-token <YOUR_TOKEN>
토큰은 ~/.apidog/config.toml에 저장되므로, 기기당 한 번만 수행하면 됩니다. 현재 사용자를 확인하세요:
모든 명령은 success 플래그와 유용한 agentHints가 포함된 구조화된 JSON을 반환하여, 출력을 스크립트화하거나 jq로 파이프 처리하기 쉽게 만듭니다.
단계 2: 프로젝트 생성
프로젝트를 생성할 팀을 선택한 다음, 프로젝트를 생성하세요:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
새 프로젝트 ID를 받게 됩니다.
나머지 튜토리얼을 복사-붙여넣기할 수 있도록 쉘 변수에 저장하세요:
PID=1314366 # replace with your project id
apidog project get $PID
단계 3: REST API 가져오기
엔드포인트를 수동으로 생성할 수도 있지만, OpenAPI 파일을 가져오는 것이 더 빠르고 실제 프로젝트가 시작되는 방식을 반영합니다. 다음은 /objects CRUD 엔드포인트를 설명하는 작은 스펙입니다 (objects-api.openapi.json으로 저장하세요):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
가져오세요:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoints created, 0 errors)
가져오기 도구는 openapi, postman, har, insomnia, jmeter 등도 읽어들입니다. 가져온 목록을 확인하세요:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
단계 4: 환경 설정
환경은 기본 URL과 테스트에서 재사용하는 모든 변수를 보관합니다. 하나를 생성하고 ID를 저장하세요:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # replace with your environment id
나중에 실행 명령에 -e $ENV를 전달하여 테스트가 요청을 보낼 위치를 알 수 있도록 합니다.
단계 5: 자동화 쓰기 게이트 통과하기
여기서 사람들이 종종 실수하는 첫 번째 문제입니다. 테스트 시나리오와 테스트 데이터는 자동화 리소스이며, 외부 도구에서 메인 브랜치에 쓰는 것은 기본적으로 차단되어 있습니다:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
이것은 버그가 아니라 안전장치입니다. 다음 두 가지 방법으로 통과할 수 있습니다:
- Apidog 데스크톱 앱의 프로젝트 설정, 기능 설정, AI 기능 설정, 외부 AI 편집 권한에서 직접 편집 권한을 켜세요.
- AI 브랜치에서 작업하여, 병합을 선택할 때까지 자동화 변경 사항을 격리합니다. 이 경로는 완전히 명령줄에서 이루어지므로, 이 방법을 사용하겠습니다.
main에서 브랜치를 생성하세요:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
명명 패턴 ai/YYYYMMDD-from--는 CLI가 예상하는 규칙입니다. import, environment create, 엔드포인트 편집은 게이트되지 않으며, 자동화 리소스만 게이트됩니다.
단계 6: 테스트 시나리오 구축
시나리오는 요청과 그 사이의 어설션으로 구성된 순서 있는 흐름입니다. 먼저 껍데기를 만들고, 그 다음에 단계를 추가합니다. AI 브랜치에서 생성하세요:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # the returned scenario id
단계는 JSON 파일을 사용하여 update를 통해 추가됩니다. 모든 JSON 쓰기에서 황금률은 보내기 전에 유효성을 검사하는 것입니다. 그래야 잘못된 페이로드를 절대 푸시하지 않습니다:
apidog cli-schema get test-scenario-update # see the exact shape
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
각 단계는 요청과 응답을 어설션하고 다음 단계로 데이터를 전달하는 작은 스크립트로 구성됩니다. 다음은 새 객체를 게시하고 나중 단계를 위해 id를 저장하는 생성 단계의 형태입니다:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
다음 단계에서는 URL에서 {{objId}}를 재사용하여 동일한 객체를 가져오고 삭제합니다. 전체 3단계 파일을 적용하세요:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
시나리오를 JSON으로 작성할 필요는 없습니다. Apidog에서 시각적으로 구축하고 CLI에서 실행하는 것도 유효한 방법입니다. JSON 경로는 테스트를 다른 코드처럼 버전 관리하고 검토하려는 경우에 중요합니다.
단계 7: 명령줄에서 실행하기
이것이 핵심입니다. CLI 리포터와 함께 시나리오를 실행하세요:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Http Requests 3 / 0 failed
Assertions 7 / 0 failed
세 개의 요청, 일곱 개의 어설션, 실패 없음, 그리고 생성된 id는 첫 번째 단계에서 다음 두 단계로 흘러갔습니다. 단 한 번의 클릭 없이 완벽한 API 테스트가 실행되었습니다.
콘솔 출력 대신 파일로 받고 싶으신가요? 여러 리포터를 한 번에 요청하고 폴더를 지정하세요:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
JUnit XML은 CI 서버가 빌드별 성공/실패를 표시하기 위해 읽는 파일입니다. HTML 보고서는 팀원들과 공유하는 보고서입니다.
단계 8: 여러 입력에 대해 동일한 테스트 실행
실제 테스트 스위트는 하나 이상의 케이스를 다룹니다. 데이터 기반 실행은 데이터의 각 행당 한 번씩 시나리오를 반복하므로, 열 개의 시나리오를 작성하지 않고 열 개의 입력을 테스트할 수 있습니다. 이는 CSV 및 JSON에서 매개변수화된 테스트와 동일한 개념입니다.
행을 파일에 넣으세요:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
-d로 데이터를 참조하고, 시나리오가 각 행에서 {{name}}과 {{price}}를 읽도록 하세요:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iteration 1/3 … ✓ row created (200) ✓ name matches the data row
Iteration 2/3 … ✓ row created (200) ✓ name matches the data row
Iteration 3/3 … ✓ row created (200) ✓ name matches the data row
Iterations 3 / 0 failed Assertions 6 / 0 failed
세 개의 행을 입력하면 세 번의 반복이 나옵니다. 파일을 CSV로 바꾸어도 다른 것은 변경되지 않습니다.
단계 9: 보고서 수집
로컬 실행은 파일을 작성합니다. 전체 팀이 브라우저에서 열 수 있는 보고서를 얻으려면 --upload-report를 추가하세요:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Apidog CLI runs data uploaded to the cloud successfully.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
알아둘 만한 한 가지 주의할 점: 클라우드 보고서는 실행된 브랜치로 태그됩니다. 이 실행은 AI 브랜치에서 발생했으므로, 일반적인 apidog test-report list --project $PID (main을 대상으로 함)로는 표시되지 않습니다. 대신 업로드 링크에서 ID로 가져오세요:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
단계 10: API를 문서 또는 스펙으로 내보내기
CLI는 또한 데이터를 외부로 푸시합니다. 프로젝트를 OpenAPI 파일, Markdown 또는 HTML 문서로 내보내세요:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
이것은 변경될 때마다 새로운 스펙을 커밋하거나 파이프라인에서 정적 문서를 게시하는 데 유용합니다.
단계 11: CI/CD에 연결하기
수동으로 실행한 모든 것이 파이프라인에서 세 줄이 됩니다. 핵심은 설치한 다음 JUnit 리포터로 실행하여 CI 서버가 결과를 읽을 수 있도록 하는 것입니다:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
토큰을 시크릿으로 저장하고, 테스트가 실패하면 빌드를 실패시키세요 (CLI는 실패 시 0이 아닌 종료 코드를 반환합니다). 전체 복사-붙여넣기 워크플로를 보려면 GitHub Actions에서 Apidog CLI 테스트 실행 가이드를 참조하거나, 파이프라인에 적합한 API 테스트 자동화 도구를 살펴보세요.
마무리
빈 터미널에서 공유 가능한 보고서가 포함된 통과하는 데이터 기반 API 테스트를 실행했고, 명령줄을 벗어나지 않았습니다. 패턴은 항상 동일합니다: API를 가져오거나 설계하고, 환경을 생성하고, 어설션이 포함된 시나리오를 구축한 다음, apidog run으로 실행합니다. 이 명령이 로컬에서 작동하면, CI에 추가하는 것은 세 줄만 변경하면 됩니다.
동일한 단계를 자신의 API에 적용하고, 시나리오 파일을 코드와 함께 커밋하면, 쉘이 있는 모든 곳에서 테스트가 실행됩니다. 시작하려면 Apidog를 다운로드하고, CLI가 과도하게 느껴지는 간단한 일회성 검사에는 REST API 테스트를 위한 curl 대안을 편리하게 사용하세요.