本記事は、Postman JavaScript reference の日本語訳です（2024年5月13日更新）。

Postman JavaScript API の機能により、pm オブジェクトを使用して、リクエストとレスポンスのデータと変数にプログラムでアクセスし、変更することができます。また、コレクションランナー用のリクエストワークフローを構築するために、実行順序を動的に変更することもできます。

スクリプトで変数を使う

pm API を使って、Postman の各スコープの変数にアクセスして操作することができます。

リクエストの実行時に動的変数を使って値を生成することができます。

Postman は様々な変数スコープをサポートしています。pm オブジェクトはグローバル変数、コレクション変数、環境変数のいずれかを特定してアクセスするためのメソッドと、異なるスコープの変数にアクセスしたりローカル変数を設定するための pm.variables メソッド群を提供します。

現在のスコープに Postman 変数があるかどうかをチェックする：

pm.variables.has(variableName:String):Function → Boolean

指定した名前の Postman 変数の値を取得する：

pm.variables.get(variableName:String):Function → *

指定した名前と値を持つローカル変数を設定する：

pm.variables.set(variableName:String, variableValue:*):Function

構文 {{$variableName}} を使って、スクリプト内の動的変数の解決された値を返す：

pm.variables.replaceIn(variableName:String):Function: → *

例：

const stringWithVars = pm.variables.replaceIn("こんにちは、私の名前は {{$randomFirstName}} です");
console.log(stringWithVars);

現在のスコープにあるすべての変数とその値を含むオブジェクトを返す。優先順位に基づいて、複数のスコープの変数を含むことになる。

pm.variables.toObject():Function → Object

変数スコープは、変数を参照するときに Postman が変数に与える優先順位を、順位の高い順に決定します：

グローバル
コレクション
環境
データ
ローカル

最も狭いスコープを持つ変数が他を上書きします。例えば、現在のコレクションとアクティブな環境の両方に score という名前の変数がある時に、pm.variables.get('score') を呼び出した場合、Postman は環境変数の現在の値を返します。pm.variables.set を使用して変数の値を設定する場合には、その値はローカルであり、現在のリクエストまたはコレクションの実行時のみ保持されます。

// コレクション変数 'score' = 1
// 環境変数 'score' = 2

// 1回目のリクエストの実行
console.log(pm.variables.get('score')); // 出力：2
console.log(pm.collectionVariables.get('score')); // 出力：1
console.log(pm.environment.get('score')); // 出力：2

// 2回目のリクエストの実行
pm.variables.set('score', 3); // ローカル変数
console.log(pm.variables.get('score')); // 出力：3

// 3回目のリクエストの実行
console.log(pm.variables.get('score')); // 出力：2

詳細は Postman Collection SDK Variables reference を参照してください。

また、pm.environment、pm.collectionVariables、pm.globals を用いて、個々のスコープで定義された変数にアクセスすることもできます。

スクリプトで環境変数を使う

スクリプトはアクティブな（現在選択されている）環境の変数にアクセスして操作するために pm.environment メソッド群を使うことができます。

アクティブな環境の名前：

pm.environment.name:String

環境に指定された名前の変数があるかどうかを調べる：

pm.environment.has(variableName:String):Function → Boolean

アクティブな環境の指定された名前の変数を取得する：

pm.environment.get(variableName:String):Function → *

アクティブな環境で指定された名前と値を持つ変数を設定する：

pm.environment.set(variableName:String, variableValue:*):Function

構文 {{$variableName}} を使ってスクリプト内の動的変数の解決された値を返す：

pm.environment.replaceIn(variableName:String):Function → *

例：

// 環境に変数 firstName と age が存在
const stringWithVars = pm.environment.replaceIn("こんにちは、私の名前は {{firstName}} で、{{age}} 歳です。");
console.log(stringWithVars);

アクティブな環境のすべての変数とその値を1つのオブジェクトで返す：

pm.environment.toObject():Function → Object

アクティブな環境から変数名を指定して変数を削除する：

pm.environment.unset(variableName:String):Function

アクティブな環境のすべての変数を消去する：

pm.environment.clear():Function

変数を編集できるかどうかはワークスペースのアクセスレベルに依存することに注意してください。

スクリプトでコレクション変数を使う

スクリプトは pm.collectionVariables メソッド群を使用して、コレクション内の変数にアクセスし、操作することができます。

コレクションに指定された名前の変数があるかどうかをチェックする：

pm.collectionVariables.has(variableName:String):Function → Boolean

指定された名前のコレクション変数の値を返す：

pm.collectionVariables.get(variableName:String):Function → *

コレクション変数に指定された名前と値を設定する：

pm.collectionVariables.set(variableName:String, variableValue:*):Function

構文 {{$variableName}} を使って、スクリプト内の動的変数の解決された値を返す：

pm.collectionVariables.replaceIn(variableName:String):Function → *

例：

// コレクションに変数 firstName と age が存在
const stringWithVars = pm.collectionVariables.replaceIn("こんにちは、私の名前は {{firstName}} で、{{age}} 歳です。");
console.log(stringWithVars);

コレクション内のすべての変数とその値をオブジェクトで返す：

pm.collectionVariables.toObject():Function → Object

コレクションから指定された変数を削除する：

pm.collectionVariables.unset(variableName:String):Function

コレクションからすべての変数を消去する：

pm.collectionVariables.clear():Function

スクリプトでグローバル変数を使う

スクリプトは pm.globals メソッド群を使用して、ワークスペース内のグローバルスコープで変数にアクセスし、操作することができます。

指定された名前のグローバル変数が存在するかチェックする：

pm.globals.has(variableName:String):Function → Boolean

指定された名前のグローバル変数の値を返す：

pm.globals.get(variableName:String):Function → *

指定した名前と値を持つグローバル変数を設定する：

pm.globals.set(variableName:String, variableValue:*):Function

構文 {{$variableName}} を使って、スクリプト内の動的変数の解決された値を返す：

pm.globals.replaceIn(variableName:String):Function → String

例：

// グローバルに変数 firstName と age が存在
const stringWithVars = pm.globals.replaceIn("こんにちは、私の名前は {{firstName}} で、{{age}} 歳です。");
console.log(stringWithVars);

オブジェクト内のすべてのグローバル変数とその値を返す：

pm.globals.toObject():Function → Object

指定されたグローバル変数を削除する：

pm.globals.unset(variableName:String):Function

ワークスペース内のすべてのグローバル変数を消去する：

pm.globals.clear():Function

変数を編集できるかどうかは、ワークスペースのアクセスレベルに依存することに注意してください。

スクリプトでデータ変数を使用する

スクリプトは、pm.iterationData メソッド群を使用して、コレクション実行中にデータファイルから変数にアクセスして操作できます。

指定された名前の変数が現在のイテレーションデータに存在するかどうかをチェックする：

pm.iterationData.has(variableName:String):Function → Boolean

イテレーションデータから指定された名前の変数を返す：

pm.iterationData.get(variableName:String):Function → *

イテレーションデータ変数をオブジェクトで返す：

pm.iterationData.toObject():Function → Object

iterationData オブジェクトを JSON 形式に変換する：

pm.iterationData.toJSON():Function → *

指定された変数を削除する：

pm.iterationData.unset(key:String):Function

リクエストデータとレスポンスデータを使ったスクリプティング

pm.request、pm.response、pm.info、pm.cookies など、様々なメソッド群が Postman スクリプトのリクエストデータとレスポンスデータへのアクセスを提供します。さらに pm.sendRequest を使ってリクエストを送ることもできます。

リクエストデータを使ったスクリプティング

pm.request オブジェクトはスクリプトが実行されているリクエストのデータへのアクセスを提供します。Pre-request スクリプトの場合、このオブジェクトはこれから実行されるリクエストであり、Post-response スクリプトの場合は実行済みのリクエストです。

pm.request オブジェクトの Pre-request スクリプトを使用して、実行前にリクエストの設定の様々な部分を変更することができます。

pm.request オブジェクトは以下のプロパティとメソッドを提供します：

リクエストURL

pm.request.url:Url

現在のリクエストのヘッダーのリスト：

pm.request.headers:HeaderList

HTTP リクエストメソッド：

pm.request.method:String

リクエストボディのデータ。このオブジェクトは不変で、スクリプトから変更することはできない：

pm.request.body:RequestBody

現在のリクエストに、指定された名前と値を持つヘッダーを追加する：

pm.request.headers.add(header:Header):Function

例：

pm.request.headers.add({
  key: "client-id",
  value: "abcdef"
});

指定した名前のリクエストヘッダーを削除する：

pm.request.headers.remove(headerName:String):Function

指定されたヘッダー名と値を挿入する（ヘッダーが存在しない場合、すでに存在するヘッダーは新しい値に更新される）：

pm.request.headers.upsert({key: headerName:String, value: headerValue:String}):Function

詳細は Postman Collection SDK Request reference を参照してください。

レスポンスデータを使ったスクリプティング

pm.response オブジェクトは、Post-response タブに追加されたスクリプトにおいて、現在のリクエストに対するレスポンスで返されたデータへのアクセスを提供します。

pm.response オブジェクトは以下のプロパティとメソッドを提供します：

レスポンスのステータスコード：

pm.response.code:Number

ステータスのテキスト文字列：

pm.response.status:String

レスポンスヘッダーのリスト：

pm.response.headers:HeaderList

レスポンスの受信に要した時間（ミリ秒）：

pm.response.responseTime:Number

受信したレスポンスのサイズ：

pm.response.responseSize:Number

レスポンステキスト：

pm.response.text():Function → String

レスポンス JSON。受け取ったプロパティの詳細を取得するために使用できる：

pm.response.json():Function → Object

詳細は Postman Collection SDK Response reference を参照してください。

リクエスト情報を使ったスクリプティング

pm.info オブジェクトは、名前、リクエストID、反復回数を含む、リクエストとスクリプト自体に関連するデータを提供します。

pm.info オブジェクトは以下のプロパティとメソッドを提供します：

イベント。スクリプトがリクエストのどこで実行されているかに応じて prerequest か test になる：

pm.info.eventName:String

現在のイテレーションの値：

pm.info.iteration:Number

実行予定のイテレーション回数の合計：

pm.info.iterationCount:Number

実行中のリクエストの保存名：

pm.info.requestName:String

実行中のリクエストを識別する一意の GUID：

pm.info.requestId:String

リクエスト Cookie を使ったスクリプティング

pm.cookies オブジェクトはリクエストに関連付けられた Cookie のリストへのアクセスを提供します。

pm.cookies オブジェクトは以下のプロパティとメソッドを提供します：

リクエストされたドメインに（名前で指定された）特定の Cookie が存在するかどうかをチェックする：

pm.cookies.has(cookieName:String):Function → Boolean

指定した Cookie の値を取得する：

pm.cookies.get(cookieName:String):Function → String

オブジェクト内のすべての Cookie とその値のコピーを取得する。リクエストドメインとパスに定義されているすべての Cookie を返す：

pm.cookies.toObject():Function → Object

詳細は Postman Collection SDK Cookie List reference を参照してください。

pm.cookies.jar を使って、リクエスト Cookie へのアクセスにドメインを指定することもできます。

pm.cookies.jar メソッド群を使ってプログラムによるアクセスを有効にするには、まず Cookie の URL を allowlist に追加してください。

Cookie ジャーオブジェクトにアクセスする：

pm.cookies.jar():Function → Object

例：

const jar = pm.cookies.jar();
// Cookie メソッド...

名前と値を使用して Cookie を設定する：

jar.set(URL:String, cookieName:String, cookieValue:String, callback(error, cookie)):Function → Object

PostmanCookie または互換性のあるオブジェクトを使用して Cookie を設定する：

jar.set(URL:String, { name:String, value:String, httpOnly:Bool }, callback(error, cookie)):Function → Object

例：

const jar = pm.cookies.jar();
jar.set("httpbin.org", "session-id", "abc123", (error, cookie) => {
  if (error) {
    console.error(`エラーが発生しました: ${error}`);
  } else {
    console.log(`Cookie は保存されました: ${cookie}`);
  }
});

Cookie ジャーから特定の URL の Cookie を取得する：

jar.get(URL:String, cookieName:String, callback(error, value)):Function → Object

Cookie ジャーから特定の URL のすべての Cookie を取得する。Cookie はコールバック関数で利用できる：

jar.getAll(URL:String, callback(error, cookies)):Function

特定の URL の Cookie を削除する：

jar.unset(URL:String, cookieName:String, callback(error)):Function → Object

Cookie ジャーから特定の URL のすべての Cookie を消去する：

jar.clear(URL:String, callback(error)):Function → Object

特定の URL の Cookie をクリアしてから、続けて Cookie を設定する：

jar.clear(URL:String, callback(error) => {
  jar.set(URL:String, cookieName:String, cookieValue:String, callback(error, cookie)):Function → Object
}):Function → Object

Cookie ジャーに対する関数呼び出しは非同期に実行されます。関数を順番に実行するには、コールバック関数を使用してください。

詳細は Postman Collection SDK Cookie reference を参照してください。

スクリプトからリクエストを送信する

pm.sendRequest メソッドを使用すると、Pre-request スクリプトや Post-response スクリプトから非同期にリクエストを送信することができます。これにより、計算を実行したり複数のリクエストを同時に送信したりする場合に、それぞれの処理の完了を待たずにバックグラウンドでロジックを実行することができます。コールバック関数を追加して、Postman がレスポンスを受信したときにコードが応答できるようにすれば、処理がブロックされる問題を回避できます。そして、レスポンスデータに対して必要な追加処理を行うことができます。

pm.sendRequest メソッドに URL 文字列を渡すか、ヘッダー、メソッド、ボディ、その他を含む完全なリクエスト設定を JSON で指定することができます。

// プレーンな文字列の URL の例
pm.sendRequest('https://postman-echo.com/get', (error, response) => {
  if (error) {
    console.log(error);
  } else {
  console.log(response);
  }
});

// 本格的なリクエストの例
const postRequest = {
  url: 'https://postman-echo.com/post',
  method: 'POST',
  header: {
    'Content-Type': 'application/json',
    'X-Foo': 'bar'
  },
  body: {
    mode: 'raw',
    raw: JSON.stringify({ key: 'これは json です' })
  }
};
pm.sendRequest(postRequest, (error, response) => {
  console.log(error ? error : response.json());
});

// テストを含む例
pm.sendRequest('https://postman-echo.com/get', (error, response) => {
  if (error) {
    console.log(error);
  }

  pm.test('レスポンスは問題なく処理できる', () => {
    pm.expect(error).to.equal(null);
    pm.expect(response).to.have.property('code', 200);
    pm.expect(response).to.have.property('status', 'OK');
  });
});

詳しくはリクエスト定義とレスポンス構造のリファレンスドキュメントを参照してください。

リクエストのパスと名前を取得する

pm.execution.location プロパティを使って、フォルダーやコレクションを含むリクエストの完全なパスを配列形式で取得することができます。例えば、コレクション C1 のフォルダー F1 にある R1 という名前のリクエストに対して、以下の Post-response スクリプトコードは ["C1", "F1", "R1"] を返します：

console.log(pm.execution.location);
// リクエストのフルパスを配列形式で返す。例：
// ["C1", "F1", "R1"]

現在の要素の名前を取得するには、pm.execution.location.current プロパティを使用します。例えば、F1 という名前のフォルダーの Pre-request スクリプトに以下のコードを追加すると、F1 が返されます：

console.log(pm.execution.location.current);
// 現在の要素の名前を返す。例：
// F1

スクリプトで pm.execution.location と pm.execution.location.current プロパティを使用すると、リクエストが送信されたときに何の項目が実行されるかを知ることができます。この情報により、API テストやコレクション構造内の現在の場所に合わせたロジックや操作をスクリプトに実装することができます。

Pre-request スクリプトからリクエスト実行をスキップする

pm.execution.skipRequest メソッドを使って、Pre-request スクリプトからリクエストの実行を停止することができます。

pm.execution.skipRequest():Function

リクエスト、コレクション、フォルダーの Pre-request タブで pm.execution.skipRequest メソッドを使うことができます。pm.execution.skipRequest() に到達すると、リクエストは送信されません。Pre-request タブの残りのスクリプトはすべてスキップされ、テストは実行されません。

例：

// 認証トークンが存在しない場合は、このリクエストをスキップする
if (!pm.environment.get('token')) {
    pm.execution.skipRequest()
}

コレクションランナーでは、pm.execution.skipRequest() に到達すると、Postman は現在のリクエストの実行をスキップし（Post-response スクリプトを含む）、次の順番のリクエストに移ります。実行結果には、そのリクエストに対するレスポンスとテストが見つからなかったことが示されます。この動作は Postman Flows、Newman、Postman CLI にも当てはまります。

pm.execution.skipRequest メソッドの使用はリクエスト、コレクション、フォルダーの Post-response タブではサポートされておらず、何の効果もありません。また、次のようなコンソールエラーが発生します：TypeError: pm.execution.skipRequest is not a function

JSON Schema でレスポンスデータを検証する

jsonSchema メソッドを使って、レスポンスデータを JSON Schema で検証するテストアサーションを書くことができます。Postman は Ajv JSON Schema バリデーターのバージョン 6.12.5 を使用して、レスポンスデータを JSON Schema で検証します。

テストアサーションを書くには、pm.response オブジェクトと Chai Assertion Library BDD 構文を使用して、レスポンスで返されるデータにアクセスします。

jsonSchema メソッドは、第一引数に JSON Schema をオブジェクトとして受け取ります。また、第二引数にはオプションの Ajv オプションのオブジェクトを受け取ります。

pm.response.<bdd-syntax>.jsonSchema(schema, options);

Postman では、リクエストの Scripts タブなどで JSON Schema を定義できます。そして、定義した JSON Schema に対してレスポンスデータのプロパティを検証するテストを書くことができます。

以下の例では、JSON Schema は、レスポンスデータに boolean データ型の「alpha」というプロパティを持たせることを要求しています。レスポンスデータにこのプロパティがないか、異なるデータ型である場合、テストは失敗します。この例では、BDD 構文 to.have を使用してアサーションを表現しています。

const schema = {
  "type": "object",
  "properties": {
    "alpha": {
      "type": "boolean"
    }
  },
  "required": ["alpha"]
};

pm.test('レスポンスは有効', function() {
  pm.response.to.have.jsonSchema(schema);
});

ワークフローのスクリプティング

コレクションランナーまたは Newman を使用するとき、pm.execution.setNextRequest メソッドを使ってリクエストワークフローを構築することができます。

setNextRequest は送信を使ってリクエストを実行するときには効果がないことに注意してください。コレクションを実行するときにのみ効果があります。

コレクションを実行するとき（コレクションランナーや Newman を使うとき）、Postman はデフォルトの順番か、実行をセットアップするときに指定した順番でリクエストを実行します。しかし、pm.execution.setNextRequest を使ってこの実行順序を上書きし、次に実行するリクエストを指定することができます。

このリクエスト（コレクションで定義されたリクエスト名、例えば「顧客の取得」）の後に指定されたリクエストを実行する：

pm.execution.setNextRequest(requestName:String):Function

指定されたリクエスト（pm.info.requestId が返すリクエスト ID）をこのリクエストの後に実行する：

pm.execution.setNextRequest(requestId:String):Function

例：

// 別のリクエスト呼び出し中のスクリプト：
//pm.environment.set('next', pm.info.requestId)
pm.execution.setNextRequest(pm.environment.get('next'));

Postman ビジュアライゼーションのスクリプティング

Postman ビジュアライザーでレスポンスデータを表示するテンプレートを指定するには pm.visualizer.set を使用します。

pm.visualizer.set(layout:String, data:Object, options:Object):Function

layout（必須）
- Handlebars HTML テンプレート文字列
data（オプション）
- テンプレートにバインドする JSON オブジェクトで、テンプレート文字列の中でアクセスできる
options（オプション）
- Handlebars.compile() のオプションオブジェクト

例：

var template = `<p>{{res.info}}</p>`;
pm.visualizer.set(template, {
    res: pm.response.json()
});

Postman ビジュアライゼーションにレスポンスデータを組み込む

Postman ビジュアライザーテンプレート文字列内では、pm.getData を使用してレスポンスデータを取得します。

pm.getData(callback):Function

コールバック関数は2つのパラメータを受け付けます：

error
- エラーの詳細
data
- pm.visualizer.set によってテンプレートに渡されたデータ

使用例：

pm.getData(function (error, data) {
  var value = data.res.info;
});

テストアサーションを書く

pm.test(testName:String, specFunction:Function):Function → Object

pm.test を使って、Pre-request スクリプトや Post-response スクリプトの中でテストの仕様を書くことができます。テストは名前とアサーションを含みます。Postman はテストの結果をレスポンスの一部として出力します。

pm.test メソッドは pm オブジェクトを返し、呼び出しを連鎖させることができます。以下のサンプルテストはレスポンスが有効かどうかをチェックします。

pm.test("レスポンスは問題なく処理できる", function () {
  pm.response.to.not.be.error;
  pm.response.to.have.jsonBody('');
  pm.response.to.not.have.jsonBody('error');
});

非同期関数をテストするために、オプションのコールバックを pm.test に渡すことができます。

pm.test('非同期テスト', function (done) {
  setTimeout(() => {
    pm.expect(pm.response.code).to.equal(200);
    done();
  }, 1500);
});

コード内の特定の場所から実行されたテストの総数を取得する：

pm.test.index():Function → Number

pm.expect メソッドを使って、ChaiJS expect BDD 構文を使ってレスポンスデータに対するアサーションを書くことができます。

pm.expect(assertion:*):Function → Assertion

pm.response.to.have.* と pm.response.to.be.* を使ってアサーションを構築することもできます。

その他のアサーションについてはテストのサンプルを参照してください。

パッケージライブラリからパッケージをインポートする

pm.require メソッドを使って、HTTP リクエスト、コレクション、フォルダーの Pre-request スクリプトや Post-response スクリプトの中に、チームのパッケージライブラリからパッケージをインポートすることができます。パッケージの内容はパーソナルワークスペース、プライベートワークスペース、チームワークスペースからのみ実行されます。パッケージライブラリを使用すると、ワークスペース内のスクリプトやテストを再利用できます。パッケージライブラリを使用してスクリプトとテストを再利用する方法については、こちらを参照してください。

pm.require メソッドは、パッケージライブラリ内のパッケージ名を受け取ります。パッケージに呼び出したい関数やオブジェクトがある場合は、メソッドを変数として宣言してください。パッケージにコードか pm オブジェクトのインスタンスしかない場合は、メソッドを変数として宣言する必要はありません。

const variableName = pm.require('@team-domain/package-name');

variableName.functionName();

外部ライブラリを使用する

require(moduleName:String):Function → *

require メソッドを使うと、サンドボックスに組み込みのライブラリモジュールを使うことができます。利用可能なライブラリの一覧を、対応するドキュメントへのリンクとともに以下に示します。

ajv
atob
btoa
chai
cheerio
crypto-js
csv-parse/lib/sync
lodash（組み込みの _ オブジェクト v3.10.1 がデフォルトでサンドボックスに存在します。最新版を読み込むには require を使ってください。）
moment
postman-collection
tv4
uuid
xml2js

以下の NodeJS モジュールもサンドボックス内で使用できます：

ライブラリを使用するには、require メソッドを呼び出し、パラメータとしてモジュール名を渡し、メソッドからの戻りオブジェクトを変数に代入してください。