Scripting API

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[]): number

Calls fn once after ms milliseconds, returning an id for clearTimeout.

setInterval(fn, ms)

setInterval(fn: Function, ms?: number, ...args: any[]): number

Calls fn every ms milliseconds, returning an id for clearInterval.

clearTimeout(id)

clearTimeout(id: number): void

Cancels a timeout that setTimeout started.

clearInterval(id)

clearInterval(id: number): void

Stops an interval that setInterval started.

Encoding

btoa(text)

btoa(text: string): string

Encodes text as Base64. The text can contain only Latin-1 characters.

atob(base64)

atob(base64: string): string

Decodes a Base64 string back to text.

xml2Json(xml)

xml2Json(xml: string): object

Parses an XML string into a JavaScript object.

Random values

crypto.randomUUID()

crypto.randomUUID(): string

Returns a random version 4 UUID string.

crypto.getRandomValues(array)

crypto.getRandomValues(array: TypedArray): TypedArray

Fills a typed array with cryptographically secure random values and returns it.

Libraries

require(module)

require(module: string): any

Loads 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] = passed

Records a test called name that passes when passed is truthy.

Unsupported globals

tv4

tv4

Postman'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.