Scripting API
The objects and functions available to request scripts.
Overview
Request scripts are JavaScript that runs before a request is sent and after its response arrives. Every script can use the relay object, which holds variable scopes, the request, the response and functions for testing and sending other requests.
Relay scripts are designed to be cross-compatible with Postman scripts. The pm global is another name for the same object, so many scripts written for Postman run in Relay without modification. Additionally, shims for Bruno's bru, req and res objects are there too.
Scripts run in a JavaScript engine without Node or a browser, so there's no process, Buffer, window or fetch. Relay provides timers, Base64 encoding, random values and a set of bundled libraries such as chai, lodash and crypto-js.
Some members only make sense in one phase. A member marked "Post-response scripts only" is undefined or empty in a pre-request script, and one marked "Pre-request scripts only" throws an error in a post-response script.
Topics
Script API
- relay: The root object of the scripting API, also available as
pm. - Variable scopes: The variable scopes scripts read and write, from values for this send to globals.
- relay.request: The request being sent, which pre-request scripts can change.
- relay.response: The response a post-response script checks, with its status, headers and body.
- PropertyList: The list of keys and values behind headers, query parameters, form fields and cookies.
- relay.sendRequest: A function that sends another request from a script and passes back its response.
- relay.cookies: The cookies the response set.
- Info and execution: Details of the current send, and controls for skipping the request.
Testing
- test: A function that runs a named check and records whether it passed.
- expect: A function that starts a chai or Jest-style assertion about a value.
- assert: chai's assert functions, recorded as soft assertions outside a test.
- console: An object that writes messages to the Console in the Tests tab.
Utilities
- Global functions: Timers, encoding, random values and the legacy Postman globals available to every script.
- Libraries: The JavaScript libraries bundled with Relay and how scripts load them.
Bruno compatibility
- bru: Bruno's script API, with its
reqandresobjects.
See Also
- Running scripts before and after requests: Add pre-request and post-response scripts to requests, folders and collections.
- Testing responses: Check responses automatically with tests and assertions.
- Migrating scripts from Postman and Bruno: Run your existing Postman and Bruno scripts in Relay and learn what's different.