何の役にも立たないテスト実行は、誰も信頼しないテスト実行です。パイプラインが赤くなり、誰かがビルドログを開いても、タイムスタンプの羅列とゼロ以外の終了コードしか見つからない。どのアサーションが壊れたのか？どの環境に対して？データファイルのどの行で？実行は知っていたはずです。ただ、後で読めるようにどこにも書き残していなかっただけです。
そのギャップを埋めるのがレポーターです。コマンドラインからAPIテストを実行する場合、レポートは実際に付き合っていく部分です。つまり、アーカイブする成果物、CIダッシュボードが解析するファイル、午前2時にはパイプラインを見ていなかった午前9時のチームメイトに渡すものです。テストの判定は仕事の半分に過ぎません。もう半分は、その判定を人間と機械の両方に同時に読み取れるようにすることです。
Apidogのコマンドラインランナーは、その両方を処理します。Apidogは、アプリで視覚的に構築したテストシナリオを実行するCLIを提供しており、すべてのレポートを制御するフラグは1つだけです。それが-r, --reportersです。カンマ区切りのリストを渡すと、ランナーは各形式をディスクに書き込み、誰が何を読めるかを決定できます。このガイドは、そのフラグとそれが生成するファイルについてです。各レポーターが何のためか、ディスクに何が書き込まれるか、どこに書き込まれるか、そしてそれぞれを実際のワークフローに接続する方法について説明します。ランナーが受け入れるすべてのフラグのより広範なツアーが必要な場合は、apidog runコマンドリファレンスが全体をカバーしています。このページはレポートに焦点を当てています。
なぜ実行よりもレポートが重要なのか
ローカルでシナリオを実行すると、その過程を目撃できます。各リクエストが起動し、各アサーションが緑色になり、最後に概要が表示されます。フィードバックループは目の前のターミナルにあり、リアルタイムです。
CIでは、そのループは存在しません。実行は、見たこともないマシン上で、監視していない時間に行われ、唯一の記録は、ランナーが終了する前にディスクに書き込まれたものです。実行がレポートを生成しなかった場合、失敗は「何かが壊れた」ことだけを伝えます。残されるのは、全体をローカルで再実行し、同じように壊れることを願うだけです。
優れたレポートはその距離を縮めます。どのシナリオが実行されたか、どの環境に対して、何回のイテレーション、どのアサーションが成功し、どれが失敗したか、そして各失敗の背後にあるリクエストとレスポンスの詳細をキャプチャします。これをディスクに残しておけば、午前2時の失敗は、再現のための調査ではなく、翌朝の5分間の読書になります。これがレポーターフラグが存在する理由のすべてであり、各オーディエンスに適した形式を選択するために少し時間をかける価値がある理由です。
すべてのレポートを制御する唯一のフラグ
Apidog CLIはapidog-cliというnpmパッケージです。一度インストールすれば、apidogという単一のバイナリが得られ、その主要なサブコマンドはrunです。グローバルにインストールします。
npm install -g apidog-cli
ランナーが生成できるすべてのレポートは、そのコマンドの1つのフラグから生成されます。それが-r, --reportersです。これはカンマ区切りのリストを受け入れ、受け入れられる4つの値はcli、html、json、junitです。何も渡さない場合のデフォルトはcliです。
2つのレポーターを含む完全な実行は次のようになります。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
これにより、トークンで認証し、テストシナリオ605067を環境1629989に対して1回実行し、HTMLファイルと読み取り可能なターミナル出力の両方を出力します。IDはシナリオIDと環境IDです。これらは、アクセスデークンとともに、手動で入力するのではなく、ApidogのシナリオのCI/CDタブからコピーします。これらの設定に見慣れない点がある場合は、Apidog CLI完全ガイドでインストール、トークン、および最初の実行がエンドツーエンドで説明されています。
重要なアイデアは、1回の実行で複数のレポートを同時に生成できることです。単一の形式を選択するわけではありません。各出力の対象となるオーディエンスを選択し、それらをまとめてリストするのです。一般的なCIラインは、同じ実行から人間が読めるHTMLファイルと機械が読めるJUnitファイルを出力するため、同じ実行で人にもダッシュボードにも対応できます。
cli：ビルドログで読むレポート
cliレポーターは、読みやすい要約をターミナルに直接出力します。これはデフォルトであり、人間が最初に目を通すものです。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
これにより、ライブの判定が得られます。何回のリクエストが実行されたか、何回のアサーションが成功し失敗したか、そして具体的にどのアサーションが壊れたか。CIビルドログでは、これは失敗したジョブをクリックしたときに誰かが読むブロックです。失敗が1つの壊れたアサーションなのか50個なのか、どのエンドポイントが関係しているのかを、何かをダウンロードする手間をかける前に一目でわかります。
機械形式を書き出す場合でもcliはオンにしておきましょう。コストはかかりませんし、ビルドログ自体を有用に保ちます。JUnit XMLのみを出力するパイプラインは、完璧なダッシュボードと役に立たないログを生成します。生の出力を読む人は、ランナーの起動と終了しか見えません。cliをリストに追加することで、これが解決されます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
さらに2つのフラグがcliの出力を形作ります。--verboseは、各ステップの完全なリクエストとレスポンスに展開されます。これは、シナリオがラップトップでは成功するのにパイプラインで失敗する場合に最初に行うべきことです。ワイヤー詳細により、ランナーが送信し、受け取ったものが正確にわかります。--silentはその逆で、コンソール出力を完全に抑制します。これは、終了コードと保存されたファイルだけを気にするような、ノイズの多いスケジュールされたジョブに適しています。
html：人間に手渡すレポート
htmlレポーターは、自己完結型のHTMLファイルを作成します。任意のブラウザで開くと、すべての実行が視覚的に表示されます。各リクエスト、それに対するアサーション、成功と失敗のステータス、そして各ステップの背後にあるリクエストとレスポンスの詳細が含まれます。インストールするものも、実行するサーバーもありません。ダブルクリックするだけのファイルです。
これはアーカイブして共有する形式です。ビルド成果物として保存しておけば、レポートはパイプラインの実行後も残り、1週間後でも、壊れたデプロイからの正確なレポートを開くことができます。また、「何が失敗したの？」と尋ねる人に、CLIをインストールしたり、何かを再実行させたりすることなく送るものです。彼らはファイルを開き、赤いステップを見て、アサーションをトリガーしたレスポンスボディを読み、それだけで済みます。
HTMLは、データ駆動型実行で最もその価値を発揮します。50行のCSVをループする1つのシナリオの場合、HTMLレポートは反復ごとの結果を表示するため、1行目から49行目までは成功し、50行目はあるアカウントのトークンが古かったために失敗したということがわかります。成功または失敗の数だけでは、それはわかりません。データファイル間でシナリオを実行する場合のパターンは、CSVとJSONを使用したデータ駆動型APIテストでカバーされています。
トレードオフ：HTMLは目で見るものであり、解析用ではありません。スクリプトで成功/失敗のステータスをスクレイピングしようとしないでください。それはJSONとJUnitの役割です。
junit：CIダッシュボードが解析するレポート
junitレポーターは、標準のJUnit形式でXMLを出力します。この形式が重要である理由は、CIテスト報告の共通語だからです。GitHub Actions、GitLab CI、Jenkins、CircleCI、Azure Pipelinesなど、ほとんどすべてのCIシステムがJUnit XMLを読み取り、それを成功/失敗ツリーに変換し、マージリクエストウィジェットで失敗を表示し、ビルド全体で時間の経過とともに結果をトレンド化する方法を知っています。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
CI用に1つの機械形式だけを選ぶなら、これを選びましょう。その見返りとして、テスト結果がログファイルの中だけでなく、チームがすでに参照しているダッシュボードに表示されるようになります。レビュー担当者はプルリクエストを開き、どのアサーションが失敗したかをインラインでレンダリングされた形で確認でき、ログを掘り下げたり、成果物をダウンロードしたりする必要はありません。
これを接続するには2つのステップがあります。まずXMLを生成し、次にCIシステムにその場所を教えます。GitLab CIでは、その2番目のステップはreports: junit:ブロックです。
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli --out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
Jenkinsでは、同じファイルを参照するpostブロック内のjunitステップが同等です。GitHub Actionsでは、ディレクトリをアーティファクトとしてアップロードし、JUnit対応のアクションにレンダリングさせます。テストが失敗した場合でも実行されるアーティファクトアップロードを含む完全なGitHubワークフローは、GitHub ActionsでのApidog CLIテストの実行にあります。
json：スクリプトが後処理するレポート
jsonレポーターは、生の構造化された結果を生成します。HTMLが目で見るため、JUnitがダッシュボードのためであるのに対し、JSONは自分で書いたコードのためのものです。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
組み込みの形式では、結果でやりたいことができない場合にこれに手を伸ばしてください。監視システムに合格率メトリクスをプッシュする。カスタムのSlackサマリーを構築する。デプロイをロールバックするかどうかを決定するスクリプトに結果をフィードする。今日の実行を昨日のものと比較する。構造を推測することなく解析できる形式であるため、プログラムによる処理はすべてJSONから始まります。
JSON出力用に特別に構築されたレポートフラグが1つあります。--out-json-failures-separated <value>は、失敗を独自のJSONファイルに分割します。これにより、失敗のみのドキュメントが得られ、壊れた少数のステップを完全な結果からスキャンするよりも、はるかに読みやすく、差分を取りやすくなります。ほとんどのステップが成功する大規模なリグレッションスイープでは、失敗のみのファイルは一瞥とgrepの違いを生みます。
ファイルの格納場所: --out-dir、--out-file、およびプレースホルダー
形式を選択することは全体の半分です。もう半分は、ファイルがどこに格納され、どのような名前になるかを制御することです。これは、複数の実行のレポートを保持するようになった瞬間に重要になります。
--out-dir <dir>は、レポートの書き込み先ディレクトリを設定します。デフォルトは./apidog-reportsです。CIでは、アーティファクトステップが見つけられる場所を指定し、アップロード設定を変更する必要がないように一貫性を保ちます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name>はレポートのファイル名を設定し、これが非常に便利です。これがないと、各実行が前のものを上書きする傾向があるため、常に最新のレポートしか残りません。このフラグは、ランナーが書き込み時に埋めるプレースホルダーを受け入れます。
{SCENARIO_NAME}は実行されたシナリオの名前になります。{FOLDER_NAME}はシナリオのフォルダーを実行したときのフォルダー名になります。{GENERATE_TIME}はタイムスタンプになります。
ファイル名にシナリオ名とタイムスタンプを付けることで、各実行が以前のものを上書きする代わりに、明確で自己記述的なファイルを書き込みます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
これで、レポートディレクトリは履歴のように読み取れるようになります。ファイルを開かなくても、どのレポートがどのシナリオから生成され、いつ実行されたかを知ることができます。これは、夜間実行のフォルダーをスキャンして、最初に問題が発生した実行を見つけたい場合にまさに望むものです。
さらに、クラウドサイドを補完するレポートフラグがもう1つあります。--upload-report [value]は、レポートの概要をApidogクラウドにアップロードするため、実行結果はローカルファイルと一緒にプロジェクトの履歴にも表示されます。これは、CIランナー上のファイルとしてだけでなく、Apidog自体の中で結果を表示したい場合に利用するオプションです。
オーディエンス別のレポーター戦略
最も明確な方法は、各レポーターを読む対象にマッピングし、必要なものをまとめて渡すことです。
- 今すぐビルドログをスキャンする人は
cliを読みます。常に含めましょう。 - 後で保存されたレポートを開く人は
htmlを読みます。成果物としてアーカイブしましょう。 - CIダッシュボードは
junitを読みます。これはマージリクエストで失敗をレンダリングし、ビルド全体で結果をトレンド化するものです。 - 自分で書いたスクリプトは
jsonを読みます。これは、独自のコードで解析されることを意図した唯一の形式です。
ほとんどのCIパイプラインでは、人間向けのHTMLとダッシュボード向けのJUnitに、生のログが読み取り可能になるようにCLIをオンにした組み合わせが最も効果的です。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
この1回の実行で、読みやすいログ、ブラウズ可能な成果物、そして解析可能なXMLファイルが生成されます。3つのオーディエンスに対し、1回の実行で、重複はありません。
はっきりと述べる価値のある注意点が一つあります。レポートは「何が起こったか」を伝えますが、終了コードがパイプラインに「それに基づいて行動させる」ものです。Apidog CLIは、いずれかのアサーションが失敗するとゼロ以外の終了コードで終了します。ビルドを失敗させ、マージをブロックするのは、レポートではなく、その終了コードです。レポートは失敗を説明し、終了コードがそれを強制します。シェルで|| trueを追加するなどの方法で、そのコードを飲み込んでしまうようなコマンドでラップしないでください。そうしないと、完全に赤いレポートが、グリーンになったビルドに添付されてしまいます。その品質ゲートロジックのより詳細なバージョンは、CI/CDでのAPIテストの自動化ガイドに記載されています。
まとめ
CIでシナリオを実行し、3つのオーディエンス向けに3つの有用な成果物をすべて出力します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
夜間フォルダーを掃引し、すべての失敗を1つのレポートに収集し、各ファイルに自己記述的な名前を付けます。
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
データ駆動型シナリオを実行し、迅速な差分比較のために失敗のみのJSONを保持します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
一時的なランナーにCLIをグローバルにインストールしたくない場合は、インストールをnpxに置き換え、同じレポーターフラグを使用します。
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
レポーターの動作はどちらの方法でも同じです。グローバルインストールとnpxの選択は、ランナーの衛生状態に関するものであり、得られるレポートに関するものではありません。
フラグ名、デフォルト値、およびレポーターはCLIのリリース間で変更される可能性があるため、ランナー自体が常に信頼できる情報源です。インストールされているバージョンでapidog run --helpを実行し、この記事を含め、あらゆる記事よりもそれを信頼してください。そもそもCLIが実行するシナリオを設定するには、Apidogをダウンロードし、アプリで1つのシナリオを構築した後、CI/CDタブから生成されたコマンドをコピーし、必要なレポーターを追加してください。