Artillery는 오픈 소스 Node.js 부하 테스트 툴킷으로, 간단한 YAML 스크립트로부터 API에 높은 동시성 트래픽을 발생시킵니다. 부하 단계(load phases)와 요청 흐름(request flows)을 정의하고, artillery run script.yml을 실행한 다음, 지연 시간 백분위수, 요청률 및 오류 수를 확인합니다. 이 가이드에서는 Artillery v2 설치, 실제 테스트 스크립트 작성, 실행, 현재 v2 방식으로 결과 캡처, 그리고 CI에 통합하는 방법을 안내합니다.
Artillery란 무엇이며 언제 사용해야 하는가
Artillery는 엔드포인트에 요청을 보내는 가상 사용자(VU)를 생성하고, 지속적인 트래픽 하에서 시스템이 어떻게 작동하는지 측정합니다. 가상 사용자는 실제 호출자와 마찬가지로 시나리오를 하나씩 실행하는 시뮬레이션된 클라이언트입니다.
확장성 문제에 대한 답을 얻어야 할 때 Artillery를 사용합니다. 초당 50개의 요청에서 p95 지연 시간은 어떻게 나타날까요? 어떤 유입률(arrival rate)에서 오류가 발생하기 시작할까요? API가 5분간 지속적인 부하에서 안정적으로 유지될까요, 아니면 성능이 저하될까요?
Artillery는 테스트가 선언적이기 때문에 이 작업에 능숙합니다. 동시성 루프를 직접 코딩하는 대신 YAML로 부하 형태를 정의합니다. Node.js가 실행되는 모든 곳에서 실행되므로 동일한 스크립트가 노트북과 CI에서 모두 작동합니다.
Artillery는 이 분야의 여러 옵션 중 하나입니다. 여전히 도구를 비교 중이라면, 최고의 부하 테스트 도구 총정리 및 이 부하 테스트 소프트웨어 비교에서 k6, JMeter, Gatling 등과의 장단점을 다루고 있습니다.
Artillery (v2) 설치
패키지 이름은 정확히 artillery이며, 현재 주요 버전은 v2입니다. npm을 사용하여 전역으로 설치한 다음, 버전을 확인하세요.
npm install -g artillery@latest
artillery version
최신 LTS 버전의 Node.js가 필요합니다. Artillery는 Windows, macOS, Linux에서 실행됩니다.
아무것도 전역으로 설치하고 싶지 않다면 npx로 필요할 때 실행할 수 있습니다.
npx artillery@latest run script.yml
Artillery 테스트 스크립트 작성
Artillery 테스트는 두 개의 최상위 섹션으로 구성된 YAML 파일입니다. config 섹션은 대상과 부하 프로필을 정의합니다. scenarios 섹션은 각 가상 사용자가 수행하는 작업을 정의합니다.
다음은 워밍업, 피크로 램프업, 그리고 지속적인 부하를 유지하는 전체 스크립트입니다.
config:
target: "https://api.example.com"
phases:
- name: "Warm up"
duration: 60
arrivalRate: 5
- name: "Ramp to peak"
duration: 120
arrivalRate: 5
rampTo: 50
- name: "Sustained load"
duration: 300
arrivalRate: 50
maxVusers: 500
# 인라인 변수 (또는 config.payload를 통해 CSV 사용)
variables:
productId:
- "1001"
- "1002"
scenarios:
- name: "Browse and create order"
flow:
- get:
url: "/v1/products/{{ productId }}"
- post:
url: "/v1/orders"
json:
productId: "{{ productId }}"
quantity: 2
config 섹션 이해하기
config.target은 모든 요청이 실행되는 기본 호스트입니다. 시나리오의 각 단계는 이 기본 주소에 url을 추가합니다.
config.phases는 순서대로 실행되는 부하 단계 배열입니다. 가장 많이 사용될 키는 다음과 같습니다:
duration: 단계 지속 시간(초 또는"5m"과 같은 사람이 읽을 수 있는 문자열).arrivalRate: 매초 시작되는 새로운 가상 사용자 수.rampTo: 단계 동안arrivalRate부터 이 값까지 유입률을 선형적으로 증가시킵니다.arrivalCount: 초당 비율 대신 단계에 걸쳐 분산되는 고정된 VU 수.maxVusers: 동시에 실행될 수 있는 가상 사용자 수의 상한선.name: 출력에 표시되는 레이블.
한 가지 주의할 점이 있습니다. 단계의 duration은 Artillery가 가상 사용자를 생성하는 기간을 제어하며, 테스트의 전체 경과 시간을 제어하는 것이 아닙니다. VU가 단계 종료 직전에 시작되고 해당 시나리오가 완료하는 데 시간이 걸리면, 해당 사용자가 완료될 때까지 실행은 계속됩니다.
scenarios 섹션 이해하기
scenarios는 배열입니다. 각 시나리오에는 가상 사용자가 실행하는 단계의 순서가 지정된 목록인 flow가 있습니다. 선택적 키에는 name과 weight가 있으며, weight는 Artillery가 특정 VU에 대해 이 시나리오를 선택할 상대적 확률을 설정합니다.
Flow 단계는 HTTP 동사 키(get, post, put, delete, patch)를 사용합니다. 각 키는 url을 가지며, 요청 본문은 json 아래에 있습니다. 이중 중괄호 구문({{ productId }})은 변수를 가져옵니다.
CSV 파일로부터 요청 구동하기
하드 코딩된 값은 스모크 테스트에는 괜찮습니다. 현실적인 부하를 위해 config.payload를 사용하여 CSV에서 데이터를 공급하세요. 각 가상 사용자는 한 행을 선택하고, 열 이름은 변수가 됩니다.
config:
target: "https://api.example.com"
payload:
path: "./users.csv"
fields:
- "email"
- "password"
phases:
- duration: 120
arrivalRate: 20
scenarios:
- flow:
- post:
url: "/login"
json:
email: "{{ email }}"
password: "{{ password }}"
테스트 실행
기본 명령은 Artillery가 스크립트를 가리키도록 합니다.
artillery run script.yml
# 스크립트를 편집하지 않고 대상을 재정의합니다:
artillery run --target https://staging.example.com script.yml
# 변수를 JSON으로 전달합니다:
artillery run -v '{ "productId": ["1001","1002"] }' script.yml
몇 가지 알아두면 좋은 플래그가 있습니다. --target (또는 -t)는 config.target을 재정의하여 동일한 스크립트를 스테이징 또는 프로덕션 환경에 연결할 수 있도록 합니다. --environment (또는 -e)는 config.environments 아래의 명명된 블록을 선택합니다. --config (또는 -c)는 별도의 파일에서 구성을 로드합니다. --insecure (또는 -k)는 테스트 환경에서 자체 서명된 인증서에 대한 TLS 확인을 건너뜁니다.
결과 읽기
테스트가 실행되는 동안 Artillery는 약 10초마다 집계된 메트릭을 출력합니다. 완료되면 요약 보고서를 얻을 수 있습니다. 가장 중요한 숫자는 다음과 같습니다.
- 요청률(Request rate): 실제로 달성된 초당 요청 수.
- 지연 시간 백분위수(Latency percentiles): p50(중앙값), p95, p99 응답 시간. p95는 가장 느린 5% 요청의 경험을 알려주며, 보통 여기서 문제가 처음 나타납니다.
- 오류 수(Error counts): 실패한 요청, 타임아웃, 2xx가 아닌 응답을 유형별로 그룹화합니다.
평균뿐만 아니라 꼬리 지연 시간(tail latencies)을 주시하세요. 평균은 건강해 보이지만 p99가 조용히 몇 초대로 상승할 수 있습니다. 지속 단계에서만 오류가 나타난다면, 조사할 가치가 있는 포화 지점을 찾았을 가능성이 높습니다. 추적해야 할 메트릭과 그 이유에 대한 더 깊이 있는 내용은 API 성능 테스트 가이드를 참조하세요.
Artillery v2에서 보고서 생성하기
보고 기능은 Artillery 버전마다 변경되었으므로, 오래된 튜토리얼은 잘못된 정보를 제공할 수 있습니다. 이전 가이드에서는 artillery run --output report.json을 실행한 다음 artillery report report.json을 실행하여 HTML 파일을 생성하라고 알려줍니다. 전반부는 여전히 작동하지만, 후반부는 그렇지 않습니다.
--output 플래그는 여전히 기계가 읽을 수 있는 JSON 결과 파일을 작성합니다.
# 기계가 읽을 수 있는 JSON 결과 작성 (여전히 지원됨):
artillery run --output report.json script.yml
JSON을 HTML로 변환하는 artillery report 명령은 Artillery CLI에서 제거되었습니다. 공식 문서에는 "더 이상 지원되지 않으며 Artillery CLI에서 제거되었다"고 명시되어 있습니다. HTML 보고 코드의 유지보수가 중단되었고, 더 이상 사용되지 않게 되었으며, 다시 가져올 계획이 없습니다. artillery report report.json을 사용하지 마십시오. 현재 v2에서는 작동하지 않습니다.
대신 세 가지 현재 옵션이 있습니다.
첫째, JSON을 직접 파싱합니다. 이는 임계값에 대해 검증해야 하는 CI에 이상적입니다. jq를 사용하여 집계된 p95 지연 시간을 가져옵니다.
jq '.aggregate.summaries["http.response_time"].p95' report.json
둘째, 호스팅된 대시보드를 위해 Artillery Cloud를 사용합니다. 이는 이전 HTML 보고서의 공식 대체품입니다. API 키와 함께 --record를 전달합니다.
artillery run --record --key $ARTILLERY_CLOUD_API_KEY script.yml
셋째, publish-metrics 플러그인 또는 OpenTelemetry를 사용하여 메트릭을 자체 모니터링 스택으로 푸시하여, 지연 시간 및 오류율이 프로덕션에서 이미 사용 중인 동일한 대시보드에 나타나도록 합니다.
CI에서 Artillery 실행
Artillery는 Node.js CLI일 뿐이므로 모든 파이프라인에 통합할 수 있습니다. 다음은 Artillery를 설치하고, 테스트를 실행하고, JSON 보고서를 빌드 아티팩트로 업로드하는 GitHub Actions 워크플로우입니다.
name: Load test
on: [workflow_dispatch]
jobs:
artillery:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "lts/*"
- run: npm install -g artillery@latest
- run: artillery run --output report.json script.yml
- uses: actions/upload-artifact@v4
with:
name: artillery-report
path: report.json
이 예제는 수동 디스패치로 실행됩니다. 대규모 부하 테스트는 몇 분이 소요되고 실제 대역폭을 소비하므로, 일반적으로 모든 커밋마다 실행되기보다는 필요할 때 또는 스케줄에 따라 트리거됩니다. JSON 보고서가 생성되면, p95가 예산을 초과할 경우 작업을 실패시키는 jq 단계를 추가할 수 있습니다.
Apidog의 역할: 기능 테스트 및 CI 게이팅
Artillery는 "API가 이 정도 트래픽을 견딜 수 있는가?"라는 질문에 답합니다. 이는 부하 및 성능 테스트입니다. 이와 함께 다른 질문도 있습니다: "이 코드 변경 후에도 API가 올바른 응답을 반환하는가?" 이는 기능 및 회귀 테스트이며, Apidog가 여기에 해당합니다.
Apidog는 설계, 디버깅, 목킹, 문서화 및 자동화 테스트를 위한 올인원 API 플랫폼입니다. 이 플랫폼의 테스트 시나리오는 if, for, foreach와 같은 조건으로 엔드포인트를 논리적인 단계로 그룹화하여 응답 본문, 상태 코드 및 계약을 검증할 수 있습니다. 코드 변경 후 병합을 막기 위해 CI에서 Apidog CLI로 이러한 시나리오를 실행합니다.
경계에 대해 명확하게 알아두세요. Apidog에는 성능 테스트 기능이 포함되어 있지만, 최대 100명의 가상 사용자로 제한됩니다. 이는 명백한 회귀를 발견하기에 충분하지만, 높은 동시성에서 Artillery를 대체할 수는 없습니다. 대규모 분산 코드 모델링 부하에는 Artillery가 적합한 도구입니다. 이와 동일한 솔직한 설명은 Python 없이 API 부하 테스트에 대한 글에 나와 있으며, Apidog의 100-VU 기능의 메커니즘은 Apidog에서의 API 성능 테스트에서 다룹니다.
따라서 두 가지 모두를 사용하세요. 규모를 위해서는 Artillery로 부하 테스트를 수행하세요. 코드 변경 후 문제가 배포되기 전에 발견하기 위해 Apidog CLI로 CI에서 기능 및 회귀 검사를 실행하세요.
Apidog CLI는 npm에서 설치되며, apidog run은 플래그만 사용합니다.
# Apidog CLI: CI에서 기능/회귀 실행 (플래그만, 위치 파일 없음)
npm install -g apidog-cli
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <TEST_SCENARIO_ID> \
-e <ENVIRONMENT_ID> \
-r cli,junit \
--out-dir ./apidog-reports
-t 플래그는 테스트 시나리오 ID이고, -e는 필수 환경 ID이며, -r cli,junit는 콘솔 출력과 CI 시스템이 읽을 수 있는 JUnit XML 보고서를 모두 출력합니다. 단계별 가이드는 Apidog CLI 튜토리얼을 참조하고, 파이프라인 설계 패턴은 API 테스트를 위한 CI/CD 모범 사례를 참조하세요.
Artillery 부하 실행과 함께 CI에서 기능 및 계약 테스트를 게이팅하고 싶으신가요? Apidog를 무료로 다운로드하고 첫 번째 테스트 시나리오를 구축해 보세요.
자주 묻는 질문
Artillery 부하 테스트란 무엇입니까?
Artillery 부하 테스트는 오픈 소스 Artillery 툴킷을 사용하여 API에 많은 동시 가상 사용자를 시뮬레이션하는 방식입니다. YAML 스크립트에 부하 형태와 요청 흐름을 정의하고, 이를 실행하며, 지연 시간 백분위수, 요청률 및 오류를 측정하여 시스템이 스트레스 하에서 어떻게 작동하는지 확인합니다.
Artillery는 무료이며 오픈 소스입니까?
예. 핵심 Artillery CLI는 artillery 패키지로 npm에 배포되는 무료 오픈 소스입니다. 결과 대시보드를 제공하는 유료 호스팅 서비스인 Artillery Cloud도 있지만, 이 서비스 없이도 로컬 및 CI에서 전체 부하 테스트를 실행할 수 있습니다.
Artillery 부하 테스트를 어떻게 실행합니까?
npm install -g artillery@latest로 설치하고, config 블록(대상 및 단계)과 scenarios 블록(요청 흐름)이 포함된 YAML 스크립트를 작성한 다음, artillery run script.yml을 실행합니다. Artillery는 10초마다 실시간 메트릭을 출력하고 마지막에 요약을 제공합니다.
Artillery 보고서는 어떻게 생성합니까?
artillery run --output report.json script.yml을 실행하여 JSON 결과 파일을 작성합니다. HTML을 생성했던 이전 artillery report 명령은 CLI에서 제거되었습니다. 대신 jq와 같은 도구로 JSON을 파싱하거나, --record --key를 통해 Artillery Cloud를 사용하거나, publish-metrics 또는 OpenTelemetry 플러그인으로 메트릭을 푸시합니다.
Artillery vs k6 또는 JMeter: 무엇을 사용해야 합니까?
세 가지 모두 대규모 부하를 처리할 수 있습니다. Artillery는 선언적 YAML과 Node.js를 사용하며, 이는 이미 JavaScript 생태계에 있는 팀에 적합합니다. k6는 코드 우선 모델로 JavaScript로 스크립트를 작성합니다. JMeter는 GUI 기반이며 Java 기반으로 오랜 플러그인 역사를 가지고 있습니다. Gatling vs JMeter 비교에서 장단점을 더 자세히 다룹니다. 팀의 스크립팅 모델에 맞는 것을 선택한 다음, 완벽한 커버리지를 위해 기능 CI 테스트와 결합하세요.