Migrating scripts from Postman and Bruno
Run your existing Postman and Bruno scripts in Relay and learn what's different.
Overview
Relay's scripting API follows Postman's: pm is another name for Relay's relay object, with the same members and shapes, so most Postman scripts run unchanged. Relay also provides Bruno's bru, req and res objects, and the test and expect functions both tools use.
The differences come from how Relay works: it sends one request at a time rather than running collections, it runs scripts without Node, and it keeps some features, such as authentication and cookies, in the app rather than in scripts.
Bring over Postman scripts
When you import a Postman collection with File > Import > Postman Collection…, Relay brings its scripts with it, at every level:
- A collection's, folder's or request's pre-request script becomes its Before Request script.
- Its test script becomes its After Response script.
When an item has several scripts for one event, Relay joins them in order, and it leaves out scripts that are disabled in Postman. When the collection has scripts, its collection variables stay on the imported collection, so pm.collectionVariables finds them.
Imported scripts don't run until you allow them. Review each one in its Scripts tab and click Allow. See Allowing scripts to run.
You can also paste a Postman script into a Scripts tab. Scripts you paste are allowed straight away.
Know what works in Postman scripts
These parts of Postman's API work as they do in Postman:
pm.environment,pm.collectionVariables,pm.globalsandpm.variables, includingreplaceIn()and dynamic variables such as{{$guid}}.pm.request, its headers, URL and body, which pre-request scripts can change.pm.response, withcode,status,headers,json(),text(),responseTimeandtoassertions such aspm.response.to.have.status(200).pm.test,pm.expect(chai), andpm.response.to.have.jsonSchema().pm.sendRequest, with a callback or as a promise.pm.cookies,pm.infoandpm.execution.skipRequest().- The older API:
postman.setEnvironmentVariable()and the otherpostmanfunctions,tests["name"] = …,responseBody,responseCode,responseHeadersandenvironment. require()for the libraries Postman bundles: chai, lodash, crypto-js, moment, uuid, Ajv, xml2js and cheerio, as well asxml2Json(),atob()andbtoa().
Relay adds a few things Postman doesn't have: expect also has Jest's matchers such as toBe and toEqual, assert records soft assertions outside a test, relay.workspaceVariables reads and writes the workspace's variables, and relay.response.events() returns a streamed response's server-sent events.
Bring over Bruno scripts
Relay doesn't import Bruno collections, but you can paste Bruno scripts into a Scripts tab. bru, req and res work as in Bruno and use the same variables and request as relay:
// Bruno post-response script
test("Status is 200", () => {
expect(res.getStatus()).toBe(200);
});
bru.setEnvVar("token", res.body.token);In Relay, bru.setVar() sets a value that lasts only until the send ends. To keep a value for later requests, use bru.setEnvVar(). For every member, see bru.
Know what's different
| In Postman or Bruno | In Relay |
|---|---|
Collection runner: pm.iterationData, pm.info.iteration, pm.execution.setNextRequest(), bru.runner | Relay sends one request at a time. Iteration data is empty and the iteration is always 0 of 1. setNextRequest() and bru.runner.stopExecution() have no effect, and Relay notes that in the Console. |
pm.request.auth | Throws an error. Set authentication in the Auth tab, or add an Authorization header in a pre-request script. |
pm.cookies.jar() | Throws an error. Relay keeps cookies in each workspace's cookie jar, which you edit from Edit Workspaces… in the workspace menu. |
pm.visualizer | Throws an error. Relay doesn't render visualizations. |
pm.vault | Throws an error. Mark variables as secret to keep their values on your Mac. |
pm.require() and package libraries | Throws an error. Use require() with one of the bundled libraries. |
pm.response.stream | Throws an error. Use pm.response.text(), or pm.response.events() for an event stream. |
tv4 | Throws an error. Use pm.response.to.have.jsonSchema(schema). |
bru.runRequest(), bru.cwd() | Throw an error. |
bru.getProcessEnv(), process.env | Scripts can't read environment variables of the system. bru.getProcessEnv() returns undefined, and process isn't defined. |
Node modules, Buffer, fs | Not available. Scripts run without Node, and require() loads only the bundled libraries. |
| Setting folder variables | Scripts can read folder variables but can't set them. |
An unsupported member throws an error whose message names it and says it isn't supported in Relay scripts. The error appears in the Tests tab with a link to the line, so you can find what to change.
A few other things behave in a particular way in Relay:
pm.sendRequestsends a request exactly as written: it doesn't resolve{{name}}tokens or apply the collection's authentication. Usepm.variables.replaceIn()for the URL and add headers yourself.- Writing to
pm.environmentwhile no environment is active, or topm.collectionVariablesfrom a draft, doesn't save anything; Relay writes a warning to the Console. - Variable values are text. Objects you set are saved as JSON, and
get()returns a string. - Each phase has a time limit, the Script Timeout in Relay > Settings > Requests, which is 30 seconds by default.
See Also
- Importing Postman collections and environments: Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.
- Allowing scripts to run: Review and allow scripts that changed outside Relay before they run.
- Scripting API: The objects and functions available to request scripts.
- bru: Bruno's script API, with its
reqandresobjects.