Scripting API

relay

The root object of the scripting API, also available as `pm`.

Declaration

relay

Overview

Every request script has access to the relay global object. It holds the variable scopes, the request being sent, the response, and functions for testing and for sending other requests. pm is the same object, so pm.environment.get("token") and relay.environment.get("token") do the same thing, and scripts written for Postman run unchanged.

const body = relay.response.json();

relay.test("Returns the new order", () => {
  relay.expect(relay.response.code).to.equal(201);
  relay.expect(body.id).to.be.a("string");
});

relay.environment.set("orderId", body.id);

Topics

Variables

variables

relay.variables: VariableScope

Variables from every scope, highest precedence first. Values you set with set() last for this send only.

environment

relay.environment: VariableScope

The variables of the workspace's active environment.

collectionVariables

relay.collectionVariables: VariableScope

The variables of the request's collection.

workspaceVariables

relay.workspaceVariables: VariableScope

The workspace's default variables.

globals

relay.globals: VariableScope

Global variables, shared by every workspace.

iterationData

relay.iterationData

Data for a collection runner's iteration, which is always empty in Relay. See Info and execution.

Request and response

request

relay.request: Request

The request being sent, which a pre-request script can change. See relay.request.

response

relay.response: Response | undefined

The response that arrived, with its status, headers and body. Post-response scripts only. See relay.response.

cookies

relay.cookies: PropertyList

Cookies the response set. Post-response scripts only. See relay.cookies.

sendRequest(request, callback)

relay.sendRequest(request: string | object, callback?: (error, response) => void): Promise<Response> | undefined

Sends another request, outside history, and passes its response to callback or a promise. See relay.sendRequest.

Tests

test(name, fn)

relay.test(name: string, fn?: () => any): relay

Runs fn as a named test, which fails if it throws or its promise rejects. See test.

expect(value)

relay.expect(value: any, message?: string): Assertion

Starts a chai or Jest-style assertion about value. See expect.

assert

relay.assert

chai's assert functions, recorded as soft assertions outside a test. See assert.

Run details

info

relay.info: object

Details of the current send, such as the phase and the request's name. See Info and execution.

execution

relay.execution: object

Controls what happens to the request, such as skipping it. See Info and execution.

Unsupported members

These Postman members exist so scripts that mention them load, but calling them throws an error that says the member isn't supported in Relay scripts.

visualizer

relay.visualizer.set(template, data)
relay.visualizer.clear()

Postman's response visualizer. Relay doesn't render visualizations.

vault

relay.vault.get(key)
relay.vault.set(key, value)
relay.vault.unset(key)

Postman's vault. To keep a value on your Mac instead of in shared files, mark the variable as secret. See Keeping secrets on your Mac.

require(name)

relay.require(name)

Postman's package library. To load a bundled library, use the global require instead.

See Also