CircleCI에서 Apidog CLI API 테스트를 실행하려면 cimg/node Docker 실행기를 사용하는 .circleci/config.yml 파일을 추가하고, npm으로 apidog-cli를 설치한 다음, 액세스 토큰, 테스트 시나리오 ID, 환경 ID를 사용하여 apidog run을 실행합니다. 토큰과 ID는 CircleCI 환경 변수로 저장하고, store_test_results 및 store_artifacts를 사용하여 JUnit 및 HTML 보고서를 발행합니다. 이 가이드는 각 부분을 단계별로 안내하므로, 복사, 붙여넣기 후 바로 적용할 수 있습니다.
이 문서는 테스트 실행에 관한 것이며, CI 플랫폼 선택에 관한 것이 아닙니다. 여전히 도구 선택을 고민 중이라면, CircleCI vs Jenkins 비교 문서가 도움이 될 것입니다. 여기서는 이미 CircleCI를 선택했고, 푸시할 때마다 API 스위트를 실행하고 싶다고 가정합니다.
CircleCI란 무엇이며 어떻게 작동하는가
CircleCI는 클라우드 기반의 지속적 통합(Continuous Integration) 및 배포(Delivery) 서비스입니다. Git 저장소를 감시하며, 커밋을 푸시할 때마다 정의된 빌드, 테스트, 배포 단계를 실행합니다. 이러한 단계는 단일 YAML 파일에 설명되어 있으므로, 파이프라인은 코드와 함께 버전 제어됩니다.
모든 것은 저장소 루트의 .circleci/config.yml 파일에서 시작됩니다. CircleCI는 푸시할 때마다 이 파일을 읽고 파이프라인으로 전환합니다. 현재 구성 형식은 버전 2.1이며, 기본 2.0 엔진 위에 orb, 명령, 매개변수와 같은 재사용 가능한 구성 요소를 추가합니다.
CircleCI 구성에는 세 가지 핵심 개념이 있습니다:
- 작업(Jobs)은 작업의 단위입니다. 각 작업은 코드 체크아웃, 종속성 설치, 테스트 명령 실행과 같은 일련의 단계(steps)를 실행합니다.
- 실행기(Executors)는 작업이 실행될 위치를 정의합니다. Docker 실행기는 Node.js 프로젝트의
cimg/node와 같이 선택한 컨테이너 이미지 내에서 단계를 실행합니다. - 워크플로(Workflows)는 작업을 조율합니다. 워크플로는 어떤 작업을 어떤 순서로 실행할지, 병렬로 실행할지 순차적으로 실행할지를 결정합니다.
이러한 구분은 API 테스트에 중요합니다. Apidog CLI를 설치하고 시나리오를 실행하는 하나의 작업을 정의한 다음, 관심 있는 브랜치에서 해당 작업을 트리거하는 워크플로를 정의합니다.
왜 CircleCI에서 API 테스트를 실행해야 하는가
CI에서 API 스위트를 실행하면 프로덕션에 도달하기 전에 계약 위반을 발견할 수 있습니다. 스키마 변경, 필드 이름 변경 또는 손상된 인증 흐름은 지원 티켓 대신 빨간색 빌드로 나타납니다.
Apidog CLI는 바로 이를 위해 제작되었습니다. Apidog 앱에서 테스트 시나리오를 설계하고 디버그한 다음, 동일한 시나리오를 CI에서 하나의 명령으로 헤드리스로 실행합니다. 코드로 어설션을 다시 작성할 필요가 없으며, 별도의 테스트 하네스를 유지 관리할 필요도 없습니다.
자동화된 검사가 파이프라인에 어떻게 통합되는지에 대한 더 넓은 그림을 원한다면, API 테스트를 위한 12가지 CI/CD 모범 사례 가이드가 좋은 보충 자료입니다.
전제 조건
구성을 작성하기 전에 Apidog 앱에서 다음을 준비하십시오:
- 액세스 토큰입니다. Apidog 계정 설정에서 생성합니다. 이는 헤드리스 환경에서 CLI를 인증합니다. Apidog CLI 인증 가이드는 토큰 생성 및 CI 시크릿 처리 방법을 자세히 다룹니다.
- 테스트 시나리오 ID입니다. 실행하려는 테스트 시나리오를 열고 URL 또는 시나리오 설정에서 ID를 복사합니다.
- 환경 ID입니다. 이는 CLI에 스테이징 또는 프로덕션과 같은 어떤 기본 URL 및 변수를 사용할지 알려줍니다.
또한, CircleCI 대시보드에서 프로젝트가 활성화된 Git 공급자와 연결된 CircleCI 계정이 필요합니다.
비밀을 환경 변수로 저장
config.yml에 액세스 토큰을 절대 하드코딩하지 마십시오. 파일은 Git에 커밋되므로, 거기에 토큰이 있으면 토큰이 유출됩니다.
CircleCI는 두 가지 안전한 옵션을 제공합니다:
- 프로젝트 환경 변수입니다. CircleCI UI에서 프로젝트 설정, 환경 변수를 열고 각 값을 추가합니다. 이들은 암호화되어 작업에
$VARS로 노출됩니다. - 컨텍스트(Contexts)입니다. 컨텍스트는 프로젝트 간에 공유되는 명명된 환경 변수 그룹입니다. 조직 설정, 컨텍스트에서 생성하고 워크플로에서 참조합니다. 컨텍스트는 여러 저장소가 동일한 Apidog 토큰을 공유할 때 유용합니다.
이 가이드에서는 APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID, APIDOG_ENVIRONMENT_ID 세 가지 변수를 추가합니다. CLI는 런타임에 이들을 읽으며, 중요한 정보는 저장소에 남지 않습니다.
전체 config.yml
다음은 복사하여 붙여넣을 수 있는 전체 구성입니다. .circleci/config.yml에 배치하고, 세 가지 환경 변수를 설정한 다음, 푸시하십시오.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
각 부분이 무엇을 하는지 살펴보겠습니다.
실행기
docker:
- image: cimg/node:20.11
cimg/node는 Node.js용 CircleCI 편의 이미지입니다. Node, npm, 일반적인 빌드 도구가 사전 설치되어 있어, 추가 설정 없이 npm install -g apidog-cli가 작동합니다. :20.11 태그는 Node 버전을 고정합니다. 팀에서 표준화한 버전으로 고정하십시오.
단계
checkout은 저장소를 작업 디렉토리로 가져옵니다. 첫 번째 run 단계는 CLI를 전역으로 설치합니다. 두 번째 run 단계는 테스트를 실행합니다.
테스트 명령을 자세히 살펴보십시오:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
각 플래그는 하나의 작업을 수행합니다:
--access-token은 실행을 인증합니다. 약식은 없습니다.-t는 ID로 테스트 시나리오를 선택합니다.-e는 환경을 선택합니다. 이 플래그는 필수입니다. CLI는 사용할 기본 URL 및 변수를 알아야 합니다.-r은 리포터(reporters)를 설정합니다. 여기서는 세 가지를 요청합니다:cli는 빌드 로그에 실시간 결과를 출력하고,junit는 기계 판독 가능한 XML을 작성하며,html은 브라우저에서 볼 수 있는 보고서를 작성합니다.--out-dir은 CLI가 보고서 파일을 작성할 위치를 알려줍니다.
보고서 발행
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results는 CircleCI가 ./reports의 JUnit XML을 가리키도록 합니다. CircleCI는 이를 파싱하고 빌드에 테스트 탭을 표시하여, 실패가 타이밍 데이터와 함께 이름으로 나열됩니다. 이는 많은 로그 텍스트를 구조화된 통과/실패 보기로 전환하는 것입니다.
store_artifacts는 HTML 보고서를 포함하여 동일한 디렉토리를 다운로드 가능한 파일로 업로드합니다. 빌드 후, 아티팩트 탭을 열고 브라우저에서 렌더링된 보고서를 볼 수 있습니다. Apidog CLI 테스트 보고서 가이드는 CLI, HTML, JSON 형식을 더 자세히 설명합니다.
워크플로
workflows:
test-api:
jobs:
- api-tests
이 워크플로는 푸시할 때마다 api-tests 작업을 실행합니다. 특정 브랜치로 제한하는 필터를 추가하거나, 그 전에 또는 후에 실행되는 다른 작업을 추가할 수 있습니다. 단일 테스트 작업의 경우, 이 최소 블록이면 충분합니다.
main 브랜치에서만 테스트 실행
모든 기능 브랜치에서 전체 API 실행을 원하지 않을 수도 있습니다. 워크플로에 브랜치 필터를 추가합니다:
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
이제 이 작업은 main 및 develop으로 푸시할 때만 실행됩니다. 다른 브랜치는 건너뛰어, 빌드 시간을 중요한 브랜치에 집중할 수 있습니다.
프로젝트 변수 대신 컨텍스트 사용
여러 저장소가 하나의 Apidog 토큰을 공유하는 경우, 컨텍스트는 이를 한 곳에 유지합니다. 조직 설정에서 컨텍스트를 생성하고, 거기에 변수를 추가한 다음, 이를 참조합니다:
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
이제 작업은 apidog-secrets 컨텍스트에서 APIDOG_ACCESS_TOKEN 및 나머지를 읽습니다. 토큰을 한 번만 변경하면, 모든 프로젝트가 새 값을 가져옵니다.
데이터 기반 실행 및 기타 옵션
CLI에는 이 가이드에서 사용된 것보다 더 많은 플래그가 있습니다. CI에 알아둘 가치가 있는 두 가지가 있습니다.
-d 및 -n을 사용하여 테스트 데이터 행 전체에서 시나리오를 반복할 수 있습니다:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
-d 플래그는 CSV 또는 JSON 파일 경로, 또는 숫자 저장 데이터 세트 ID를 사용하여 행당 한 번씩 시나리오를 실행합니다. 데이터 기반 테스트 가이드는 이러한 파일의 구조를 보여줍니다.
또한, continue, end, ignore를 허용하는 --on-error를 사용하여 실행이 실패를 처리하는 방식을 제어할 수 있습니다. Apidog 브랜치를 사용하는 프로젝트의 경우, --project <id> --branch <name>은 특정 브랜치를 대상으로 합니다. Apidog 클라우드에 보고서 개요를 푸시하려면, --upload-report를 단일 플래그로 추가하십시오.
이것이 Apidog 워크플로에 어떻게 맞는가
Apidog CLI의 요점은 테스트 코드를 작성하거나 유지 관리할 필요가 없다는 것입니다. 명령줄이나 시각적 테스트 빌더에서 테스트 시나리오를 구축하고, 상태 코드 및 응답 본문에 대한 어설션을 설정하고 저장합니다. 그런 다음 CI가 해당 시나리오를 정확하게 실행합니다.
시나리오가 Apidog 프로젝트에 존재하므로, 팀은 한 곳에서 테스트를 편집할 수 있습니다. CI 구성은 거의 변경되지 않으며, 단순히 apidog run을 호출합니다. 누군가 앱에서 어설션을 추가하면, 다음 CircleCI 빌드는 YAML 편집 없이 이를 반영합니다.
이는 깨끗한 분할을 유지합니다. Apidog는 테스트되는 것을 소유합니다. CircleCI는 언제 어디서 실행되는지를 소유합니다. 이러한 종류의 작업에 대해 CircleCI를 다른 러너와 비교하고 싶다면, API 팀을 위한 지속적 통합 도구 요약이 장단점을 설명합니다.
모든 푸시에서 API 스위트를 실행할 준비가 되셨습니까? Apidog를 다운로드하고, 테스트 시나리오를 구축하고, 위의 구성을 저장소에 추가하십시오.
자주 묻는 질문
CircleCI란 무엇입니까?
CircleCI는 클라우드 기반의 지속적 통합 및 배포 플랫폼입니다. Git 저장소에 연결하고, .circleci/config.yml 파일을 읽고, 코드를 푸시할 때마다 빌드, 테스트, 배포 단계를 자동으로 실행합니다. 이는 사용자 컴퓨터에서 이러한 단계를 수동으로 실행할 필요를 없애줍니다.
CircleCI는 무엇에 사용됩니까?
팀은 CircleCI를 사용하여 테스트 및 배포를 자동화합니다. 일반적인 작업에는 코드 컴파일, 단위 및 통합 테스트 실행, API 계약 확인, Docker 이미지 빌드, 스테이징 또는 프로덕션으로 릴리스 배포 등이 포함됩니다. 이 가이드에서는 푸시할 때마다 Apidog CLI API 테스트를 실행하는 작업을 다룹니다.
CircleCI는 무료입니까?
CircleCI는 매월 할당된 빌드 크레딧이 포함된 무료 플랜을 제공하며, 이는 소규모 프로젝트 및 개인 저장소에 충분합니다. 더 많은 동시성, 더 긴 빌드 시간 또는 더 큰 머신이 필요한 대규모 팀은 유료 Performance 및 Scale 플랜으로 전환합니다. 정확한 제한 사항은 CircleCI의 현재 가격 페이지를 확인하십시오.
CircleCI는 오픈 소스입니까?
아니요, CircleCI는 오픈 소스가 아닌 상용 호스팅 제품입니다. YAML 파일을 통해 구성하고 CircleCI 인프라 또는 자체 호스팅 러너에서 실행합니다. 완전히 오픈 소스 CI 서버가 필요하다면, Jenkins가 일반적인 대안이며, 이는 CircleCI vs Jenkins 비교에서 논의됩니다.
CircleCI는 어떻게 작동합니까?
커밋을 푸시하면 CircleCI는 변경 사항을 감지하고, .circleci/config.yml을 읽고, cimg/node Docker 컨테이너와 같이 정의된 실행기를 시작합니다. 작업의 각 단계를 순서대로 실행한 다음, Git 공급자에게 결과를 보고합니다. 워크플로는 작업을 연결하고 병렬화할 수 있도록 합니다. 이것이 배포 파이프라인에 어떻게 통합되는지에 대한 더 큰 그림을 보려면, CI/CD란 무엇인가 가이드를 참조하십시오.