ガイドライン：PostmanのPre-request ScriptとTests Scriptを利用

PostmanのPre-request ScriptとTests Scriptは、APIリクエストの前後に実行できるJavaScriptコードになり、APIのテストを自動化したり、柔軟な前処理や後処理を行うことに便利なものです。それでは、PostmanでPre-request ScriptとTests Scriptをどのように利用すれば良いでしょうか？本文では、この2種類のScriptを詳しく解説した上、どのようにそれぞれの利用方法をも一緒に解説していこうと思います。

💡

Apidogは PostmanのScript に完全に互換しつつ、アサーション、変数抽出、データベース操作などの高度な機能をサポートしています。右側のコードスニペットを活用できるため、手作業を最小限に抑えられます。

button

PostmanのPre-request ScriptとTests Scriptとは

PostmanのPre-request ScriptとTests Scriptは、APIリクエストの前後に実行できるJavaScriptコードです。

Pre-request Script

Pre-request Scriptは、Postmanでリクエストが送信される前に実行されるScriptになります。Pre-request Scriptを利用することで、環境変数の設定や動的な値の生成、認証トークンの取得など、リクエストに必要な前処理を行うことができます。例えば、リクエストボディにランダムな値を設定したり、現在時刻をリクエストヘッダに追加したりできます

Tests Script

その一方で、Tests Scriptは、Postmanでリクエストのレスポンスを受け取った後に実行されるScriptになります。Tests Scriptを利用することで、レスポンスデータの検証を行ったり、応答に基づいて変数を設定したりできますし、レスポンスコードやレスポンスボディ、レスポンスヘッダなどを確認し、テストケースを記述することもできます。

Tests Scriptを利用する場合、テストが失敗した場合は赤色、成功した場合は緑色でマークされます。

これらのスクリプトを活用することで、APIのテストを自動化したり、柔軟な前処理や後処理を行うことができます。Pre-request Scriptではリクエスト側の準備、Tests Scriptではレスポンスの検証やデータ操作ができるので、API開発やテストの生産性が大幅に向上します。

PostmanでPre-request ScriptとTests Scriptを利用する

それでは、Postmanでより効率的なAPIテストを図るために、このPre-request ScriptとTests Scriptをどのように利用すれば良いのでしょうか。この部分では、PostmanでPre-request ScriptとTests Scriptの利用方法を詳しく説明していこうと思います。

Pre-request Scriptを利用

Postmanを開き、左側のサイドバーから対象のコレクションを選択します。
コレクション内の任意のリクエストを選択します。
右側の「Pre-request Script」タブをクリックします。
このタブ内にJavaScriptコードを記述します。

Pre-request Scriptで利用可能なScript例

pm.environment.set()で環境変数を設定
pm.variables.set()でグローバル変数を設定
pm.sendRequest()で別のリクエストを実行
ランダムな値や現在時刻をpm.request.bodyやpm.request.headersに設定

Tests Scriptを利用

手順1・2と同様にコレクションとリクエストを選びます。
右側の「Tests」タブをクリックします。
このタブ内にJavaScriptコードを記述します。

記述したスクリプトは、そのリクエストが実行されるたびに実行されます。

スクリプトには、Postmanの提供する様々な変数やメソッドがアクセスでき、以下のようなことができます。

Tests Scriptで利用可能なScript例

pm.response.codeで応答コードを取得し検証
pm.response.json()でJSON応答を取得し検証
pm.test()でテストケースを記述
pm.expect()で応答値を検証
グローバル変数pm.globals.set()や環境変数pm.environment.set()を設定

公式ドキュメントにも多くの情報があり、さらにコミュニティで共有されたサンプルコードも参考になります。実践を重ねるとスクリプト記述力が身につきます。

Pre-request ScriptとTests Scriptの使用例

それでは、実際には、PostmanのPre-request ScriptとTests Scriptを利用する場合は、どうしたらいいですか？次は、Pre-request ScriptとTests Scriptの実際の使用例を紹介しますので、実際の作業でどのようにこのScriptを利用するかを一緒に観にいきましょう。

Pre-request Scriptの使用例

// ランダムな数値をリクエストボディに設定する
const randomNumber = Math.floor(Math.random() * 100);
pm.request.body.update({
  mode: 'raw',
  raw: JSON.stringify({ randomNumber: randomNumber })
});

// 現在時刻をリクエストヘッダに設定する
const now = new Date().toISOString();
pm.request.headers.upsert({
  key: 'X-Current-Time',
  value: now
});

// 環境変数を参照してベースURLを設定する
const env = pm.environment.get('env');
const baseUrl = env === 'production' ? 'https://api.example.com' : 'http://localhost:3000';
pm.request.url.update({ host: baseUrl });

Tests Scriptの使用例

// レスポンスコードが200であることを検証
pm.test('Status code is 200', function() {
  pm.response.to.have.status(200);
});

// レスポンスボディにある特定のキーと値を検証
pm.test('Response includes correct data', function() {
  const responseData = pm.response.json();
  pm.expect(responseData.name).to.eql('John Doe');
  pm.expect(responseData.age).to.be.above(20);
});

// レスポンスヘッダを検証
pm.test('Response has correct header', function() {
  pm.response.to.have.header('Content-Type', 'application/json');
});

// 成功時のみグローバル変数を設定
if (pm.response.code === 200) {
  const responseData = pm.response.json();
  pm.globals.set('userId', responseData.id);
}

// 別の条件でリクエストを送信
if (pm.response.json().status === 'pending') {
  pm.sendRequest('https://api.example.com/retry', function(err, res) {
    // 別リクエストの応答処理
  });
}

これらは一般的な利用例ですが、APIの構造や要求に合わせてスクリプトを記述する必要があります。PostmanのAPIドキュメントやコミュニティのサンプルを参考にするとより実践的なスクリプトが書けるでしょう。

ApidogでScriptをより便利に利用

APIテストの中で、Scriptを利用して高度な操作を行うために、ApidogはPostmanより便利なツールだと考えられています。ApidogはAPIの設計、テスト、モック及びドキュメンテーションにも対応できるオンストップなAPI管理ツールとして、PostmanのScriptにも完全に互換しています。

button

Apidogでリクエストの設定画面で、「前処理」か「後処理」で「カスタムScript」を追加することができます。

ここで、PostmanのScriptが直接に利用されます。また、右側メニューで利用可能なコードスペニットがたくさんありますので、コードを手動で入力したくない場合で、右側のコードスペニットをクリックすると、自動的に入力してくれます。

PostmanのScriptを直接に利用するだけではなく、Apidogは次のような様々な操作をサポートしています。

アサーション：APIレスポンスのバリデーションを行うための機能となり、自分でバリデーションの条件を課し、サーバーから返されるデータが特定の要求に満たされているかどうかを自動的に検証してくれます。
変数抽出：APIレスポンスの特定の値をコンソールにプリントしたり、変数に抽出して重複に利用したりする機能となります。
データベース操作：データベースに接続して、データの取得、挿入、更新、削除を行う機能となり、テストデータのセットアップとクリーンアップが行えます。

上記のように、Apidogを使えば、PostmanのScriptの記述に加えて、他にも様々な高度な機能を活用することができるので、APIに関する作業をより簡単にすることができるのでしょう。

button

まとめ

Postmanの Pre-request Script と Tests Script は、APIテストの自動化や柔軟な前処理・後処理を実現するための強力なツールです。Pre-request Scriptでは、リクエスト送信前に環境変数の設定、動的値の生成、認証トークンの取得などの前処理を行えます。一方、Tests Scriptではレスポンスデータの検証、変数の設定、追加リクエストの送信などの後処理が可能です。

これらのスクリプトを活用することで、API開発の生産性が大幅に向上します。実践を重ねることで、より高度なスクリプトを記述できるようになります。

さらに、Apidogは PostmanScript に完全に互換しつつ、アサーション、変数抽出、データベース操作などの高度な機能をサポートしています。右側のコードスニペットを活用できるため、手作業を最小限に抑えられます。

Apidogを使えば、PostmanScriptの記述に加えて様々な操作を行え、APIの設計、テスト、モック、ドキュメント化までをシームレスに実現できます。APIライフサイクル全体を包括的に管理できるため、Apidogは APIテストとその先の領域でも大きな恩恵をもたらすでしょう。