Node 이미지를 사용하고 `apidog-cli`를 설치하며 환경에 대해 `apidog run`을 실행하는 Docker 파이프라인 단계를 추가하여 Drone CI에서 Apidog CLI API 테스트를 실행합니다. Apidog 액세스 토큰은 Drone 시크릿에 저장되며 `from_secret`을 통해 주입됩니다. 이 가이드에서는 복사-붙여넣기 `.drone.yml`, 시크릿 처리, 브랜치 게이팅, 그리고 Drone에 내장 아티팩트 저장소가 없기 때문에 테스트 보고서를 노출하는 방법을 설명합니다.
Drone CI란 무엇이며 어떻게 작동하는가
Drone은 오픈소스 컨테이너 네이티브 CI/CD 플랫폼이며, 현재 Harness의 일부입니다. CI/CD는 지속적 통합 및 지속적 배포를 의미하며, 변경사항 발생 시 자동으로 코드를 빌드하고 테스트하는 관행입니다. 이 개념 자체에 대한 자세한 정보는 CI/CD란 무엇인가를 참조하십시오.
Drone의 특징은 간단합니다. 모든 파이프라인 단계는 자체 Docker 컨테이너 내에서 실행됩니다. 사전 설치된 도구가 복잡하게 널려 있는 공유 빌드 에이전트는 없습니다. 각 단계에 대한 이미지를 선택하면 Drone이 그 안에서 명령을 실행합니다. 이는 빌드를 재현 가능하게 만들고 이해하기 쉽게 만듭니다.
리포지토리의 루트에 있는 `.drone.yml` 파일에 파이프라인을 정의합니다. Docker 파이프라인에는 `kind`, `type`, `name`이라는 세 가지 최상위 키가 있습니다. 작업은 `steps` 아래에서 이루어지며, 각 단계는 `name`, `image`, `commands` 목록을 선언합니다.
kind: pipeline
type: docker
name: api-tests
steps:
- name: greeting
image: alpine
commands:
- echo hello
- echo world
Drone은 `set -e` 및 `set -x`를 사용하여 `commands`를 셸 스크립트로 실행하므로, 첫 번째 0이 아닌 종료 코드에서 빌드가 빠르게 실패하고 각 명령을 실행하기 전에 에코합니다. 명령은 컨테이너 진입점을 재정의하며, 작업 디렉토리는 리포지토리 루트입니다.
컨테이너 단계에서 API 테스트를 실행하는 이유
API 테스트는 계약 불일치를 방지합니다. 응답 형태나 상태 코드를 조용히 변경하는 백엔드 변경은 모든 다운스트림 클라이언트를 손상시킬 수 있습니다. 모든 푸시에서 이러한 테스트를 실행하면 배포되기 전에 회귀를 발견합니다.
Apidog는 이 모델에 잘 맞습니다. Apidog 앱에서 시각적으로 테스트를 구축하고 유지보수하며, Apidog CLI를 사용하여 명령줄에서 정확히 동일한 테스트 시나리오를 실행합니다. 스크립트를 다시 작성할 필요도 없고 별도의 테스트 하네스도 필요 없습니다. 파이프라인에 API 테스트를 연결하는 방법에 대한 더 넓은 지침은 API 테스트를 위한 CI/CD 모범 사례를 참조하십시오.
Apidog는 설계, 디버깅, 테스트, 모킹 및 문서를 위한 올인원 API 플랫폼입니다. CLI는 저장된 테스트 시나리오를 Drone 단계에 필요한 단일 반복 가능한 명령으로 변환하는 부분입니다.
실행할 Apidog CLI 명령
npm으로 CLI를 설치한 다음 테스트 시나리오를 실행합니다. CI에서는 플래그를 사용하여 저장된 시나리오를 가리키므로 관리할 로컬 컬렉션 파일이 없습니다.
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
각 플래그의 기능은 다음과 같습니다.
- `--access-token`은 Apidog 액세스 토큰을 전달합니다. 짧은 형식은 없습니다.
- `-t`는 실행하려는 테스트 시나리오 ID입니다.
- `-e`는 환경 ID이며 필수입니다. 이는 실행이 사용하는 기본 URL 및 변수를 선택합니다.
- `-r`은 리포터를 나열합니다. 유효한 값은 `cli`, `html`, `json`, `junit`입니다.
필요에 따라 더 많은 플래그를 추가할 수 있습니다.
- `-n` 또는 `--iteration-count`는 지정된 횟수만큼 실행을 반복합니다.
- `-d` 또는 `--iteration-data`는 데이터 기반 실행을 위해 CSV 또는 JSON 파일 경로 또는 숫자 저장 데이터 세트 ID를 사용합니다.
- `--out-dir`은 보고서 출력 디렉토리를 설정합니다.
- `--upload-report`는 보고서 개요를 Apidog 클라우드로 푸시하여 앱에서 볼 수 있습니다. 이 플래그만 사용할 수 있습니다.
- `--on-error`는 `continue`, `end`, `ignore`로 실패 동작을 제어합니다.
- `--project <id>` 및 `--branch <name>`은 특정 프로젝트 브랜치를 대상으로 합니다.
명령과 그 옵션에 대한 전체 설명은 Apidog CLI 완전 가이드 및 명령줄에서 REST API 테스트에 대한 가이드를 참조하십시오.
Apidog 테스트를 위한 완전한 .drone.yml
다음은 작동하는 파이프라인입니다. Node 이미지를 사용하고 CLI를 설치하며 시나리오를 실행합니다. 토큰은 하드코딩되지 않고 Drone 시크릿에서 가져옵니다.
kind: pipeline
type: docker
name: apidog-api-tests
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
trigger:
branch:
- main
event:
- push
- pull_request
`1234567`을 테스트 시나리오 ID로, `89012`를 환경 ID로 바꿉니다. 둘 다 Apidog 앱에서 볼 수 있습니다. 단계가 `cli` 리포터를 사용하기 때문에 전체 통과/실패 분석이 Drone 빌드 로그에 직접 출력되어 빌드를 검토하는 누구든지 읽을 수 있습니다.
Drone CI에 시크릿 저장
API 토큰을 절대로 리포지토리에 커밋하지 마십시오. Drone은 YAML에서 시크릿을 제외하고 런타임에 주입합니다.
단계의 `environment` 블록(또는 플러그인의 `settings` 블록) 내에서 `from_secret`을 사용하여 시크릿을 참조합니다. 작성하는 값은 토큰 자체가 아니라 시크릿의 이름입니다.
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
시크릿을 생성하는 두 가지 일반적인 방법이 있습니다. 첫 번째는 Drone UI입니다. 리포지토리를 열고, Settings, Secrets로 이동한 다음, 토큰을 값으로 사용하여 `apidog_access_token`이라는 시크릿을 추가합니다. 두 번째는 Drone 명령줄 도구입니다.
drone secret add \
--repository your-org/your-repo \
--name apidog_access_token \
--data your-apidog-token
CLI 플래그는 릴리스 간에 변경될 수 있으므로, 사용 중인 버전의 Drone CLI 문서에서 정확한 플래그 이름을 확인하십시오. Drone은 또한 `drone encrypt`가 별도의 `kind: secret` YAML 문서로 포함할 암호화된 블롭을 생성하는 리포지토리 내 암호화된 시크릿 변형을 지원합니다. 대부분의 팀에서는 UI 또는 `drone secret add`를 통해 추가된 리포지토리 시크릿이 더 간단하고 권장되는 시작점입니다.
토큰을 시크릿에 보관하는 것은 다른 곳에서도 적용하는 것과 동일한 원칙입니다. CLI가 자격 증명을 처리하는 방법에 대한 자세한 내용은 Apidog CLI 인증에 대한 가이드를 참조하십시오.
브랜치 및 이벤트별 실행 제어
Drone은 작업 실행 시기를 제어하는 두 가지 레버를 제공합니다. 파이프라인 수준의 `trigger`와 단계 수준의 `when`입니다.
`trigger` 블록은 전체 파이프라인을 실행할지 여부를 결정합니다. 모든 조건이 true로 평가되어야 하므로 아래 예시는 `main`을 대상으로 하는 푸시 및 풀 리퀘스트에서만 실행됩니다.
trigger:
branch:
- main
event:
- push
- pull_request
`when` 블록은 단일 단계 내에 있으며 해당 단계만 제어합니다. 이는 파이프라인의 대부분을 모든 곳에서 실행하되, 더 무거운 테스트는 하나의 브랜치에 예약하고 싶을 때 유용합니다.
steps:
- name: run-api-tests
image: node:20-alpine
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
when:
branch:
- main
event:
- push
두 블록 모두 글로브 패턴과 포함/제외 하위 키를 지원합니다. 지원되는 이벤트 유형에는 `push`, `pull_request`, `tag`, `promote`, `rollback`, `cron`, `custom`이 있습니다.
아티팩트 저장소 없이 테스트 보고서 노출
Drone에는 네이티브 아티팩트 호스팅 기능이 없습니다. 이는 보고서를 처리하는 방식을 변경하지만, 두 가지 깔끔한 옵션이 있습니다.
첫 번째는 가장 간단한 방법입니다. `cli` 리포터를 사용하여 결과가 빌드 로그에 출력되도록 합니다. 대부분의 팀에서는 로그에 이미 어떤 어설션이 통과하고 실패했는지 표시되므로 이 정도로 충분합니다.
두 번째 옵션은 HTML 보고서를 생성하고 영구적인 어딘가에 업로드하는 것입니다. Drone은 파일을 S3 또는 S3 호환 저장소에 업로드하는 공식 S3 플러그인인 `plugins/s3`를 제공합니다. `html` 리포터와 `--out-dir`을 사용하여 보고서를 생성한 다음 업로드 단계를 추가합니다.
steps:
- name: run-api-tests
image: node:20-alpine
environment:
APIDOG_ACCESS_TOKEN:
from_secret: apidog_access_token
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports
- name: upload-report
image: plugins/s3
settings:
bucket: my-bucket
region: us-east-1
source: reports/**/*
target: /apidog-reports
access_key:
from_secret: aws_access_key
secret_key:
from_secret: aws_secret_key
이 플러그인은 Apidog 토큰에 사용한 것과 동일한 메커니즘인 `from_secret`을 통해 AWS 자격 증명을 읽습니다. `source` 키는 업로드할 파일의 글로브이며, `target`은 버킷 내의 대상 접두사입니다.
보고서 내용과 읽는 방법에 대한 자세한 내용은 Apidog CLI 테스트 보고서 분석을 참조하십시오.
데이터 기반 실행 추가
때로는 하나의 시나리오가 많은 입력 행(예: 10개의 사용자 ID, 12개의 페이로드, 일련의 엣지 케이스)에 대해 실행되어야 할 때가 있습니다. CLI는 CSV 또는 JSON 파일 경로 또는 저장된 데이터 세트 ID를 허용하는 `-d`로 이를 처리합니다.
commands:
- npm install -g apidog-cli
- apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli
`data.csv`의 각 행은 하나의 반복이 되며, 열 값은 시나리오 변수에 바인딩됩니다. 전체 패턴은 Apidog CLI 데이터 기반 테스트에서 다룹니다.
다른 CI 도구와 비교
Drone 패턴(깨끗한 컨테이너에 CLI를 설치하고 하나의 명령을 실행)은 거의 모든 CI 시스템에 적용됩니다. 래퍼 구문은 다르지만, Apidog 단계는 동일합니다.
다른 곳에서도 파이프라인을 실행하는 경우, Apidog는 GitHub Actions 및 Azure Pipelines에 대한 일치하는 설명도 제공합니다. 공통된 아이디어는 테스트가 Apidog에 존재하고 CI 도구는 단순히 테스트를 트리거한다는 것입니다.
범위에 대한 솔직한 참고: Apidog CLI는 기능 및 계약 테스트를 실행하며, 대규모 부하 테스트는 실행하지 않습니다. 엔드포인트에 스트레스를 주기 위해 수천 명의 동시 가상 사용자가 필요한 경우, 전용 부하 테스트 도구를 사용하십시오. 모든 커밋에서 API가 올바르게 작동하는지 확인하는 데는 Drone 단계의 CLI가 충분히 잘 작동합니다.
테스트를 시각적으로 구축하고 하나의 명령으로 실행
이것을 즐겁게 만드는 워크플로우는 작성과 실행의 분리입니다. Apidog에서 엔드포인트를 설계하고 시각적으로 테스트 시나리오를 조립하며, 요청을 연결하고, 상태 코드 및 응답 필드를 어설션하고, 환경 변수를 재사용합니다. 스위트를 구축하는 데 코드가 필요 없습니다.
그런 다음 CI는 컨테이너 단계 내에서 하나의 CLI 명령으로 동일한 스위트를 실행합니다. 팀원이 Apidog 앱에서 테스트를 업데이트하면 다음 Drone 빌드가 자동으로 이를 반영합니다. 동기화할 테스트의 두 번째 복사본은 없습니다.
첫 번째 테스트 시나리오를 구축하려면 Apidog를 무료로 다운로드한 다음, 위의 `.drone.yml`을 리포지토리에 넣어 모든 푸시에서 실행하십시오.
자주 묻는 질문
Drone CI란 무엇입니까?
Drone은 오픈소스 컨테이너 네이티브 CI/CD 플랫폼이며, 현재 Harness의 일부입니다. 모든 파이프라인 단계를 자체 Docker 컨테이너 내에서 실행하며, 파이프라인은 `.drone.yml` 파일에 정의됩니다. 이는 빌드를 재현 가능하게 만들고 전통적인 빌드 에이전트의 사전 설치된 도구 복잡성을 방지합니다.
Drone CI는 무료입니까?
핵심 Drone 프로젝트는 오픈소스이며 자체 호스팅이 무료입니다. Harness 인수 후 Drone은 Harness CI Community Edition이 되었으며, 유료 엔터프라이즈 티어가 제공됩니다. 대부분의 팀에서는 자체 호스팅 오픈소스 버전으로 이 가이드에 있는 것과 같은 API 테스트를 실행할 수 있습니다.
Drone CI는 오픈소스입니까?
예. Drone은 오리지널 컨테이너 네이티브 CI 도구 중 하나이며 오픈소스로 남아 있습니다. 2020년 Harness가 이를 인수했을 때, 회사는 프로젝트를 오픈소스로 유지하겠다고 약속했으며, 여전히 자체 호스팅할 수 있습니다.
Drone CI는 어떻게 사용됩니까?
팀은 모든 푸시 또는 풀 리퀘스트에서 코드를 자동으로 빌드, 테스트 및 배포하기 위해 Drone을 사용합니다. 리포지토리에 `.drone.yml`을 커밋하면 Drone이 이를 읽고 각 단계를 컨테이너에서 실행합니다. 일반적인 단계에는 코드 컴파일, 단위 테스트 실행, API 테스트 실행, 외부 저장소에 아티팩트 업로드가 포함됩니다.
Drone CI에 시크릿을 어떻게 저장합니까?
Drone UI의 리포지토리 설정(Settings) -> 시크릿(Secrets) 화면을 통해 또는 CLI에서 `drone secret add`를 사용하여 시크릿을 추가합니다. 그런 다음, 각 시크릿을 단계의 `environment` 또는 플러그인의 `settings` 블록 내에서 `from_secret`을 사용하여 참조하며, 이 때 값은 시크릿의 이름입니다. 토큰 자체는 YAML에 절대로 나타나지 않습니다.
스크립트를 작성하지 않고도 CI에서 Apidog 테스트를 실행할 수 있습니까?
예. Apidog 앱에서 테스트 시나리오를 시각적으로 구축한 다음, 단일 `apidog run` 명령으로 CI에서 실행할 수 있습니다. Drone 단계는 Node 이미지, `npm install -g apidog-cli` 줄, 그리고 시나리오 및 환경 ID를 가리키는 실행 명령만 있으면 됩니다.