Artilleryは、シンプルなYAMLスクリプトからAPIに高並行性トラフィックを生成するオープンソースのNode.jsロードテストツールキットです。ロードフェーズとリクエストフローを定義し、artillery run script.ymlを実行すると、レイテンシのパーセンタイル、リクエストレート、エラーカウントが読み取れます。このガイドでは、Artillery v2のインストール、実際のテストスクリプトの作成、実行、現在のv2方式での結果の取得、およびCIへの組み込みについて説明します。
Artilleryとは何か、そしていつ活用すべきか
Artilleryは、エンドポイントにアクセスする仮想ユーザー（VU）を生成し、システムが持続的なトラフィックの下でどのように耐えるかを測定します。仮想ユーザーは、実際の呼び出し元と同じように、シナリオを次々とリクエストを実行するシミュレートされたクライアントです。
スケーリングに関する疑問の答えが必要なときにArtilleryを活用します。p95レイテンシは1秒あたり50リクエストでどのように動作しますか？どのような到着率でエラーが出始めますか？APIは5分間の持続的な負荷に対して安定した状態を保ちますか、それとも劣化しますか？
Artilleryは、テストが宣言的であるため、この点に優れています。並行性ループを手動でコーディングする代わりに、YAMLで負荷の形状を記述します。Node.jsが動作する場所ならどこでも実行できるため、同じスクリプトがラップトップでもCIでも動作します。
Artilleryはこの分野でいくつかの選択肢の一つです。まだツールを比較している場合は、主要なロードテストツールまとめとこのロードテストソフトウェア比較が、k6、JMeter、Gatlingなどのトレードオフを網羅しています。
Artillery (v2) のインストール
パッケージ名は正確にはartilleryで、現在のメジャーバージョンはv2です。npmでグローバルにインストールし、バージョンを確認してください。
npm install -g artillery@latest
artillery version
Node.jsの最新のLTSリリースが必要です。ArtilleryはWindows、macOS、Linuxで動作します。
グローバルに何もインストールしたくない場合は、npxでオンデマンドで実行してください。
npx artillery@latest run script.yml
Artilleryテストスクリプトの作成
Artilleryテストは、2つのトップレベルセクションを持つ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
# Inline variables (or use a CSV via config.payload)
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: 1秒あたりに開始する新しい仮想ユーザーの数。rampTo: このフェーズ全体で、到着率をarrivalRateからこの値まで線形に引き上げます。arrivalCount: 1秒あたりのレートではなく、フェーズ全体に分散された固定数のVU。maxVusers: 同時に実行できる仮想ユーザーの数の上限。name: 出力に表示されるラベル。
一つ注意すべき詳細があります。フェーズのdurationは、Artilleryが仮想ユーザーを生成し続ける時間を制御するものであり、テストの総実時間ではありません。フェーズの終わりに近い時点でVUが開始され、そのシナリオに時間がかかる場合、そのユーザーが完了するまで実行は継続されます。
scenariosセクションの理解
scenariosは配列です。各シナリオにはflowがあり、これは仮想ユーザーが実行するステップの順序付けられたリストです。オプションのキーにはnameとweightがあり、weightは指定されたVUに対してArtilleryがこのシナリオを選択する相対的な確率を設定します。
フローのステップでは、HTTP動詞のキー（get、post、put、delete、patch）を使用します。それぞれurlを取り、リクエストボディはjsonの下に記述します。二重中括弧の構文{{ productId }}は変数を引き込みます。
CSVファイルからのリクエストの駆動
スモークテストでは値をハードコーディングしても問題ありません。現実的な負荷のためには、config.payloadを使用してCSVからデータを供給します。各仮想ユーザーは1行を選択し、列名が変数になります。
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
# Override target without editing the script:
artillery run --target https://staging.example.com script.yml
# Pass variables as JSON:
artillery run -v '{ "productId": ["1001","1002"] }' script.yml
いくつかの重要なフラグがあります。--target (または-t) はconfig.targetを上書きするため、同じスクリプトをステージング環境や本番環境に向けられます。--environment (または-e) はconfig.environmentsの下の名前付きブロックを選択します。--config (または-c) は別のファイルから設定を読み込みます。--insecure (または-k) は、テスト環境における自己署名証明書のTLS検証をスキップします。
結果の読み取り
テストの実行中、Artilleryは約10秒ごとに集計メトリクスを出力します。完了すると、サマリーレポートが表示されます。最も重要な数値は次のとおりです。
- リクエストレート: 実行で実際に達成された1秒あたりのリクエスト数。
- レイテンシのパーセンタイル: p50（中央値）、p95、およびp99の応答時間。p95は、通常、問題が最初に現れる最も遅い5パーセントのリクエストの体験を示します。
- エラーカウント: 失敗したリクエスト、タイムアウト、および2xx以外の応答をタイプ別にグループ化したもの。
平均値だけでなく、テールレイテンシにも注意してください。平均値は健全に見えても、p99が静かに数秒の領域に達している場合があります。持続フェーズ中にのみエラーが発生する場合、調査する価値のある飽和点を発見した可能性が高いです。どのメトリクスを追跡すべきか、そしてその理由について深く知りたい場合は、このAPIパフォーマンステストガイドを参照してください。
Artillery v2でのレポート生成
レポート機能はArtilleryのバージョン間で変更されたため、古いチュートリアルでは誤った情報に導かれる可能性があります。古いガイドでは、HTMLファイルを生成するためにartillery run --output report.jsonを実行し、次にartillery report report.jsonを実行するように指示されています。前半はまだ機能しますが、後半は機能しません。
--outputフラグは引き続き、機械で読み取り可能なJSON結果ファイルを書き込みます。
# 機械で読み取り可能なJSON結果を書き込みます（引き続きサポートされています）：
artillery run --output report.json script.yml
JSONからHTMLを生成するartillery reportコマンドは、Artillery CLIから削除されました。公式ドキュメントには「もはやサポートされておらず、Artillery CLIから削除された」と記載されています。HTMLレポートのコードはメンテナンスされなくなり、非推奨となり、その後削除され、復活させる計画はありません。artillery report report.jsonと記述しないでください。現在のv2では動作しません。
代わりに、現在3つの選択肢があります。
まず、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
3番目に、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などの条件でエンドポイントを論理的なステップにグループ化するため、レスポンスボディ、ステータスコード、および契約を検証できます。コード変更後のマージをゲートするために、Apidog CLIを使用してCIでこれらのシナリオを実行します。
境界を明確にしてください。Apidogにはパフォーマンステスト機能が含まれていますが、最大100仮想ユーザーに制限されています。これは明らかな回帰を発見するのに十分ですが、高並行性におけるArtilleryの代替品ではありません。大規模な分散型コードモデルの負荷には、Artilleryが適切なツールです。PythonなしでのAPIロードテストに関する私たちの記事でも同様の正直な説明がされており、Apidogの100-VU機能のメカニズムはApidogでのAPIパフォーマンステストで説明されています。
したがって、両方を活用してください。Artilleryで大規模なロードテストを行い、Apidog CLIでCIで機能チェックと回帰チェックを実行し、問題のある動作が出荷される前に発見します。
Apidog CLIはnpmからインストールされ、apidog runはフラグのみです。
# Apidog CLI: functional/regression run in CI (flag-only, no positional file)
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は無料でオープンソースであり、npmでartilleryパッケージとして配布されています。結果用のダッシュボードを提供する有料のホスト型サービスである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：どちらを使用すべきですか？
これら3つすべてが大規模な負荷を処理できます。Artilleryは宣言型YAMLとNode.jsを使用するため、すでにJavaScriptエコシステムにいるチームに適しています。k6はコードファーストモデルでJavaScriptでスクリプトを作成します。JMeterはGUI駆動型でJavaベースであり、長いプラグインの歴史があります。Gatling vs JMeterの比較では、トレードオフについてより深く説明されています。あなたのチームのスクリプトモデルに合ったものを選び、その後、完全なカバレッジのために機能的なCIテストと組み合わせてください。