Request scripts

Open a request’s Scripts section to write JavaScript that runs before sending or after receiving a response. The Snippets menu and pm. completion list the available APIs.

Scripts run against a snapshot: their request edits affect that send without changing the request draft or saved file. An uncaught pre-request error prevents the request; a failed pm.test does not.

Collection scripts

Click a collection in the sidebar to open its tab. There you can rename it, edit the variables in its environment.toml, and write scripts that run for every request in the collection. Save with the Save button or the save shortcut.

In each phase the collection’s script runs first, then the request’s own script. Both scripts share pm.variables for that send. If the collection’s pre-request script fails, the request is not sent. If its post-response script fails, the request’s own tests still run. The tab stores the scripts in the collection’s .request-eagle-collection.toml.

Reuse a response value

pm.response.to.have.status(200);
pm.environment.set("token", pm.response.json().token);

Other requests in the same collection can then use Bearer {{token}}. Session values last until the workspace closes and are never written to environment.toml.

File values come from the collection’s environment.toml and from the global environment selected in the tab bar. The selected environment’s values take precedence. Global environments are stored in ~/.request-eagle/environments/<name>.toml.

Scripts read and change values in these scopes. A {{name}} reference uses the first one that has the name:

Each scope has the same methods:

Use {{!name}} to send a literal {{name}}.

Make HTTP calls from a script

const login = await pm.sendRequest({
    url: "{{base_url}}/login",
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({username: pm.environment.get("username")}),
});

login.to.have.status(200);
pm.environment.set("token", login.json().token);
pm.request.headers.upsert({key: "Authorization", value: "Bearer {{token}}"});

pm.sendRequest(url) sends GET. The response has code, status, responseTime, headers, text(), json(), and the same assertions as pm.response. HTTP 4xx/5xx statuses are normal responses; transport failures reject.

Subrequests use the primary request’s settings and do not run saved scripts. Like the primary request, they store and send cookies in the cookie jar, so a login subrequest’s session cookie goes with the request that follows. Timers, filesystem access, and fetch are not provided.

Read and change the body

pm.request.body.mode names the body’s type, as in Postman: raw, urlencoded, formdata or file.

Sign and encode values

const body = pm.variables.replaceIn(pm.request.body.raw || "");
const signature = pm.crypto.hmacSha256(pm.environment.get("secret"), body);
pm.request.headers.upsert({key: "X-Signature", value: signature});

Use Postman’s libraries

const CryptoJS = require("crypto-js");
const moment = require("moment");

const timestamp = moment().utc().format();
const signature = CryptoJS.HmacSHA256(timestamp, pm.environment.get("secret"));
pm.request.headers.upsert({key: "X-Timestamp", value: timestamp});
pm.request.headers.upsert({key: "X-Signature", value: CryptoJS.enc.Base64.stringify(signature)});

require loads these libraries, as Postman does:

Other names throw an error.

Read and change cookies

pm.environment.set("session", pm.cookies.get("session"));

pm.cookies lists the cookies of the current exchange: those the request sends, from its Cookie header and the cookie jar, and after the response, with the response’s Set-Cookie headers applied. pm.response.cookies lists only the cookies the response set, with their attributes. Both have get(name), has(name), one(name), all(), count() and toObject().

pm.cookies.jar() reads and changes the cookie jar. As in Postman, its methods report through a callback:

const jar = pm.cookies.jar();
jar.set("https://api.example.com", "session", "abc", error => {
    if (error) throw error;
});
jar.get("https://api.example.com", "session", (error, value) => console.log(value));

Changes made before sending apply to the request. When the cookie jar is off in Settings, pm.cookies lists only the cookies of the exchange and each jar method reports an error; without a callback, the error is logged.

Validate response structure

pm.test("Response matches the schema", () => {
    pm.response.to.have.jsonSchema({
        type: "object",
        required: ["id", "name"],
        properties: {
            id: {type: "integer"},
            name: {type: "string"},
        },
    });
});

For other values, pm.schema.validate(data, schema) returns {valid, errors, truncated}. The default dialect is Draft 2020-12. Local references such as #/$defs/user work; external references are not loaded.

Skip the primary request

if (!pm.environment.get("token")) {
    pm.execution.skipRequest("No access token configured");
}

The primary request and post-response script do not run.

In the Collection Runner, pm.execution.setNextRequest(name) and postman.setNextRequest(name) choose the request that runs next; a request sent on its own ignores them, as in Postman. The legacy postman object also has getEnvironmentVariable, setEnvironmentVariable, clearEnvironmentVariable, getGlobalVariable, setGlobalVariable and clearGlobalVariable.

Know where a script runs

pm.info describes the current execution:

if (pm.info.iteration > 0) {
    pm.execution.skipRequest("Checked in the first iteration");
}

gRPC scripts

A gRPC request’s Scripts section has three scripts:

• Before invoke runs before the method is invoked. It can change the server URL, metadata and message of that call, and pm.execution.skipRequest(reason) cancels it. It runs before server reflection loads the call’s methods, so it can also set the metadata that reflection needs.
• On message runs for each message the server sends, in order.
• After response runs once the server ends the call, including with an error status. It does not run when the call fails without a status, such as when the server is unreachable, or when you cancel it.

The three scripts share pm.variables during the call. A {{$guid}} or other generated value that Before invoke creates or sets keeps that value for the whole call, including stream messages. Collection scripts run only for HTTP requests.

// Before invoke
const auth = await pm.sendRequest({url: "{{base_url}}/login", method: "POST"});
pm.request.metadata.upsert({key: "authorization", value: "Bearer " + auth.json().token});

// On message
pm.test("Every update has an ID", () => {
    pm.expect(pm.message.data).to.have.property("id");
});

// After response
pm.test("Status is OK", () => pm.response.to.have.status("OK"));
pm.test("An update reports success", () => {
    pm.response.messages.to.include({status: "success"});
});
pm.environment.set("orderId", pm.response.messages.idx(0).data.id);

Messages appear as JSON, with lowerCamelCase field names and 64-bit integers as strings.

Message lists are arrays with idx(index), count(), all() and each(callback). Their filter also accepts the fields to match, such as filter({data: {type: "ping"}}).

Limits

Each phase is limited to:

• 2 seconds of active execution, 30 seconds elapsed, and a 32 MiB heap.
• 32 HTTP calls with 4 in flight, 8 MiB per response and 16 MiB in total.
• 500 tests and 500 console entries.
• 1 MiB for crypto, Base64, and schema data, and 64 KiB for a schema.

On message runs once for each received message, with these limits for each run. A call shows up to 500 tests and 500 console entries from all of them. After response sees the latest 8 MiB of messages in each direction.