CI/CDタブからコマンドをコピーしてパイプラインに貼り付けたら、それが機能しました。しかし、同僚から「テストが明らかに失敗したのにビルドがまだグリーンになるのはなぜですか？」、「同じ実行を本番環境ではなくステージング環境に向けられますか？」、「CIダッシュボードが実際にパースするレポートを取得するにはどうすればいいですか？」といった質問が来ます。突然、一行のコマンドだけでは不十分になります。コマンドのすべての部分が何をするのかを知る必要があるのです。
apidog runは、Apidogコマンドラインランナーの中核をなす単一のコマンドです。Apidogで作成したAPIテストシナリオを、GUIや人間のボタンクリックなしで、ターミナルからヘッドレスで実行します。ランナーができるすべてのことは、この単一のコマンドのフラグを通じて行われます。実行するシナリオ、ターゲットとする環境、ループ回数、出力するレポート、そして失敗と見なす条件などです。一度フラグの表面を学べば、盲目的にコピー＆ペーストするのをやめることができます。
apidog runとは
Apidog CLIは、apidog-cliというnpmパッケージとして提供されます。一度インストールすると、単一のバイナリapidogが手に入り、その主要なサブコマンドがrunです。このサブコマンドは、Apidogのテストシナリオの1つを受け取り、デスクトップアプリが実行するのと同じ方法で実行し、終了コードと要求されたレポートファイルで結果を返します。
グローバルにインストールします:
npm install -g apidog-cli
解決されたことを確認します:
apidog -v
フラグの前に理解すべきことは、apidog runが何に基づいて動作するかです。それは独自のテスト形式を定義しません。テストはApidogアプリで作成したシナリオです。つまり、連鎖したリクエスト、アサーション、あるレスポンスから次のレスポンスへ引き出される値、オプションのデータ駆動型イテレーションです。CLIはプロジェクトにアクセスし、IDによってシナリオを見つけて実行します。したがって、ほとんどのフラグは、インラインでテストを作成することではなく、ランナーが何をフェッチし、実行中にどのように動作するかを伝えるためのものです。
最小限の実際のコマンドは次のようになります:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
これは、「このトークンで認証し、テストシナリオ605067を、環境1629989に対して1回実行し、HTMLレポートと読みやすいターミナル出力を生成する」という意味です。この行のすべてのフラグは以下で説明されており、このコマンドで省略されているフラグも含まれています。
オプションの全貌
ジョブごとにグループ化されたオプションの完全なセットを以下に示します。これをルックアップテーブルとして使用してください。この後に続くセクションでは、1文以上を必要とするオプションについて説明します。
| グループ | フラグ | 引数 | 制御するもの |
|---|---|---|---|
| 選択 | -t, --test-scenario |
<testScenarioId> |
IDで単一のシナリオを実行する |
| 選択 | -f, --test-scenario-folder |
<folderId> |
フォルダ内のすべてのシナリオを実行する |
| 選択 | --test-suite |
<testSuiteId> |
IDでテストスイートを実行する |
| 選択 | --project |
<projectId> |
シナリオが属するプロジェクト |
| 選択 | --branch |
<branchName> |
ブランチに対して実行する（デフォルトはmain） |
| 認証 | --access-token |
<accessToken> |
実行を認証する（オンラインで必須） |
| 環境 | -e, --environment |
<environmentId> |
ターゲットとする環境 |
| 反復 | -n, --iteration-count |
<n> |
シナリオをn回実行する |
| 反復 | -d, --iteration-data |
<path> |
JSONまたはCSVファイルから反復を駆動する |
| 反復 | --variables |
<path> |
ローカルファイルから変数を読み込む |
| 反復 | --global-var |
<value> |
グローバル変数をインラインで設定する（key=value） |
| 反復 | --env-var |
<value> |
環境変数をインラインで上書きする（key=value） |
| レポート | -r, --reporters |
[reporters] |
レポート形式: cli, html, json, junit |
| レポート | --out-dir |
<outDir> |
レポートが書き込まれる場所 |
| レポート | --out-file |
<outFile> |
レポートのファイル名（名前のプレースホルダーを使用） |
| レポート | --out-json-failures-separated |
<value> |
失敗を別のJSONファイルに書き出す |
| レポート | --upload-report |
[value] |
Apidogクラウドにレポートの概要をアップロードする |
| エラー | --on-error |
<behavior> |
失敗時の動作: ignore, continue, または end |
| エラー | --ignore-redirects |
HTTPリダイレクトを追跡しない | |
| エラー | --delay-request |
[n] |
リクエスト間にnミリ秒待機する |
| エラー | --timeout-request |
[n] |
リクエストごとのタイムアウト（ミリ秒） |
| エラー | --timeout-script |
[n] |
スクリプト実行のタイムアウト（ミリ秒） |
| TLS | -k, --insecure |
SSL証明書の検証を無効にする | |
| TLS | --ssl-client-cert |
<path> |
クライアント証明書（PEM） |
| TLS | --ssl-client-key |
<path> |
クライアント証明書の秘密鍵 |
| TLS | --ssl-client-passphrase |
<passphrase> |
クライアント証明書のパスフレーズ |
| TLS | --ssl-client-cert-list |
<path> |
証明書とホストをマッピングする設定 |
| TLS | --ssl-extra-ca-certs |
<path> |
追加の信頼されたCA証明書 |
| 出力 | --verbose |
完全なリクエストとレスポンスの詳細を出力する | |
| 出力 | --silent |
コンソール出力を抑制する | |
| 出力 | --color |
<value> |
カラー出力を強制的に有効または無効にする |
| 出力 | --external-program-path |
<path> |
カスタムロジック用の外部プログラムファイル |
| 出力 | --database-connection |
<path> |
DBをクエリするステップ用のデータベース設定 |
| 出力 | --preferred-http-version |
<version> |
推奨されるHTTPプロトコルバージョン |
| 出力 | -b, --bigint |
大きな数値のBigIntを有効にする | |
| 出力 | --lang |
<language> |
CLIの言語 |
| 出力 | -h, --help |
ヘルプテキストを出力する |
フラグ名とデフォルト値はCLIのリリース間で変更される可能性があります。疑問がある場合は、ランナー自体が真実の源です。インストールされているバージョンでapidog run --helpを実行し、この記事を含む他のどの記事よりもそちらを信頼してください。
実行する内容の選択
実行のスコープを決定する3つのフラグがあり、コマンドごとにそのうち1つだけを選択します。
-t, --test-scenario <id>は、単一のシナリオを実行します。これは日常的なケースで、特定の煙テスト、特定のリグレッションシナリオ、プルリクエストでゲートしたい1つのものです。
-f, --test-scenario-folder <id>は、フォルダ内のすべてのシナリオを実行します。機能領域をフォルダに整理し、夜間のリグレッションスイープのようにグループ全体を1つのジョブとして実行したい場合にこれを使用します。
--test-suite <id>は、厳選されたテストスイートを実行します。これは、論理的な単一の単位としてまとめて実行するために集められた一連のシナリオです。テストしたいシナリオがすべて同じフォルダにはないが、同じテストパスに属する場合、スイートが適切なツールとなります。
さらに2つのセレクタが、ランナーがどこを探すかを絞り込みます。--project <id>はシナリオが存在するプロジェクトを指定します。これは、トークンが複数のプロジェクトへのアクセス権を持っている場合に便利です。--branch <name>は、mainではなく特定のブランチに存在するシナリオを実行するため、マージする前に機能ブランチでテストの変更を検証できます。
# 1つのシナリオ
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
# フォルダ全体
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit
# 厳選されたスイート
apidog run --access-token $APIDOG_ACCESS_TOKEN --test-suite 40231 -r junit
実行の認証
--access-token <token>は、すべてのオンライン実行に必要な唯一のフラグです。これにより、実行がシナリオをフェッチして実行することを許可されていることが証明されます。トークンはApidogのテストシナリオのCI/CDタブ内で生成され、アプリはシナリオIDと環境IDがすでに埋め込まれた完全なapidog runコマンドも作成します。
トークンはパスワードのように扱ってください。コミットされたパイプラインファイルや共有スクリプトに貼り付けないでください。CIシステムにシークレットとして保存し、環境変数を通じて渡してください。そのため、ここのすべての例では、リテラル文字列ではなく$APIDOG_ACCESS_TOKENを参照しています。トークンが漏洩した場合は、同じCI/CDタブから再生成すると、古いトークンは機能しなくなります。
環境のターゲット設定と反復
環境フラグにより、1つのシナリオで多くの目的を達成できます。-e, --environment <id>は、実行を特定の環境に向けます。これにより、同じシナリオをプルリクエストのゲートでステージング環境をチェックしたり、デプロイ後の煙テストで本番環境をチェックしたりすることができます。何も重複させる必要はありません。環境間で値を管理する場合、APIクライアントの環境とシークレット管理に関するガイドでは、それらの値の流れについて説明しています。
-n, --iteration-count <n>は、シナリオをn回連続して実行します。迅速な安定性チェックや、冪等であるべきフローを繰り返すのに役立ちます。
-d, --iteration-data <path>はデータ駆動型フラグです。これをJSONまたはCSVファイルに向け、ランナーは各行を独自の入力値を持つ独自のパスとして扱い、シナリオを各行ごとに1回実行します。これは、50のアカウントに対して1つのログインシナリオを実行したり、ペイロードのテーブルに対して1つの注文作成フローを実行したりする方法です。より詳細なパターンは、CSVおよびJSONを使用したデータ駆動型APIテストに記載されています。
3つのフラグは、シナリオを編集せずに値を挿入します。--variables <path>はローカルファイルから変数を読み込みます。--global-var key=valueはグローバル変数をインラインで設定します。--env-var key=valueは、この実行のみに適用される単一の環境変数を上書きします。これらのフラグは、値（ベースURL、機能フラグなど）がパイプラインごとに異なり、それぞれのパイプラインに個別の環境を設定したくない場合にCIで役立ちます。Apidogの変数が初めての場合は、Apidogでの変数の習得でスコープについて説明しています。
# CSVの入力に対してシナリオを50回実行
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r junit
# この実行のみ1つの環境変数を上書き
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 --env-var baseUrl=https://staging.internal -r cli
レポーター: apidog runが生成できるすべての出力形式
これは人々が最も検索するグループなので、各レポーターとその目的をここに示します。これらは-r, --reportersで選択し、複数同時にカンマ区切りで渡すことができます。デフォルトはcliです。
cliは、読みやすい要約をターミナルに出力します。これは、ビルドログで人間が合格/失敗の数やどのアサーションが壊れたかを確認するためにスキャンするものです。ログを役立つものにするために、機械形式と併用してもcliをオンにしておいてください。
htmlは、自己完結型のHTMLレポートを書き出します。これをビルドアーティファクトとしてアーカイブし、ブラウザで開いて、リクエストとレスポンスの詳細を含む完全な実行結果を確認できます。これは、パイプラインを見ていなかった人に渡すための形式です。
junitは、標準のJUnit形式でXMLを出力します。ほぼすべてのCIダッシュボードは、JUnit XMLをパースして合格/失敗ツリーを作成したり、マージリクエストウィジェットに失敗を表示したり、時間の経過とともに結果をトレンド表示したりする方法を知っています。CI向けに1つの機械形式だけを選択するなら、これを選んでください。
jsonは、生の構造化された結果を生成します。自分で結果を後処理したい場合（スクリプトにフィードしたり、メトリクスをどこかにプッシュしたり、カスタムサマリーを作成したりする場合）にこれを使用します。
一般的なCIの組み合わせは、人間向けのHTMLとダッシュボード向けのJUnitです:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -r html,junit --out-dir ./apidog-reports
残りのレポートフラグは、出力の保存場所と追加で含まれる内容を制御します:
--out-dir <dir>は、レポートが書き込まれるディレクトリを設定します。デフォルトは./apidog-reportsです。--out-file <name>は、レポートのファイル名を設定し、プレースホルダー{FOLDER_NAME}、{SCENARIO_NAME}、{GENERATE_TIME}を受け入れます。これにより、実行ごとに1つのファイルを上書きするのではなく、シナリオ名とタイムスタンプでファイルに印を付けることができます。--out-json-failures-separated <value>は、失敗を独自のJSONファイルに分割し、失敗のみの差分を読みやすくします。--upload-report [value]は、レポートの概要をApidogクラウドにアップロードし、ローカルファイルと並行してプロジェクトの履歴に実行結果が表示されるようにします。
失敗の制御: エラー処理と終了コード
テストが合格したかどうかをパイプラインに伝える場合にのみ、ランナーはパイプラインで役立ちます。apidog runは、行儀の良いコマンドラインツールが行う方法でこれを行います。すべてのアサーションが合格した場合は0で終了し、何かが失敗した場合は非ゼロのコードで終了します。この単一の動作が品質ゲートのすべてです。CIは終了コードを読み取り、ステップを失敗とマークし、マージまたはデプロイをブロックします。ゲートを設定する必要はありません。終了コードがゲートです。
--on-error <behavior>は、シナリオの途中でステップが失敗した場合の動作を決定し、3つの値があります:
endは、最初の失敗したステップで実行を停止します。何かが壊れた瞬間にフィードバックが欲しい高速失敗の煙テストに使用します。continueは、残りのすべてのステップを実行し、1つのレポートですべての失敗を収集します。一度にすべての障害を確認することでラウンドトリップを節約したいリグレッションスイープに使用します。ignoreは、既知の不安定なステップを致命的と扱わずに実行を続行させます。これは慎重に使用してください。無視されたステップが実際のリグレッションを隠しているべきではありません。
いずれにしても、アサーションが失敗した場合は、実行は非ゼロで終了するため、選択した動作に関係なくゲートは保持されます。ゲートを静かに壊す1つのこと: シェルで|| trueを付加するなど、コマンドの終了コードを飲み込むような形でコマンドをラップすることです。これはやめてください。非ゼロの終了が重要な点なのです。
4つのフラグは、実行中のリクエストの動作を調整します:
--ignore-redirectsは、HTTPリダイレクトを自動的に追跡するのをランナーに停止させます。これにより、リダイレクトレスポンス自体をアサートできます。--delay-request [n]は、リクエスト間にnミリ秒待機します。これは、レート制限や負荷に敏感なエンドポイントに対して役立ちます。--timeout-request [n]は、単一のリクエストが取ることができる最大時間をミリ秒単位で設定します。--timeout-script [n]は、前処理または後処理スクリプトが実行できる最大時間をミリ秒単位で設定します。
# 煙テスト: 最初の失敗で停止
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --on-error end
# リグレッション: すべて実行し、すべての失敗を収集
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
TLSと証明書
相互TLSまたは内部認証局の背後にあるエンドポイントをテストする場合、このグループを使用して接続を確立します。
-k, --insecureは、SSL証明書の検証を完全に無効にします。自己署名証明書を持つ信頼された内部ホストに対してのみ使用してください。パブリックなものには決して向けないでください。これは接続を保護するチェックを無効にするためです。
適切な相互TLSには、代わりにクライアント資格情報を提供します。PEM証明書には--ssl-client-cert <path>、その秘密鍵には--ssl-client-key <path>、鍵が暗号化されている場合は--ssl-client-passphrase <passphrase>を使用します。異なるホストに異なる証明書が必要な場合は、--ssl-client-cert-list <path>がそれらをマッピングする設定ファイルを指定します。そして、--ssl-extra-ca-certs <path>は、信頼されたCA証明書を追加します。これは、ランナーが他に認識しない内部CAチェーンに対するクリーンな修正であり、-kを使用するよりも優れています。
出力と診断
最後のグループは、ランナーが出力する内容といくつかの実行の詳細を制御します。
--verboseは、すべてのステップの完全なリクエストとレスポンスを出力します。これは、シナリオがローカルでは合格するがCIで失敗する場合の最初の手順です。ランナーが送信し、受け取った正確なバイトが表示されるため、手動で送信したものと比較できます。--silentはその逆で、コンソール出力を抑制します。これは、終了コードと保存されたレポートのみを気にするうるさいスケジュールされたジョブに役立ちます。--color <value>は、CIログビューアがANSIコードを台無しにする場合に役立つ、カラー出力を強制的に有効または無効にします。
残りは特定のシナリオ機能用です:
--external-program-path <path>は、シナリオが呼び出すカスタムロジック用の外部プログラムファイルを指定します。--database-connection <path>は、データベースを直接クエリするステップを持つシナリオのデータベース設定を提供します。--preferred-http-version <version>は、ランナーが推奨するHTTPプロトコルバージョンを設定します。-b, --bigintは、大きな数値が精度を失わないようにBigInt処理を有効にします。--lang <language>は、CLIの表示言語を設定します。-h, --helpは、ヘルプテキストを出力します。これは、インストールされているバージョンに関する公式リストです。
まとめ: 実際に実行するコマンド
デプロイ直後に本番環境に対して煙テストを実行し、高速に失敗させます:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e $PROD_ENV_ID -r cli --on-error end
フォルダ全体で完全な夜間リグレッションを実行し、すべての失敗を1つのHTMLおよびJUnitレポートにまとめます:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports
CSVを使ったデータ駆動型実行、CI向けの機械可読な出力:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-cases.csv -r junit
マージする前に、機能ブランチでテストの変更を検証します:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli
CIのみの失敗をデバッグするために、ワイヤーの詳細をダンプします:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli --verbose
一時的なCIランナーでCLIを実行していて、グローバルにインストールしたくない場合は、インストールの代わりにnpxを使用します:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
これは同じ表面をカバーします。グローバルインストールとnpxの選択は、ランナーの衛生状態に関するものであり、機能に関するものではありません。CLIが実行するシナリオを設定するには、Apidogをダウンロードし、アプリでシナリオを作成し、そのCI/CDタブから生成されたコマンドをコピーして、トークンをパラメータ化してください。\