スクリプトAPI

スクリプトは、リクエストの送信前（リクエスト前）またはレスポンスの到着後（テスト）に実行されるJavaScriptです。 PostmanのAPIであるpmを使うので、Postmanコレクションのスクリプトはそのまま動作します。このページでは、そのすべてを一覧にしています。 アプリでの書き方と結果の読み方は、スクリプトとテストを参照してください。

スクリプトが実行される場所Copy Anchor Link

• リクエストのスクリプトはスクリプトタブにあり、リクエストの横に<slug>.pre.jsと<slug>.test.jsとして保存されます。フォルダとワークスペースにもスクリプトがあります（_folder.pre.js、_folder.test.js）。ワークスペースのファイルを参照してください。
• 各リクエストでは、最初にワークスペースのスクリプトが、次に外側から順に各フォルダのスクリプトが、最後にリクエスト自身のスクリプトが実行されます。1つのイベントのすべてのスクリプトは、1つのサンドボックスを共有します。
• MCPの呼び出しにはスクリプトがありません。
• Echolotの外部（読み込み、Git、別のエディタ）から来たスクリプトは、スクリプトを確認…で読んでからスクリプトを信頼した場合にだけ実行されます。
• コマンドラインツールも、echolot runとecholot sendでスクリプトを実行します。

サンドボックスCopy Anchor Link

スクリプトは、Echolot内のサンドボックス化されたJavaScriptエンジン（QuickJS）で実行されます。ファイルシステムも、独自のネットワークも、Node.jsモジュールもありません。外に出る唯一の方法は、Echolotを通じて送信するpm.sendRequestです。

例外を投げたり制限を超えたりしたスクリプトは、スクリプトエラーとして報告され、失敗したテストとして数えられます。

pm.testCopy Anchor Link

pm.test("Status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Has products", () => {
  const body = pm.response.json();
  pm.expect(body.items).to.be.an("array").that.is.not.empty;
});

リクエスト前スクリプトのテストも数えられます。

pm.expectCopy Anchor Link

pm.expect(value)（またはexpect(value)）は、Chai形式のアサーションです。失敗は、Chaiと同じ形で表示されます：expected 401 to equal 200。

チェーンワードは、読みやすくするためのもので、何もしません：to、be、been、is、that、which、and、has、have、with、at、of、same、but、does、still、also。

フラグ：not（否定）、deep（値で比較）、nested（propertyでのドット区切りのパス）、own、any、all、ordered。

レスポンスに対しては、expectはPostmanのレスポンスのアサーションも取れます：pm.expect(pm.response).to.have.status(200)、.header(name)、.jsonBody(…)、.body(…)、.responseTime(…)、およびpm.expect(pm.response).to.be.ok、.success、.json、以下のその他のものです。

pm.responseCopy Anchor Link

テストスクリプトでの、レスポンスです。

レスポンスのアサーション：pm.response.to.have.…とpm.response.to.not.have.…：

pm.response.to.be.…：

pm.requestCopy Anchor Link

リクエストです。リクエスト前スクリプトでは、これに加えた変更が送信される内容になります。

pm.request.headers.upsert({ key: "X-Request-Id", value: pm.variables.replaceIn("{{$guid}}") });
pm.request.url.addQueryParams("per_page=50");

urlオブジェクトには、protocol、host（ラベルの配列）、port、path（セグメントの配列）、query（リスト）、hash、そしてgetHost()、getPath()、getQueryString()、getPathWithQuery()、getRemote()、update(text)、addQueryParams(…)、removeQueryParams(…)、toString()があります。 変更しなかったURLは、{{variables}}を含め、正確なテキストを保ちます。Echolotは、スクリプトの後でそれらを解決します。

変数Copy Anchor Link

各スコープには、get(name)、has(name)、set(name, value)、unset(name)、clear()、toObject()、replaceIn(text)があります。setはオブジェクトをJSONテキストにします。

pm.variables.getは、次の順序で探します：ローカルの値、データの行、フォルダとリクエストの変数、環境、ワークスペース、グローバル。

// Pre-request: sign the body
const signature = CryptoJS.HmacSHA256(pm.request.body.raw, pm.environment.get("apiSecret")).toString();
pm.request.headers.upsert({ key: "X-Signature", value: signature });

// Test: keep the new order's ID for the next requests
pm.collectionVariables.set("orderId", pm.response.json().id);

setが保持するもの。スクリプトが設定した値は、Postmanの「現在の値」です。アプリではウインドウが開いている間、コマンドラインではそのコマンドの間だけ保持され、リクエストを解決するときは、そのスコープの保存済みの値より優先されます。 ワークスペースのファイルには書き込まれません。レスポンスの値を保存するには、レスポンスのキャプチャを使います。pm.variables.setによるローカルの値は、実行の開始時に忘れられます。

replaceIn(text)は、上記のスコープから{{variables}}を埋め込みます。動的な値のうち、{{$guid}}、{{$randomUUID}}、{{$timestamp}}、{{$isoTimestamp}}、{{$randomInt}}は認識します。それ以外の{{$…}}はそのまま残され、Echolotがリクエストを送信するときに解決されます。

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

スクリプトから、Echolotを通じて別のリクエストを送信します。ほかのリクエストと同じように、プロキシ、証明書、Cookieが適用されます。

pm.sendRequest("https://demo.echolot.dev/v1/categories", (error, response) => {
  if (error) { console.error(error); return; }
  pm.collectionVariables.set("firstCategory", response.json().items[0].id);
});

// or with a promise
pm.sendRequest({
  url: pm.variables.replaceIn("{{baseURL}}/auth/token"),
  method: "POST",
  header: { "Content-Type": "application/json" },
  body: { mode: "raw", raw: JSON.stringify({ email: "heidi@alpenglow.ch", password: pm.environment.get("password") }) }
}).then(response => {
  pm.environment.set("token", response.json().access_token);
});

• 最初の引数は、URL、またはurl、method（デフォルトはGET）、header（{ key, value }の配列、オブジェクト、またはリスト）、bodyを持つオブジェクトです。
• bodyは、文字列、{ mode: "raw", raw }、{ mode: "urlencoded", urlencoded: [{ key, value }] }、または{ mode: "graphql", graphql: { query, variables } }です。後ろの2つは、指定がなければContent-Typeが設定されます。
• URL内の{{variables}}は、リクエストの環境で埋め込まれます。
• コールバックは(error, response)を受け取ります。responseはpm.responseと同様です。コールバックがない場合は、Promiseを返します。
• このリクエストには独自の認証がなく（ワークスペースの認証は適用されません）、スクリプトも実行されません。
• エージェントのpm.sendRequestは、ほかの送信と同じように、エージェントの承認を通ります。

実行の制御Copy Anchor Link

pm.cookiesCopy Anchor Link

このやり取りのCookie。リクエストが送信したものと、レスポンスが設定したものです。リストで、pm.cookies.get(name)、has(name)、toObject()、そして{ name, key, value }を返すone(name)があります。

リストCopy Anchor Link

ヘッダー、クエリパラメータ、Cookieは、Postmanのプロパティリストです。

consoleCopy Anchor Link

console.log、info、warn、error、debug、traceは、リクエストのコンソールに書き出され、コマンドラインでは── console ──の下に書き出されます。オブジェクトはJSONで書き出されます。

タイマーCopy Anchor Link

setTimeout、setInterval、setImmediateは、スクリプトの後に、遅延の順序で関数を実行します。実際に待つことはありません。setIntervalは一度だけ実行されます。clearTimeoutなどで取り消せます。

JSON SchemaCopy Anchor Link

方法は3つあり、すべてEcholot独自のJSON Schemaバリデータを使います。

const schema = {
  type: "object",
  required: ["sku", "price"],
  properties: { sku: { type: "string" }, price: { type: "object" } }
};

// Chai
pm.expect(pm.response.json()).to.have.jsonSchema(schema);

// ajv
const Ajv = require("ajv");
const validate = new Ajv().compile(schema);
pm.test("Matches the schema", () => pm.expect(validate(pm.response.json()), JSON.stringify(validate.errors)).to.be.true);

// tv4
pm.test("Matches the schema", () => pm.expect(tv4.validate(pm.response.json(), schema)).to.be.true);

JSON Schemaのチェックは、スクリプトなしでも行えます。テストタブのJSON Schemaチェックです。

ライブラリCopy Anchor Link

古いPostmanのグローバルCopy Anchor Link

古いコレクションのスクリプトはこれらを使い、そのまま動作します。

使えないものCopy Anchor Link

• ほかのモジュール：上記にないもののrequire（cheerio、xml2js、moment、Node自身のモジュール）は、「The module … is not available in Echolot scripts.」という例外を投げます。
• 実際の待機：タイマーは遅延なしで実行され、fetchもXMLHttpRequestもありません。pm.sendRequestを使ってください。
• ファイルとプロセス：スクリプトはファイルの読み書きもプログラムの起動もできません。
• pm.visualizer.setは受け付けられるため、それを使うスクリプトは動作しますが、Echolotは可視化を表示しません。
• xml2Json、pm.requireとPostmanのパッケージライブラリ、pm.vault。
• ファイル内のシークレット：スクリプトはシークレットの変数をほかの変数と同じように読み取りますが、setした内容がワークスペースのファイルに書き込まれることはありません。