relay
The root object of the scripting API, also available as `pm`.
Declaration
relayOverview
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: VariableScopeVariables from every scope, highest precedence first. Values you set with set() last for this send only.
environment
relay.environment: VariableScopeThe variables of the workspace's active environment.
collectionVariables
relay.collectionVariables: VariableScopeThe variables of the request's collection.
workspaceVariables
relay.workspaceVariables: VariableScopeThe workspace's default variables.
globals
relay.globals: VariableScopeGlobal variables, shared by every workspace.
iterationData
relay.iterationDataData for a collection runner's iteration, which is always empty in Relay. See Info and execution.
Request and response
request
relay.request: RequestThe request being sent, which a pre-request script can change. See relay.request.
response
relay.response: Response | undefinedThe response that arrived, with its status, headers and body. Post-response scripts only. See relay.response.
cookies
relay.cookies: PropertyListCookies the response set. Post-response scripts only. See relay.cookies.
sendRequest(request, callback)
relay.sendRequest(request: string | object, callback?: (error, response) => void): Promise<Response> | undefinedSends 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): relayRuns fn as a named test, which fails if it throws or its promise rejects. See test.
expect(value)
relay.expect(value: any, message?: string): AssertionStarts a chai or Jest-style assertion about value. See expect.
assert
relay.assertchai's assert functions, recorded as soft assertions outside a test. See assert.
Run details
info
relay.info: objectDetails of the current send, such as the phase and the request's name. See Info and execution.
execution
relay.execution: objectControls 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
- Variable scopes: The variable scopes scripts read and write, from values for this send to globals.
- Global functions: Timers, encoding, random values and the legacy Postman globals available to every script.
- Running scripts before and after requests: Add pre-request and post-response scripts to requests, folders and collections.