Scripts

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.globals and pm.variables, including replaceIn() and dynamic variables such as {{$guid}}.
  • pm.request, its headers, URL and body, which pre-request scripts can change.
  • pm.response, with code, status, headers, json(), text(), responseTime and to assertions such as pm.response.to.have.status(200).
  • pm.test, pm.expect (chai), and pm.response.to.have.jsonSchema().
  • pm.sendRequest, with a callback or as a promise.
  • pm.cookies, pm.info and pm.execution.skipRequest().
  • The older API: postman.setEnvironmentVariable() and the other postman functions, tests["name"] = …, responseBody, responseCode, responseHeaders and environment.
  • require() for the libraries Postman bundles: chai, lodash, crypto-js, moment, uuid, Ajv, xml2js and cheerio, as well as xml2Json(), atob() and btoa().

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 BrunoIn Relay
Collection runner: pm.iterationData, pm.info.iteration, pm.execution.setNextRequest(), bru.runnerRelay 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.authThrows 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.visualizerThrows an error. Relay doesn't render visualizations.
pm.vaultThrows an error. Mark variables as secret to keep their values on your Mac.
pm.require() and package librariesThrows an error. Use require() with one of the bundled libraries.
pm.response.streamThrows an error. Use pm.response.text(), or pm.response.events() for an event stream.
tv4Throws an error. Use pm.response.to.have.jsonSchema(schema).
bru.runRequest(), bru.cwd()Throw an error.
bru.getProcessEnv(), process.envScripts can't read environment variables of the system. bru.getProcessEnv() returns undefined, and process isn't defined.
Node modules, Buffer, fsNot available. Scripts run without Node, and require() loads only the bundled libraries.
Setting folder variablesScripts 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.sendRequest sends a request exactly as written: it doesn't resolve {{name}} tokens or apply the collection's authentication. Use pm.variables.replaceIn() for the URL and add headers yourself.
  • Writing to pm.environment while no environment is active, or to pm.collectionVariables from 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