Postmanは、HTTPリクエストを送信し、APIがどのように動作するかを確認するための最も広く使用されているツールの1つです。ブラウザ拡張機能として始まり、簡単なGETリクエストからCIで実行されるスクリプト化されたテストスイートまで、あらゆるものを処理するフル機能のデスクトップアプリケーションへと成長しました。APIを構築または利用するなら、Postmanに遭遇することはほぼ確実でしょう。
このガイドでは、PostmanでAPIを日常的にテストする方法を順を追って説明します。リクエストを送信し、レスポンスを検証し、「Tests」タブでアサーションを記述し、ステージング環境と本番環境を切り替えられるように環境を設定し、Collection Runnerでコレクション全体を一度に実行します。例では公開APIを使用しているため、事前に何も設定せずに手順を追うことができます。
Postmanのセットアップと初めてのリクエスト送信
公式サイトからPostmanをダウンロードし、デスクトップアプリをインストールします。ローカルでの作業であればアカウントなしでも利用可能ですが、サインインするとコレクションがデバイス間で同期されます。アプリを開き、Newボタンをクリックし、HTTP Requestを選択します。
リクエストには最低限3つのものが必要です。メソッド、URL、そして場合によってはボディです。メソッドのドロップダウンからGETを選択し、実際のエンドポイントを入力します。JSONPlaceholderサービスは練習に便利です。
GET https://jsonplaceholder.typicode.com/users/1
Sendをクリックします。レスポンスパネルにボディ、ステータスコード（200 OK）、応答時間、およびサイズが表示されます。ボディ表示をPretty、Raw、Previewの間で切り替えて、JSON形式またはサーバーが送信したそのままの形式で確認できます。
POSTの場合、メソッドを変更し、Bodyタブを開き、rawを選択し、形式ドロップダウンからJSONを選択します。次のようなペイロードを貼り付けます。
{
"name": "Maria Chen",
"email": "maria.chen@example.com"
}
JSONボディタイプを選択すると、Content-Type: application/jsonのようなヘッダーが自動的に追加されます。Headersタブでは、Authorizationヘッダーなど、APIが必要とするその他の情報を追加できます。期待されるレスポンスコードについてよく知らない場合、REST APIが使用すべきHTTPステータスコードに関するガイドは役立つ参考資料です。
リクエストをコレクションに整理する
簡単な確認であれば、単一のリクエストで十分です。実際のテストでは、ユーザーの作成、そのユーザーの取得、更新、削除など、関連する多数のリクエストが必要です。Postmanはこれらをコレクションにグループ化します。
サイドバーのCollectionsをクリックし、次に+アイコンをクリックしてコレクションを作成します。「User API smoke tests」のような具体的な名前を付けます。Ctrl/Cmd + Sで各リクエストをコレクションに保存し、明確な名前を付けます。コレクション内にフォルダーをネストして、例えば認証リクエストとリソースリクエストを分けることができます。
コレクションは共有する単位でもあります。JSONファイルとしてエクスポートしたり、クラウドに同期している場合はリンクを共有したりできます。チームメイトはそれをインポートして、あなたとまったく同じリクエストを利用できます。Collection Runnerも自動テストも、個別のリクエストではなくコレクションを対象として動作するため、これは他のすべての基礎となります。
コレクションは共有の振る舞いを持つこともできます。Postmanでは、単一のリクエストだけでなく、コレクションやフォルダーレベルでスクリプトを添付できます。コレクションのプリリクエストスクリプトは、コレクション内のすべてのリクエストの前に実行され、トークンの更新やタイムスタンプの付与などに便利です。コレクションレベルのテストスクリプトは、すべてのリクエストの後に実行され、「レスポンス時間は妥当である」など、あらゆる場所で必要なアサーションに役立ちます。これらを一度定義することで、個々のリクエストをそれぞれ固有の側面に集中させることができます。
「Tests」タブでテストを記述する
リクエストを送信すると、何が返ってきたかを知ることができます。テストは、返ってきたものが正しいかどうかを、毎回自動的に教えてくれます。Postmanは、レスポンスが到着した後、リクエストのScriptsエリア（古いバージョンではTestsタブと呼ばれていました）でJavaScriptを実行します。
Postmanはアサーションを記述するためのpmオブジェクトを提供しています。核となるパターンはpm.test(name, callback)で、コールバックは期待値が満たされなかった場合にエラーをスローします。これらが頻繁に使用するアサーションです。
// ステータスコードを確認する
pm.test("Status code is 200", function () {
pm.response.to.have.status(200);
});
// 応答時間を確認する
pm.test("Response is under 500ms", function () {
pm.expect(pm.response.responseTime).to.be.below(500);
});
// JSONボディのフィールドを確認する
pm.test("User has the expected email", function () {
const body = pm.response.json();
pm.expect(body.email).to.eql("maria.chen@example.com");
});
// ヘッダーを確認する
pm.test("Content-Type is JSON", function () {
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/json");
});
アサーション構文はChaiに由来しており、pm.expectは.to.eql、.to.include、.to.be.aboveなどをサポートしています。Sendをクリックすると、Test Resultsタブに結果が表示され、各テストが緑色（成功）または赤色（失敗）で表示されます。
いくつかの習慣がテストを役立つものにします。各pm.testブロックには、エンドポイントではなく、チェックする動作に基づいて名前を付けてください。そうすることで、失敗メッセージが文章のように読めます。実際にAPIの利用者を壊してしまう可能性のあるもの（ステータスコード、ボディの形状、クライアントが依存するフィールド）をチェックしてください。サーバー生成のタイムスタンプなど、制御できない値に対してアサーションを行うのは避けてください。それらは不安定な失敗を引き起こし、人々が赤（失敗）を無視するように仕向けてしまいます。Postmanにはエディターの横にSnippetsパネルも付属しており、クリックするだけで挿入できる既製のアサーションが用意されています。これはpm APIを学ぶ最速の方法です。アサーション設計をより深く掘り下げたい場合は、APIアサーションとその適切な記述方法の解説を参照してください。チェックを名前付きのケースに構造化するというより広いアイデアについては、APIテストケースの例ガイドも併せて読む価値があります。
環境と変数を使用する
https://api.staging.example.comをすべてのリクエストにハードコーディングすると、本番環境を指す必要が生じたときに苦痛です。環境がこれを解決します。環境とは、名前付きの変数セットです。
サイドバーの環境アイコンをクリックし、「Staging」という名前で環境を作成します。https://jsonplaceholder.typicode.comという値を持つ変数base_urlを追加します。異なるbase_urlを持つ「Production」という2番目の環境を作成します。次に、二重波括弧を使用してリクエスト内で変数を参照します。
GET {{base_url}}/users/1
右上のドロップダウンからアクティブな環境を選択すると、{{base_url}}を使用するすべてのリクエストがそれに合わせて切り替わります。
変数はリクエスト間でデータを引き渡すこともできます。ログインリクエストは、そのレスポンスからトークンを取得し、後続のリクエストで使用するために保存できます。
pm.test("Save the auth token", function () {
const token = pm.response.json().token;
pm.environment.set("auth_token", token);
});
その後、すべてのリクエストでAuthorization: Bearer {{auth_token}}を送信できます。このチェーン化により、リソースの作成とその存在確認など、状態に依存するフローをテストできます。
Postmanには、知っておくべき2つの関連する変数スコープがあります。環境変数は選択された環境に属し、環境を切り替えると変更されます。コレクション変数は環境に関係なくコレクションに属し、そのAPIにとって定数である値に適しています。さらに、どこでも適用されるグローバル変数と、1回の実行のみに存在する短命なローカル変数もあります。適切なスコープを選択することで、値が本来あるべき場所に保たれ、ターゲットを切り替えたときの予期せぬ事態を回避できます。
Collection Runnerでコレクション全体を実行する
各リクエストで「Send」をクリックするのはすぐに手間になります。Collection Runnerはコレクション内のすべてのリクエストを順番に実行し、すべてのテストを実行し、合否の概要を提供します。
コレクションを開き、Runボタンをクリックするか（または三点リーダーメニューからRun collectionを選択）、ランナーがリクエストを順番に表示します。環境を選択し、実行するイテレーション数を設定し、オプションでデータファイルを添付します。Runをクリックすると、Postmanはすべてのリクエストを上から下へ順次実行し、各リクエストのテストも実行します。
結果ページには、すべてのリクエストに対するすべてのアサーションが、合格と失敗の合計とともに表示されます。これがあなたの回帰チェックです。デプロイ後にこれを実行すれば、APIがまだ正常に動作しているかどうかを数秒で知ることができます。ランナーは過去の実行履歴も保持しているため、今日の結果を昨日の結果と比較し、以前は成功していたスイートがいつ失敗し始めたかを特定できます。
ランナーでは順序が重要です。リクエストは上から下へ実行されるため、ログインリクエストを最初に配置してauth_tokenを取得させ、その下のすべてのリクエストでそのトークンを使用させることができます。セットアップとクリーンアップにも同じことが言えます。開始付近でリソースを作成し、途中でそれを行使し、最後に削除する。適切に順序付けられたコレクションは、完全なユーザーのジャーニーを効果的にスクリプト化します。
データ駆動型テストの場合、ランナーでCSVまたはJSONファイルを添付します。各行が1つのイテレーションとなり、{{username}}のような変数として列を参照します。これにより、1つのリクエストで数十の入力組み合わせを、リクエストを重複させることなくテストできます。例えば、ログインエンドポイントは、有効な資格情報を持つ1行と、不正な資格情報を持つ複数行でヒットさせることができ、各行が期待するステータスコードをアサーションします。CSVとJSONによるデータ駆動型APIテストに関する記事では、このパターンについて詳しく解説しています。GUIなしでCIで同じコレクションを実行するには、PostmanはNewmanコマンドラインツールを提供しています。NewmanとPostmanの比較で説明されています。
Postmanが重くなる点、および考慮すべき点
Postmanは、探索的テストや小〜中規模のスイートに優れています。プロジェクトが成長するにつれて、2つの問題点が現れます。まず、アサーションはJavaScriptで記述されるため、非開発者や視覚的なアプローチを好むQA担当者には学習曲線があります。第二に、PostmanはAPI設計、テスト、モック、ドキュメントを別々の場所に保持するため、テストデータとAPI契約が乖離する可能性があります。
Apidogは、これら両方に対応するオールインワンのAPIプラットフォームです。Postmanコレクションを直接インポートできるため、移行に書き換えは不要です。アサーションはコードなしで視覚的に構築でき、必要なときにはスクリプトも利用できます。設計、デバッグ、モック、テスト、ドキュメントが一つの真実の源を共有するため、テストは実際のAPI仕様と常に一致します。選択肢を検討している場合、APIテストのためのPostman代替ツールまとめではトレードオフが示されています。Apidogをダウンロードして既存のコレクションをインポートし、直接比較することができます。
これらすべてがPostmanの使用をやめるべきだという意味ではありません。特に簡単な確認や、すでにPostmanに投資しているチームにとっては、依然として堅実な選択肢です。重要なのは、それぞれのツールがどこに適しているかを知ることです。
よくある質問
PostmanでAPIをテストするためにコードを書く必要がありますか？
リクエストの送信とレスポンスの読み取りには必要ありません。自動化されたアサーションには、はい、少なくとも少しは必要です。Postmanの「Tests」タブはJavaScriptを実行し、pmオブジェクトを使用します。パターンはシンプルで、Postmanの組み込みスニペットパネルからコピーできますが、それでもJavaScriptです。コード不要のビジュアルアサーションビルダーが必要な場合は、Apidogのような専用プラットフォームがそれを扱います。
Postmanコレクションと環境の違いは何ですか？
コレクションは、テストと一緒にグループ化されたリクエストのセットです。環境は、base_urlやauth_tokenのような、名前付きの変数セットです。コレクションは送信するものを保持します。環境は、ステージング、本番、ローカル間で変更される値を保持します。異なるサーバーに対して同じリクエストをテストするために、1つのコレクションを異なる環境に指定します。
CIでPostmanテストを自動的に実行するにはどうすればよいですか？
PostmanのコマンドラインランナーであるNewmanを使用します。コレクションと環境をエクスポートし、その後、newman run collection.json -e environment.jsonを実行します。いずれかのテストが失敗した場合、Newmanは非ゼロコードで終了します。これはCIパイプラインがチェックするものです。CI/CDでAPIテストを自動化するに関するガイドでは、これをパイプラインに組み込む方法が解説されています。
PostmanはREST API以外もテストできますか？
はい。最新のPostmanは、通常のHTTPとRESTに加えて、GraphQL、gRPC、WebSocket、SOAPのリクエストをサポートしています。「Tests」タブとアサーションはこれらのほとんどで機能しますが、プロトコルごとに正確なリクエスト設定は異なります。
1つのリクエストにいくつのアサーションを持たせるべきですか？
レスポンスが正しいことを確認するのに十分な数で、1つの変更で多数のテストが壊れるほど多くはありません。一般的な基準は、ステータスコード、応答時間、およびそのエンドポイントにとって重要な2、3のフィールドです。各pm.testブロックを1つの期待値に集中させてください。そうすることで、失敗したときに何が壊れたのかを正確に知ることができます。