Scripting API

Postguy runs pre-request and post-response scripts in an embedded QuickJS engine. The scripting surface is implemented as Rust closures in crates/script. This page lists every global and member.

• For when scripts run, their order, and how failures are shown, see Scripts and tests.
• For the {{$name}} generators you can use in request text, see Dynamic variables.

Phases

The request's Tests tab runs in the post-response phase, after the post-response scripts. It runs the enabled assertions in order first, then the Tests script.

• Each script runs inside its own function. const and let names never collide between the collection, folder and request scripts. Share data through variables, not JS scope.
• After a script finishes, queued promise callbacks and setTimeout callbacks are drained before the next script starts.
• A thrown error is recorded as a failure with the script's origin label and line number.
• A failing pre-request script stops the remaining pre-request scripts of that run.
• A failing post-response script does not stop the later ones, unless a limit (time, cancel) tripped.

Globals

console, atob, btoa, timers

• console.log/info/warn/error/debug(...args) joins arguments with a space. Objects are rendered as JSON. A line is cut at 16 KiB with … (truncated). Lines past the line limit are dropped.
• btoa(text) throws InvalidCharacterError: btoa only encodes Latin-1 text for characters above U+00FF.
• atob(text) ignores whitespace and optional padding and throws InvalidCharacterError: the string to be decoded is not correctly encoded on bad input. The result is a Latin-1 string.
• setTimeout(fn, delay?, ...args) returns a numeric id. The delay is not waited: callbacks run after the script body, ordered by delay and then by creation. Timers scheduled from timers run in later rounds. clearTimeout(id) cancels one.

pm

Variable scopes

pm.globals, pm.collectionVariables, pm.environment, pm.variables and pm.iterationData share the same methods. Values are stored as text: strings as-is, everything else through JSON.stringify. The limit is 1 MiB.

pm.variables.get looks in this order, and the first match wins: local values, runtime variables (pg.setVar), iteration data, environment, folder variables, collection variables, globals.

Request

pm.request is read-only after the response:

A key/value object without a key throws expected an object with a key and a value.

Response

pm.response exists only in post-response scripts. It is a plain snapshot:

Cookies

Tests and requests

pm.sendRequest options:

• A URL string, or { url, method, header, body }.
• url is a string or an object with toString.
• method defaults to GET.
• header is an array of {key, value} or a plain object.
• body is { mode: "raw" | "urlencoded" | "formdata", raw | urlencoded | formdata }.

The response has the same shape as pm.response, but without to. A failed send passes an Error to the callback, or rejects the promise.

It throws these errors:

• pm.sendRequest was called more than 10 times, after the limit.
• the script was cancelled, when cancelled.
• pm.sendRequest expects a URL or an options object, for any other argument.

Flow control

See Collection runner for how the runner applies them.

// Pre-request: sign the request and skip it when a flag is off
const stamp = Date.now().toString();
pm.variables.set("stamp", stamp);
pm.request.headers.upsert({ key: "X-Stamp", value: stamp });
if (pm.environment.get("dryRun") === "true") pm.execution.skipRequest();

// Post-response: assert and chain
pm.test("created", () => pm.response.to.have.status(201));
pm.test("has id", () => pm.expect(pm.response.json()).to.have.property("id"));
pm.collectionVariables.set("userId", String(pm.response.json().id));
pm.execution.setNextRequest("Fetch user");

Assertions

pm.expect(value) (also expect(value)) returns an assertion. Failures throw an AssertionError whose message is expected <value> to <description> (or to not <description> after not). Values that are cyclic or too large fail with value is too deeply nested or too large.

Chain words

These words return the assertion unchanged: to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, own, all, any.

Flags: not negates the next check. deep makes equal, include, property and oneOf compare structurally.

Terminals

These properties run the check when read, for example pm.expect(x).to.be.true.

Methods

Number comparisons on a non-number throw expected <value> to be a number. A missing argument throws the assertion needs an argument.

pm.expect(pm.response.json().items).to.be.an("array").and.have.lengthOf(2);
pm.expect({ a: 1, b: [2] }).to.eql({ a: 1, b: [2] });
pm.expect("abc").to.match(/b/);
pm.expect(5).to.be.within(1, 10);

pm.response.to

Response assertions use the same chain words, not and deep. They throw there is no response in a pre-request script when used without a response.

Terminals (status class and content type):

Methods:

pm.test("json ok", () => {
  pm.response.to.be.ok;
  pm.response.to.be.json;
  pm.response.to.have.header("content-type", "application/json");
  pm.response.to.have.jsonBody("data.items.0.id", 1);
});

pg

pg contains every member of pm (the same values) and these additions. It does not add postman.

Variables (also on bru)

Bruno-style methods. They call the same scopes as pm:

set* methods accept a third options argument and ignore it.

Request methods (on pg.request and req)

pg.request also keeps the pm.request members. After the response, setters throw <label> is read-only in post-response scripts, where the label is req, pg.request or pm.request.

Flow control

pg.assets

Read-only access to the collection's Assets folder (see Collections). Paths use / and are relative to the folder root. A path that climbs above the root throws path <p> leaves the collection assets.

Requests that are not saved in a collection throw assets are only available for requests saved in a collection.

pg.report

Adds custom columns to run reports (see Collection runner).

Limits: keys up to 128 characters (pg.report keys may be at most 128 characters), at most 100 fields (pg.report holds at most 100 fields).

pg.report.set("tenant", pg.getEnvVar("tenant"));
pg.report.set("latencyMs", pm.response.responseTime);

Bruno compatibility

Postguy accepts the Bruno script globals, so scripts from imported Bruno folders run. There is no Bruno export.

bru members:

Unsupported bru calls throw <name> is not supported in Postguy scripts:

req

The request methods plus accessors that read and write the same values: req.url (string), req.method, req.headers (snapshot object; assigning merges each entry into the headers) and req.body (parsed JSON or string; assigning calls setBody).

res

res (post-response only) is both a function and an object.

test("token present", () => {
  expect(res.status).to.equal(200);
  bru.setVar("token", res("data.token"));
});

Node-style shims

Postguy does not embed Node. The shims are Rust closures over the collection's Assets folder.

require

Modules receive exports, require, module, __filename and __dirname.

• Modules are cached per run, so dependency cycles see the partial module.exports.
• A module that throws is not cached.
• A missing module throws Cannot find module '<spec>' in the collection assets: <detail>.
• At most 64 modules load per run.
• Each source is limited to 8 MiB and must be UTF-8.

fs (read-only virtual file system)

The root / is the collection's Assets folder.

Every writing function (writeFileSync, appendFileSync, mkdirSync, unlinkSync, rmSync, rmdirSync, renameSync, copyFileSync, truncateSync, chmodSync, symlinkSync, openSync, writeSync, createWriteStream, mkdtempSync and the callback forms writeFile, appendFile, mkdir, unlink, rm, rmdir, rename, copyFile, truncate, chmod, symlink, open, write) exists and throws fs.<name> is not available in Postguy scripts (scripts can only read collection assets).

path

POSIX only: join, resolve (with / as the working directory), normalize, dirname, basename(path, ext?), extname, isAbsolute, sep (/).

crypto

Only crypto.randomUUID().

Buffer

Encodings: utf8 (utf-8), base64, base64url, hex, latin1 (binary). Others throw Buffer encoding '<name>' is not supported in Postguy scripts. Base64 decoding is lenient (both alphabets, optional padding).

Limits

These are the defaults of Limits in crates/script/src/lib.rs. The wall-clock budget covers all scripts of one run.

A user cancel stops a running script with the script was cancelled. Scripts have no file system, process or network access, except pm.sendRequest and read-only Assets. An engine error or panic becomes a recorded failure, never a crash.