Scripting API

Scripts are JavaScript that runs before a request is sent (pre-request) or after its response arrives (test). They use Postman's pm API, so scripts from Postman collections run as they are. This page lists all of it. For writing them in the app and reading their results, see scripts and tests.

Where scripts runCopy Anchor Link

• A request's scripts are in its Scripts tab, saved as <slug>.pre.js and <slug>.test.js beside the request. Folders and the workspace have scripts too (_folder.pre.js, _folder.test.js); see workspace files.
• For each request, the workspace's script runs first, then each folder's from the outside in, then the request's own. All the scripts of one event share one sandbox.
• MCP calls have no scripts.
• Scripts that came from outside Echolot (an import, Git, another editor) run only once you trust them: Trust Scripts, after reading them with Review Scripts….
• The command-line tool runs scripts too, in echolot run and echolot send.

The sandboxCopy Anchor Link

Scripts run in a sandboxed JavaScript engine (QuickJS) inside Echolot, with no file system, no network of their own and no Node.js modules. The only way out is pm.sendRequest, which sends through Echolot.

A script that throws, or goes over a limit, is reported as a script error, which counts as a failed test.

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;
});

Tests in pre-request scripts count too.

pm.expectCopy Anchor Link

pm.expect(value) (or expect(value)) is a Chai-style assertion. Failures read as Chai's do: expected 401 to equal 200.

Chain words, which read well and do nothing: to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also.

Flags: not (negates), deep (compares by value), nested (dotted paths in property), own, any, all, ordered.

On a response, expect also takes Postman's response assertions: pm.expect(pm.response).to.have.status(200), .header(name), .jsonBody(…), .body(…), .responseTime(…), and pm.expect(pm.response).to.be.ok, .success, .json and the others below.

pm.responseCopy Anchor Link

In test scripts, the response.

Response assertions: pm.response.to.have.… and pm.response.to.not.have.…:

pm.response.to.be.…:

pm.requestCopy Anchor Link

The request. In a pre-request script, changes to it are what gets sent.

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

The url object has protocol, host (an array of labels), port, path (an array of segments), query (a list), hash, and getHost(), getPath(), getQueryString(), getPathWithQuery(), getRemote(), update(text), addQueryParams(…), removeQueryParams(…), toString(). A URL you don't change keeps its exact text, {{variables}} included; Echolot resolves them after the scripts.

VariablesCopy Anchor Link

Each scope has get(name), has(name), set(name, value), unset(name), clear(), toObject() and replaceIn(text). set turns objects into JSON text.

pm.variables.get looks in this order: local values, the data row, folder and request variables, the environment, the workspace, globals.

// 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);

What set keeps. Values that scripts set are Postman's "current values": they last for the window in the app, or for the command on the command line, and win over the saved values of their scope when requests resolve. They are never written to the workspace files. To save a value from a response, use a response capture. Local values from pm.variables.set are forgotten when a run starts.

replaceIn(text) fills in {{variables}} from the scopes above. Of the dynamic values, it knows {{$guid}}, {{$randomUUID}}, {{$timestamp}}, {{$isoTimestamp}} and {{$randomInt}}; every other {{$…}} is left as it is, for Echolot to resolve when it sends the request.

pm.infoCopy Anchor Link

pm.sendRequestCopy Anchor Link

Sends another request from a script, through Echolot: proxies, certificates and cookies apply as for any request.

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);
});

• The first argument is a URL, or an object with url, method (default GET), header (an array of { key, value }, an object, or a list) and body.
• body is a string, { mode: "raw", raw }, { mode: "urlencoded", urlencoded: [{ key, value }] } or { mode: "graphql", graphql: { query, variables } }. The last two set their Content-Type when you don't.
• {{variables}} in the URL are filled in, with the request's environment.
• The callback gets (error, response); response is like pm.response. Without a callback it returns a promise.
• The request has no auth of its own (the workspace's auth doesn't apply) and runs no scripts.
• An agent's pm.sendRequest goes through the agent's approvals, like its other sends.

Controlling a runCopy Anchor Link

pm.cookiesCopy Anchor Link

The cookies of this exchange: those the request sent and those the response set. A list, with pm.cookies.get(name), has(name), toObject(), and one(name) returning { name, key, value }.

ListsCopy Anchor Link

Headers, query parameters and cookies are Postman property lists:

consoleCopy Anchor Link

console.log, info, warn, error, debug and trace write to the request's Console, and on the command line under ── console ──. Objects are written as JSON.

TimersCopy Anchor Link

setTimeout, setInterval and setImmediate run their functions after the script, in the order of their delays, without waiting for real. setInterval runs once. clearTimeout and the others cancel.

JSON SchemaCopy Anchor Link

Three ways, all on Echolot's own JSON Schema validator:

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);

A JSON Schema check also works without a script: the JSON Schema check on the Tests tab.

LibrariesCopy Anchor Link

The old Postman globalsCopy Anchor Link

Scripts from older collections use these, and they work:

What is not thereCopy Anchor Link

• Other modules: require of anything not listed above (cheerio, xml2js, moment, Node's own modules) throws "The module … is not available in Echolot scripts."
• Real waiting: timers run without delay, and there is no fetch or XMLHttpRequest. Use pm.sendRequest.
• Files and processes: scripts can't read or write files or start programs.
• pm.visualizer.set is accepted, so scripts that use it run, but Echolot shows no visualization.
• xml2Json, pm.require and Postman's package library, and pm.vault.
• Secrets in files: scripts read secret variables like any other, but what they set never reaches the workspace files.