apidog-cli를 설치하고 apidog run을 실행하며 JUnit 결과를 게시하는 단일 Run 단계가 포함된 CI 스테이지를 추가하여 Harness에서 Apidog CLI 테스트를 실행합니다. Apidog 액세스 토큰을 Harness 보안 비밀로 저장하고, <+secrets.getValue("...")> 표현식으로 참조하며, JUnit 보고서 블록을 CLI의 XML 출력으로 지정하세요. 이 가이드는 Harness Cloud와 자체 호스팅 델리게이트 모두에 대한 복사-붙여넣기 파이프라인 YAML을 제공합니다.
Harness CI/CD란 무엇인가요?
Harness CI는 Harness 플랫폼의 지속적 통합 모듈입니다. 관리형 또는 자체 호스팅 빌드 인프라에서 코드를 빌드, 테스트, 검증한 후, 배포를 위해 Harness CD에 아티팩트를 전달합니다.
모든 것을 YAML로 정의합니다. 파이프라인에는 하나 이상의 스테이지가 포함됩니다. 각 스테이지는 유형을 가지며, CI 스테이지는 빌드 인프라에서 실행됩니다. 스테이지 내부에 있는 실행 블록은 명령을 실행하는 단계의 정렬된 목록을 포함합니다.
이 모델은 API 테스트에 깔끔하게 적용됩니다. CI 스테이지를 추가하고, 테스트 명령을 실행하는 단계를 삽입한 다음, Harness가 결과에 따라 빌드를 게이트하도록 합니다. 테스트가 실패하면 단계가 실패하고 파이프라인이 중지됩니다.
Harness는 테스트 보고를 위해 JUnit XML을 읽습니다. Apidog CLI는 JUnit을 내보낼 수 있으므로, 모든 빌드에서 통과 및 실패 횟수가 있는 기본 테스트 탭을 얻을 수 있습니다. 별도의 연결 코드는 필요 없습니다.
Harness CI 작동 방식
YAML 계층 구조는 엄격하므로, 작성하기 전에 중첩 구조를 이해하는 것이 도움이 됩니다. CI 파이프라인은 위에서 아래로 다음과 같습니다.
pipeline은 메타데이터와stages목록을 담습니다.- 각
stage는type: CI와spec을 가집니다. - 스테이지
spec은 빌드 인프라와execution블록을 선언합니다. execution은steps목록을 담습니다.- 각
step은type,name,identifier, 그리고 자체spec을 가집니다.
셸 명령을 실행하기 위한 단계 유형은 Run입니다. Run 단계의 spec은 shell 필드(Bash, Sh, PowerShell, Pwsh 또는 Python)와 스크립트를 담는 command 필드를 포함합니다. YAML 블록 스칼라 |-를 사용하여 여러 줄 명령을 작성합니다.
이 단일 Run 단계만으로 Apidog CLI를 설치하고 실행할 수 있습니다. 이 가이드의 모든 다른 내용은 이 한 단계를 둘러싼 구성입니다.
1분 만에 알아보는 Apidog CLI
Apidog CLI는 Apidog에서 시각적으로 구축한 테스트 시나리오를 위한 명령줄 러너입니다. Postman 컬렉션을 실행하는 Newman과 유사하게, 앱에서 테스트를 설계한 다음 모든 파이프라인에서 헤드리스 방식으로 실행합니다. Apidog CLI와 Newman을 비교하려면 Apidog CLI vs Newman을 참조하세요.
npm에서 설치하고 단일 명령을 실행합니다:
npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports
CI에 중요한 몇 가지 플래그가 있습니다. --access-token 플래그는 클라우드 실행을 인증하며 짧은 형식은 없습니다. -e 플래그는 환경을 설정하며 필수입니다. -t 플래그는 ID로 테스트 시나리오를 선택합니다. -r 플래그는 리포터를 선택하며, junit는 지원되는 값 중 하나입니다(cli, html, json, junit). --out-dir 플래그는 보고서가 저장될 위치를 제어하며, 기본값은 ./apidog-reports입니다.
이 -r cli,junit 선택은 Harness로의 다리 역할을 합니다. CLI는 JUnit XML을 출력 디렉토리에 작성하고, Harness는 이를 직접 읽습니다. CLI가 생성하는 내용에 대한 자세한 내용은 Apidog CLI 테스트 보고서 가이드를 참조하세요.
Harness 보안 비밀로 Apidog 액세스 토큰 저장하기
YAML에 토큰을 절대 하드코딩하지 마세요. 먼저 Harness 보안 비밀 관리자에 추가한 다음 참조하세요.
Harness UI에서 프로젝트 (또는 조직/계정) 설정으로 이동하여 보안 비밀을 열고 새 텍스트 보안 비밀을 생성하세요. 식별자를 apidog_token으로 지정하세요. 식별자는 YAML에서 참조하는 것이며, 표시 이름과 다릅니다.
다음 표현식으로 보안 비밀을 참조합니다:
<+secrets.getValue("apidog_token")>
표시 이름 대신 따옴표 안에 식별자를 사용하세요. 조직 범위 보안 비밀의 경우 org.apidog_token처럼 org.를 접두사로 붙이세요. 계정 범위 보안 비밀의 경우 대신 account.를 사용하세요.
셸 명령 내에서 표현식을 작은따옴표로 묶으세요. 토큰에 $ 문자가 포함될 수 있으며, 작은따옴표는 셸이 이를 확장하는 것을 막습니다. 토큰 설정에 대한 자세한 내용은 Apidog CLI 인증 노트를 참조하세요.
Harness Cloud 파이프라인 (권장 시작점)
Harness Cloud는 Node.js와 npm이 사전 설치된 Harness 관리 빌드 머신을 제공합니다. 유지보수할 인프라가 없으며, Linux는 즉시 실행됩니다. 이것이 작동하는 파이프라인을 얻는 가장 빠른 방법입니다.
Harness Cloud에서 스테이지 spec은 platform 블록과 type: Cloud의 runtime 블록을 사용합니다. 관리형 머신에 이미 도구가 있으므로 여기서는 Run 단계에 image를 지정하지 않습니다.
pipeline:
name: Apidog API Tests
identifier: apidog_api_tests
projectIdentifier: YOUR_PROJECT
orgIdentifier: YOUR_ORG
stages:
- stage:
name: API Tests
identifier: api_tests
type: CI
spec:
cloneCodebase: false
platform:
os: Linux
arch: Amd64
runtime:
type: Cloud
spec: {}
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 \
-e 1629989 \
-n 1 \
-r cli,junit \
--out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
605067을 테스트 시나리오 ID로, 1629989를 환경 ID로 교체하세요. -n 1 플래그는 한 번 반복 실행합니다. 테스트가 Apidog 클라우드에 있으므로 파이프라인이 저장소를 필요로 하지 않기 때문에 cloneCodebase: false로 설정하세요.
테스트 결과 게시
Run 단계의 reports 블록은 Harness에 결과를 표시하는 역할을 합니다. type으로 JUnit을, paths 목록을 통해 XML 파일을 가리키는 spec을 사용합니다.
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
Harness는 기본 보고를 위해 JUnit XML만 파싱합니다. 빌드 후, 각 시나리오, 상태 및 타이밍이 표시되는 테스트 탭을 볼 수 있습니다. apidog-reports/*.xml 글로브는 CLI가 -r cli,junit로 기본 출력 디렉토리에 작성한 파일과 일치합니다.
Harness는 또한 코드 변경에 의해 영향을 받는 테스트만 실행하는 별도의 Test 단계 유형을 사용하는 Test Intelligence를 제공합니다. 이 최적화는 헤드리스 API 시나리오가 아닌 언어 수준 단위 테스트를 대상으로 합니다. Apidog CLI 출력을 수집하려면 JUnit reports 블록이 있는 일반 Run 단계가 올바른 경로입니다.
리포터를 변경하더라도 -r 목록에는 최소한 junit를 유지하세요. junit가 없으면 CLI는 XML을 작성하지 않으며, 단계 자체가 통과하더라도 테스트 탭은 비어 있습니다.
자체 호스팅 델리게이트 대안
개인 네트워크 액세스, 사용자 지정 또는 레거시 런타임이 필요하거나 Harness Cloud 빌드 크레딧을 피하고 싶을 때 델리게이트 기반 빌드를 사용하세요. Kubernetes 델리게이트는 각 스테이지를 Pod로 실행합니다.
구조는 두 가지 방식으로 변경됩니다. 스테이지 spec은 platform 및 runtime 대신 infrastructure 블록을 사용합니다. 그리고 Kubernetes 인프라에서는 각 Run 단계가 connectorRef와 image를 선언해야 합니다. 왜냐하면 단계가 지정한 컨테이너 내부에서 실행되기 때문입니다.
spec:
cloneCodebase: false
infrastructure:
type: KubernetesDirect
spec:
connectorRef: YOUR_K8S_CONNECTOR
namespace: harness-ci
execution:
steps:
- step:
type: Run
name: Run Apidog CLI Tests
identifier: run_apidog_cli_tests
spec:
connectorRef: YOUR_DOCKER_CONNECTOR
image: node:20
shell: Sh
command: |-
npm install -g apidog-cli
apidog run \
--access-token '<+secrets.getValue("apidog_token")>' \
-t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
reports:
type: JUnit
spec:
paths:
- apidog-reports/*.xml
image: node:20 줄은 Pod 내부에 Node.js와 npm을 제공합니다. connectorRef 값은 등록된 Kubernetes 및 Docker 커넥터를 가리킵니다. 한 스테이지에서 두 가지 인프라 스타일을 혼합하지 마세요. 스테이지는 Harness Cloud (platform + runtime)이거나 델리게이트 기반 (infrastructure)이어야 하며, 둘 다일 수는 없습니다.
Harness Cloud와 델리게이트 선택
API가 위치한 곳과 빌드 머신 소유자를 기준으로 선택하세요.
| 요소 | Harness Cloud | 자체 호스팅 델리게이트 |
|---|---|---|
| 설정 | 인프라 제로, npm 사전 설치됨 | 클러스터 또는 VM 관리 |
| 네트워크 도달 범위 | 공개 엔드포인트 | 비공개 및 내부 엔드포인트 |
| Run 단계 이미지 필요 여부 | 아니요 | 예, Kubernetes 인프라에서 |
| 비용 모델 | 빌드 크레딧 사용 | 자체 컴퓨팅 |
| 가장 적합한 경우 | 클라우드 API, 빠른 시작 | 내부 API, 사용자 지정 런타임 |
Apidog 환경이 공개 엔드포인트를 사용한다면 Harness Cloud부터 시작하세요. 테스트 환경이 VPN 뒤에 있거나 제어해야 하는 런타임이 필요할 때 델리게이트로 전환하세요. Run 단계와 Apidog 명령은 두 가지 경우 모두 거의 동일하게 유지됩니다.
데이터 기반 실행
매개변수화된 테스트를 위해 CSV 또는 JSON 파일을 실행에 공급할 수 있습니다. -d 플래그 (긴 이름 --iteration-data)는 데이터 파일 경로를 가져오고, -n은 반복 횟수를 설정합니다.
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports
이는 데이터 행당 한 번 시나리오를 실행합니다. Harness Run 단계에서는 먼저 git clone하거나 다른 방식으로 데이터 파일을 스테이징한 다음, -d를 해당 경로로 지정해야 합니다. 전체 패턴은 Apidog CLI 데이터 기반 테스트 및 더 광범위한 자동화된 API 테스트 가이드를 참조하세요.
Apidog에서 먼저 테스트를 설계해야 하는 이유
CLI는 Apidog 프로젝트에 이미 존재하는 시나리오만 실행합니다. 이것이 핵심입니다. Apidog는 설계, 디버깅, 테스트, 모킹 및 문서를 위한 올인원 API 플랫폼이므로, 테스트 스위트를 한 번 구축하고 모든 곳에서 재사용할 수 있습니다.
시각적 빌더를 사용하여 스크립팅 없이 테스트를 설계할 수 있습니다. 요청을 연결하고, 한 응답에서 다음 응답으로 값을 추출하며, UI를 통해 어설션을 추가할 수 있습니다. 그런 다음 CLI는 Harness에서 해당 스위트를 헤드리스 방식으로 정확하게 실행하므로, 로컬에서 디버그하는 것이 파이프라인에서 실행되는 것과 동일합니다.
Apidog는 브랜치 지원 및 팀 작업 공간을 갖춘 OpenAPI-native이므로, QA 엔지니어와 백엔드 개발자가 단일 진실의 원천을 공유합니다. 브랜치에서 승인된 시나리오는 apidog run 명령이 실행하는 것과 동일한 시나리오가 됩니다. 더 넓은 파이프라인 패턴을 위해 CI/CD란 무엇인가 입문서와 GitHub Actions 워크플로 가이드는 다른 시스템에서 동일한 CLI를 다룹니다. Apidog 자동화 테스트를 Jenkins와 통합하는 방법의 Jenkins 튜토리얼은 동일한 명령 형태를 사용합니다.
첫 번째 테스트 시나리오를 구축하려면 Apidog를 무료로 다운로드한 다음, 위의 YAML을 사용하여 Harness에 연결하세요.
자주 묻는 질문
Harness CI/CD는 무엇인가요?
Harness CI/CD는 소프트웨어 빌드, 테스트 및 배포를 위한 파이프라인 플랫폼입니다. 스테이지와 단계로 구성된 YAML로 파이프라인을 정의합니다. CI 스테이지는 Harness가 관리하는 클라우드 머신 또는 자체 호스팅 델리게이트와 같은 빌드 인프라에서 실행되며, CD 스테이지는 배포를 처리합니다.
Harness CI는 어떻게 작동하나요?
파이프라인은 스테이지 목록을 담습니다. 각 CI 스테이지는 빌드 인프라를 선언하는 사양과 실행 블록을 가집니다. 실행 블록은 정렬된 단계 목록을 실행합니다. Run 단계는 셸 명령을 실행하는데, 여기에서 Apidog CLI를 설치하고 실행합니다.
Harness에서 보안 비밀을 저장하고 사용하는 방법은 무엇인가요?
Harness 보안 비밀 관리자에서 텍스트 보안 비밀을 생성하고 그 식별자를 기록합니다. YAML에서 <+secrets.getValue("identifier")>를 사용하여 표시 이름 대신 식별자로 참조합니다. 해당 범위의 경우 org. 또는 account.를 접두사로 사용하고, 셸 명령 내에서 표현식을 작은따옴표로 묶습니다.
Harness에서 테스트 결과를 게시하는 방법은 무엇인가요?
Run 단계에 type: JUnit과 XML 파일을 가리키는 paths 목록을 포함하는 reports 블록을 추가하세요. Harness는 JUnit XML을 파싱하고 빌드의 테스트 탭에 결과를 표시합니다. Apidog CLI는 -r junit 또는 -r cli,junit를 전달할 때 이 XML을 내보냅니다.
Harness CI는 무료인가요?
Harness는 CI를 위한 무료 티어를 제공하며, Harness Cloud 빌드는 플랜에 포함된 빌드 크레딧을 소모합니다. 가격 및 크레딧 한도는 시간이 지남에 따라 변경될 수 있으므로, 티어를 결정하기 전에 현재 Harness 가격 페이지에서 정확한 수치를 확인하세요.
내 저장소를 클론하지 않고 Apidog CLI 테스트를 실행할 수 있나요?
예. 테스트가 Apidog 클라우드에 있을 때 스테이지에 cloneCodebase: false로 설정하세요. CLI는 액세스 토큰으로 인증하고 ID로 시나리오와 환경을 가져오므로, 파이프라인은 테스트 실행을 위해 소스 코드를 필요로 하지 않습니다.