Global functions
Timers, encoding, random values and the legacy Postman globals available to every script.
Declaration
setTimeout(fn, ms)
btoa(text)
crypto.randomUUID()
require(module)Overview
Scripts run without Node or a browser, so Relay provides the globals scripts most often need: timers, Base64, random values and a require for the bundled libraries. It also provides the globals of Postman's older scripting API, so older scripts run unchanged.
// Wait a second, then send a request with a fresh id.
await new Promise(resolve => setTimeout(resolve, 1000));
relay.request.headers.upsert({ key: "Idempotency-Key", value: crypto.randomUUID() });Each script runs inside an async function, so you can use await at the top level, and its let and const declarations stay in that script.
Topics
Timers
setTimeout(fn, ms)
setTimeout(fn: Function, ms?: number, ...args: any[]): numberCalls fn once after ms milliseconds, returning an id for clearTimeout.
setInterval(fn, ms)
setInterval(fn: Function, ms?: number, ...args: any[]): numberCalls fn every ms milliseconds, returning an id for clearInterval.
clearTimeout(id)
clearTimeout(id: number): voidCancels a timeout that setTimeout started.
clearInterval(id)
clearInterval(id: number): voidStops an interval that setInterval started.
Encoding
btoa(text)
btoa(text: string): stringEncodes text as Base64. The text can contain only Latin-1 characters.
atob(base64)
atob(base64: string): stringDecodes a Base64 string back to text.
xml2Json(xml)
xml2Json(xml: string): objectParses an XML string into a JavaScript object.
Random values
crypto.randomUUID()
crypto.randomUUID(): stringReturns a random version 4 UUID string.
crypto.getRandomValues(array)
crypto.getRandomValues(array: TypedArray): TypedArrayFills a typed array with cryptographically secure random values and returns it.
Libraries
require(module)
require(module: string): anyLoads a bundled library by name, such as "lodash" or "uuid". See Libraries.
Legacy Postman globals
postman
postman.setEnvironmentVariable(key, value)
postman.getEnvironmentVariable(key)
postman.clearEnvironmentVariable(key)
postman.clearEnvironmentVariables()
postman.setGlobalVariable(key, value)
postman.getGlobalVariable(key)
postman.clearGlobalVariable(key)
postman.clearGlobalVariables()
postman.setNextRequest(name)
postman.getResponseHeader(name)
postman.getResponseCookie(name)Postman's older functions, which call the matching members of relay.environment, relay.globals, relay.execution and relay.response. getResponseCookie(name) returns { name, value }.
environment, globals
environment[name]
globals[name]Read-only objects whose properties are the active environment's variables and the global variables.
responseBody, responseCode, responseHeaders, responseTime, responseCookies
responseBody: string
responseCode: { code: number, name: string, detail: string }
responseHeaders: object
responseTime: number
responseCookies: { name: string, value: string }[]The response's body text, status, headers, time in milliseconds and cookies. Post-response scripts only.
request
request: { url: string, method: string, headers: object, data: string, name: string }The request's URL, method, enabled headers, body text and name.
tests
tests[name] = passedRecords a test called name that passes when passed is truthy.
Unsupported globals
tv4
tv4Postman's older JSON Schema validator. Reading it throws an error; use relay.response.to.have.jsonSchema(schema), which validates with Ajv.
Discussion
Timers and the end of a script
A script isn't finished while it has a timer waiting, so a script that starts an interval and never clears it runs until the Script Timeout setting stops it. Clear intervals when you're done with them. Intervals fire at most once a millisecond.
Sharing values between scripts
Every script of a send runs in the same JavaScript environment, before and after the request, so a property you add to globalThis in a pre-request script is still there in the post-response script. Each send starts afresh. To share values in a documented way, use relay.variables.set(), which also makes them available to the request's {{name}} tokens.
See Also
- Libraries: The JavaScript libraries bundled with Relay and how scripts load them.
- relay: The root object of the scripting API, also available as
pm. - Migrating scripts from Postman and Bruno: Run your existing Postman and Bruno scripts in Relay and learn what's different.