LoginSignup
3
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@nagix(草薙 昭彦)inPostman

Postman テストスクリプトリファレンス

Last updated at Posted at 2024-05-13

本記事は、Postman JavaScript reference の日本語訳です（2025年4月16日更新）。

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

スクリプトで変数を使う

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

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

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

変数スコープには、変数を参照する際に 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.vault で Postman Vault の Vault シークレットにアクセスできます。

Postman は pm.variables を使って Vault シークレットにアクセスしたり操作したりすることをサポートしていません。

次のようにスクリプトの中で変数を使用することができます：

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

  • pm.variables.has(variableName:String):function // Boolean

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

  • pm.variables.get(variableName:String):function

Postman はスコープのない変数の値の取得をサポートしています。

Postman 変数の値に + 演算子を使って文字列を追加します：

  • String + 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

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

環境変数を編集するには、その環境の Editor 権限が必要です。

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

アクティブな環境の名前を取得します：

  • pm.environment.name:String

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

  • pm.environment.has(variableName:String):function // Boolean

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

  • pm.environment.get(variableName:String):function

アクティブな環境の変数の値に + 演算子を使って文字列を追加します：

  • String + 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

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

コレクション変数を編集するには、そのコレクションの Editor 権限が必要です。

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

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

  • pm.collectionVariables.has(variableName:String):function // Boolean

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

  • pm.collectionVariables.get(variableName:String):function

コレクション変数の値に + 演算子を使って文字列を追加します：

  • String + 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

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

グローバル変数を編集するには、Workspace Editor 権限が必要です。

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

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

  • pm.globals.has(variableName:String):function // Boolean

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

  • pm.globals.get(variableName:String):function

グローバル変数の値に + 演算子を使って文字列を追加します：

  • String + 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

イテレーションデータの値に + 演算子を使って文字列を追加します：

  • String + pm.iterationData.get(variableName:String):function

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

  • pm.iterationData.toObject():function // Object

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

  • pm.iterationData.toJSON():function

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

  • pm.iterationData.unset(key:String):function

スクリプトで Valut シークレットを使う

Postman Vault の Valut シークレットにアクセスしたり操作したりするには、スクリプトで pm.vault メソッドを使用します。pm.vault メソッドを使用するには、Postman Vault のスクリプトでの Valut シークレットのサポートを有効にします。pm.vault メソッドを使用するリクエストを送信したり、コレクションを手動で実行したりすると、スクリプトを使用してコレクションやワークスペースに Valut シークレットへのアクセスを許可または拒否するプロンプトが表示されます。Postman Vault 内の Valut シークレットを安全に保つには、信頼できるスクリプトのみを実行するようにしてください。

外部 Valut にリンクされた Valut シークレットにアクセスするメソッドを使用するには、Postman デスクトップアプリを使用する必要があります。

pm.vault メソッドは HTTP コレクションとリクエストの Pre-request と Post-response スクリプトでサポートされています。このメソッドは、コレクションランナーを使用して手動でコレクションを実行するときのスクリプトでもサポートされています。スケジュールされたコレクションの実行、モニター、Postman CLI、Newman は pm.vault メソッドをサポートしていません。また、pm.vault メソッドは GraphQL や gRPC などの非 HTTP リクエストにも対応していません。

スクリプトから Valut シークレットにアクセスするために Postman ウェブアプリを使用している場合は、Postman デスクトップエージェントを使用してください。Postman では、最新の変更や改良を受けるために最新版の Postman デスクトップエージェントを使用することを推奨しています。

pm.vault メソッドはスクリプト内で非同期に実行されます。各メソッドは、メソッドの完了または失敗を表す Promise オブジェクトも返します。各 pm.vault メソッドの前に await 演算子を追加して、Promise とその結果の値を待ちます。await 演算子のないメソッドはスクリプト内で実行されるかもしれませんが、期待した動作をしない可能性があることに注意してください。例をご覧ください：

console.log(await pm.vault.get("secretKey"));
await pm.vault.set("secretKey", "newValue");
await pm.vault.unset("secretKey");

スクリプトでの Valut シークレットのサポートを有効にする

スクリプトで pm.vault メソッドを使って Valut シークレットにアクセスしたり操作したりするには、まず Postman Vault でこのオプションを有効にする必要があります。

サポートを有効にせずにスクリプトで Valut シークレットにアクセスしたり操作しようとすると、Postman コンソールにエラーが表示されます。また、pm.vault メソッドの後に来るコードは、リクエスト送信時に実行されません。

スクリプトでの Valut シークレットのサポートを有効にするには、以下のようにします：

  1. Postman Vault を開きます。
  2. Postman Vault の右上にある Vault 設定を選択します。
  3. 設定タブで、スクリプトでのサポートを有効にするの横にあるトグルをオンにし、Enable を選択して確定します。

スクリプトでの Vault シークレットのサポートを有効にすると、HTTP コレクションやリクエストで pm.vault メソッドを使用できるようになります。メソッドを使用するリクエストを送信するとき、またはコレクションを手動で実行するときに、コレクションまたはワークスペースが Valut シークレットにアクセスすることを許可または拒否するプロンプトが表示されます。

スクリプトに Valut シークレットへのアクセスを許可する

スクリプトで pm.vault メソッドを使用するリクエストを送信したり、コレクションを手動で実行したりすると、コレクションまたはワークスペースに Valut シークレットへのアクセスを許可または拒否するよう求められます。Postman では、アクセスを許可したコレクションやワークスペースからのみ、これらのスクリプトを実行できます。Postman Vault から、Valut シークレットへのコレクションまたはワークスペースのアクセスを管理できます。Postman Vault 内の Valut シークレットを安全に保つには、信頼できるスクリプトのみを実行するようにしてください。

スクリプトでの Valut シークレットのサポートが有効になっていることを確認してください。有効にしないと、スクリプトを使用してコレクションまたはワークスペースに Valut シークレットへのアクセスを許可または拒否するプロンプトが表示されません。

新しい HTTP リクエストを作成し、コレクションに保存する前にリクエストを送信すると、スクリプトを使用して Valut シークレットにアクセスするためのリクエストが許可されます。リクエストがコレクションに保存されていない場合、Postman は Valut シークレットへのアクセスを許可または拒否するプロンプトを表示しません。

コレクションに Valut シークレットへのアクセスを許可または拒否するには、以下の手順を実行します：

  1. Postman Vault を開きます。
  2. サイドバーでコレクションを選択し、Valut シークレットにアクセスまたは操作するスクリプトを含む HTTP コレクションまたはリクエストを開きます。
  3. リクエストを送信するか、コレクションを手動で実行します。
  4. このコレクションのみを選択します。
  5. アクセスを許可するか拒否するかを選択します：
    • アクセス権を許可 - コレクション内のすべてのリクエストに対して、スクリプトを使用した Valut シークレットへのアクセスを許可する場合に選択します。
    • アクセス権を拒否 - コレクション内のすべてのリクエストに対して、スクリプトを使用した Valut シークレットへのアクセスを拒否する場合に選択します。

Postman は、コレクション内のリクエストに対して再度プロンプトを表示しません。Postman Vault から、Valut シークレットへのアクセスを許可または拒否したコレクションを管理できます。

ワークスペースに自分の Valut シークレットへのアクセスを許可または拒否するには、以下の手順を実行します：

  1. Postman Vault を開きます。
  2. サイドバーでコレクションを選択し、Valut シークレットにアクセスまたは操作するスクリプトを含む HTTP リクエストを開きます。
  3. 送信を選択してリクエストを送信します。
  4. ワークスペース全体を選択します。
  5. アクセスを許可するか拒否するかを選択します：
    • アクセス権を許可 - ワークスペース内のすべてのコレクションとリクエストに対して、スクリプトを使用した Valut シークレットへのアクセスを許可する場合に選択します。
    • アクセス権を拒否 - ワークスペース内のすべてのコレクションとリクエストに対して、スクリプトを使用した Valut シークレットへのアクセスを拒否する場合に選択します。

ワークスペース内のコレクションやリクエストに対して、Postman から再度プロンプトが表示されることはありません。ワークスペースに Valut シークレットへのアクセスを許可または拒否した場合、Postman Vault からそのワークスペースを管理できます。

コレクションまたはワークスペースの Valut シークレットへのアクセスを管理するには、以下の手順を実行します：

  1. Postman Vault を開きます。
  2. Postman Vault の右上にある Vault 設定を選択します。
  3. アクセス権を管理タブを選択します。
  4. コレクションまたはワークスペースの横にある以下のいずれかを選択します：
    • アクセス権をリセット - コレクションまたはワークスペース内のスクリプトに Valut シークレットへのアクセスを許可するかどうかの決定をリセットする場合に選択します。コレクションまたはワークスペースでリクエストを送信すると、Valut シークレットへのアクセスを許可するか拒否するかを再度尋ねるプロンプトが表示されます。
    • アクセス権を許可 - コレクションまたはワークスペース内のすべてのスクリプトに、Valut シークレットへのアクセスを許可する場合に選択します。このオプションは、以前にコレクションまたはワークスペース内のスクリプトによる Valut シークレットへのアクセスを拒否した場合に使用できます。

コレクションまたはワークスペースから Postman Vault へのアクセスを拒否した場合、拒否されたスコープでリクエストを送信すると、Postman コンソールにエラーが表示されます。また、pm.vault メソッドの後に来るコードは、拒否されたスコープでリクエストを送信したときに実行されません。

pm.vault メソッドを使用する

スクリプトで pm.vault メソッドを使用すると、Valut シークレットにアクセスして操作できます。

スクリプトでの Valut シークレットのサポートを有効にし、コレクションまたはワークスペース内のスクリプトに、スクリプトを使用して Valut シークレットにアクセスする権限を与えていることを確認してください。そうしないと、Postman コンソールでエラーが発生します。

指定した名前の Valut シークレットの値を返すには：

  • await pm.vault.get(secretKey:String):function

Valut シークレットの値に + 演算子を用いて文字列を追加します：

  • String + await pm.vault.get(secretKey:String):function

指定された名前と値で Valut シークレットを設定します：

  • await pm.vault.set(secretKey:String, secretValue:*):function

Postmanは、外部 Vault にリンクされた Valut シークレットの値の設定をサポートしていません。

指定された Valut シークレットを削除するには：

  • await pm.vault.unset(secretKey:String):function

console.log を使用して Valut シークレットの値をログに記録する場合、デフォルトではその値は Postman コンソールでマスクされます。コンソールで Valut シークレットの値のマスクを解除するには、Postman Vault を開き、設定を選択し、設定タブの Valut シークレットをマスクの横のトグルをオフにします。

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

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.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、反復回数を含む、リクエストとスクリプト自体に関連するデータを提供します。このオブジェクトは以下のプロパティとメソッドを提供します：

イベント。スクリプトがリクエストのどこで実行されているかに応じて 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 のリストへのアクセスを提供します。このオブジェクトは以下のプロパティとメソッドを提供します：

リクエストされたドメインに（名前で指定された）特定の 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

pm.cookies.jar を使って、ドメインを指定してリクエスト Cookie にアクセスすることができます。pm.cookies.jar メソッド群を使ってプログラムによるアクセスを有効にするには、まずドメインを 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

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

詳細は 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()

リクエスト、コレクション、フォルダーの 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 では、リクエストのスクリプトタブなどで 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 を使ってこの実行順序を上書きし、次に実行するリクエストを指定することができます。

このリクエストの後に指定されたリクエストを実行します（requestName はコレクションのリクエスト名。例えば「Get customers」）：

  • pm.execution.setNextRequest(requestName:String):function

このリクエストの後に指定されたリクエストを実行します（requestId は 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（必須）
  • data（オプション）
    • テンプレートにバインドする JSON オブジェクトで、テンプレート文字列の中でアクセスできる
  • options（オプション）

使用例：

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

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

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

  • pm.getData(callback):function

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

使用例：

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

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

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

  • pm.test(testName:String, specFunction:function):function

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.* を使ってアサーションを構築することもできます。

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

スクリプトからパッケージをインポートする

pm.require メソッドを使って、HTTP リクエスト、コレクション、フォルダーの Pre-request スクリプトや Post-response スクリプトの中に、チームのパッケージライブラリもしくは外部パッケージレジストリからパッケージをインポートすることができます。

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

パッケージライブラリからパッケージをインポートするには、以下の書式を使用します：

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

variableName.functionName();

パッケージレジストリから外部パッケージをインポートするには、以下の書式を使用します：

// npm からインポートされたパッケージ
const npmVariableName = pm.require('npm:package-name@version-number');

npmVariableName.functionName()

// jsr からインポートされたパッケージ
const jsrVariableName = pm.require('jsr:package-name@version-number');

jsrVariableName.functionName()

グローバルオブジェクトを使用する

Postman はスクリプト内で以下の JavaScript オブジェクトをグローバルにサポートしています：

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

require メソッドを使うと、サンドボックスに組み込みのライブラリモジュールを使うことができます。ライブラリを使用するには、require メソッドを呼び出し、パラメータとしてモジュール名を渡し、メソッドからの戻りオブジェクトを変数に代入してください：

  • require(moduleName:String):function

サンドボックスで使用可能なサポートライブラリは以下の通りです：

以下のライブラリは非推奨であり、もうサポートされていません：

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

Postman は buffer モジュールで次をサポートしていません：isAscii、isUtf8、resolveObjectURL、transcode、copyBytesFrom。

3
5
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
5

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?