エンジニアの皆さん、こんにちは。API開発の現場で「テスト結果をSlackに投げる」あるいは「CI/CDパイプラインで自動テストを回す」という作業、避けては通れませんよね。
PostmanのCLI実行エンジンであるNewmanは非常に強力ですが、デフォルトの出力はテキストベースで、正直なところ「あとで振り返る」には少し味気ないものです。
今回は、そんなNewmanの出力結果を劇的に変える「newman-reporter-htmlextra」というツールを紹介します。これを使えば、単なる合格・不合格の羅列ではなく、「どこが、なぜ、どう間違えたのか」が一目でわかる、美しく詳細なレポートを自動生成できるようになります。
現場で震えるほど役立つ、その実践テクニックを伝授しましょう。
—
1. なぜ「htmlextra」が必要なのか？
Postmanでテストを組むのは簡単ですが、開発が大規模になればなるほど、CI環境で「どのエンドポイントで、どのリクエストが、どのレスポンスで落ちたのか」を瞬時に特定する必要があります。
`newman-reporter-htmlextra`の最大のメリットは以下の3点です。
- 可視化: 直感的なグラフとサマリーで、チームへの共有が容易。
- デバッグ性: リクエストとレスポンスのボディ、ヘッダー、環境変数を一画面で確認可能。
- 拡張性: 失敗時のスクリーンショットを埋め込むなど、後から追跡しやすい構成。
—
2. 導入：最短で環境を構築する
まずは準備です。Node.js環境が必要ですが、既にある前提で進めます。まだの方はインストールしておいてください。
インストール
Newman本体と、今回の主役であるhtmlextraをインストールします。
Newmanとhtmlextraをグローバルにインストール
npm install -g newman newman-reporter-htmlextra
—
3. HelloWorld：最初のレポート生成
まずは、手元にあるPostmanコレクションファイル（`collection.json`）を使って、基本的なレポートを生成してみましょう。
newman run collection.json \
-r htmlextra \
–reporter-htmlextra-export ./reports/report.html
これだけで、`./reports/report.html` に非常に見やすいHTMLファイルが生成されます。ブラウザで開いてみてください。これだけでも既存のCUI出力より何倍も優秀なことがわかるはずです。
—
4. 現場で差がつく！高度な設定術
ここからが本題です。ただ出すだけならマニュアル通り。現場で真価を発揮する「設定」を紹介します。
推奨の実行コマンド
CI/CDで回す際は、以下のオプションを組み込むのが私の「鉄板」構成です。
newman run collection.json \
-e environment.json \
-r htmlextra \
–reporter-htmlextra-export ./reports/report.html \
–reporter-htmlextra-darkTheme \
–reporter-htmlextra-showOnlyFails \
–reporter-htmlextra-logs
- `–reporter-htmlextra-darkTheme`: 目に優しいダークモードです。深夜のデバッグ作業には必須。
- `–reporter-htmlextra-showOnlyFails`: 成功した数千のテストを隠し、エラーのみを表示。ノイズを排除して問題の本質に集中できます。
- `–reporter-htmlextra-logs`: `console.log`の内容をレポートに出力します。デバッグ時に「どの変数がどう評価されたか」を追うのに最適です。
—
5. 失敗時のスクリーンショット埋め込み（極意）
もし、あなたがPostmanの「Visualizer」機能を使ってテスト結果をGUIで表示している場合、その結果をレポートに含めることも可能です。
テストスクリプト内に以下のように記述してください：
// テストが失敗した時の処理例
pm.test(“Status code is 200”, function () {
if (pm.response.code !== 200) {
// レポートに詳細を残すための工夫
console.error(“Critical Failure: Response code is ” + pm.response.code);
}
pm.response.to.have.status(200);
});
`–reporter-htmlextra-logs` を有効にしていれば、この `console.error` もHTMLレポート内に綺麗に記録されます。これにより、「なぜそのテストが落ちたのか」をコードレベルで即座に特定できるようになります。
—
まとめ：自動化の先にある「楽」
いかがでしたか？
これまでは「テストが落ちた」と聞くたびに、わざわざPostmanを開いて、環境設定を選んで、手動でリクエストを送って……と繰り返していたかもしれませんが、今日からは違います。
「CIが回る → レポートが生成される → 失敗箇所をHTMLで見て即修正」
このサイクルを確立すれば、あなたの貴重なエンジニアリング・リソースは「単純な確認作業」から解放され、もっと創造的な「設計や実装」に注げるようになります。
ぜひ、次回のプロジェクトから導入してみてください。現場が驚くほど、API開発の速度が上がりますよ。何か困ったことがあれば、いつでも聞いてくださいね。応援しています！