Scripting API

bru

Bruno's script API, with its `req` and `res` objects.

Declaration

bru
req
res

Overview

Relay provides Bruno's bru, req and res objects, so scripts written for Bruno run unchanged. They're built on relay: bru.setEnvVar() sets the same variable as relay.environment.set(), and req reads and changes the same request as relay.request.

// Post-response script
test("Creates the user", () => {
  expect(res.getStatus()).toBe(201);
  expect(res.body.email).toBe("ada@example.com");
});

bru.setEnvVar("userId", res.body.id);

Topics

Variables

setEnvVar(key, value)

bru.setEnvVar(key: string, value: any): void

Sets a variable in the active environment.

getEnvVar(key)

bru.getEnvVar(key: string): string | undefined

Returns a variable from the active environment.

hasEnvVar(key)

bru.hasEnvVar(key: string): boolean

Returns whether the active environment has the variable.

deleteEnvVar(key)

bru.deleteEnvVar(key: string): void

Removes a variable from the active environment.

getEnvName()

bru.getEnvName(): string | undefined

Returns the active environment's name.

setVar(key, value)

bru.setVar(key: string, value: any): void

Sets a variable for this send only.

getVar(key)

bru.getVar(key: string): string | undefined

Returns a variable from any scope, highest precedence first.

hasVar(key)

bru.hasVar(key: string): boolean

Returns whether any scope defines the variable.

deleteVar(key)

bru.deleteVar(key: string): void

Removes a variable set for this send.

deleteAllVars()

bru.deleteAllVars(): void

Removes every variable set for this send.

getCollectionVar(key)

bru.getCollectionVar(key: string): string | undefined

Returns a variable from the request's collection.

getFolderVar(key)

bru.getFolderVar(key: string): string | undefined

Returns a variable from the request's folders, innermost first.

getGlobalEnvVar(key)

bru.getGlobalEnvVar(key: string): string | undefined

Returns a global variable.

setGlobalEnvVar(key, value)

bru.setGlobalEnvVar(key: string, value: any): void

Sets a global variable.

getRequestVar(key)

bru.getRequestVar(key: string): undefined

Returns undefined, since Relay requests don't have variables of their own.

getProcessEnv(key)

bru.getProcessEnv(key: string): undefined

Returns undefined, since Relay scripts can't read process environment variables.

interpolate(text)

bru.interpolate(text: string | object): string | object

Replaces {{name}} tokens in text with their variables' values.

Run details

getRequestName()

bru.getRequestName(): string

Returns the name of the request being sent.

getCollectionName()

bru.getCollectionName(): string | undefined

Returns the name of the request's collection, or undefined for a draft.

Requests and timing

sendRequest(config, callback)

bru.sendRequest(config: string | object, callback?: (error, response) => void): Promise<object> | undefined

Sends another request from an axios-style config, passing its response to callback or a promise.

The config has a url, a method, headers as an object, and data, which is sent as text when it's a string and as JSON otherwise. The response has a status, statusText, headers and data, which is the parsed JSON body or else the body text. The request is sent as relay.sendRequest sends one.

sleep(ms)

bru.sleep(ms: number): Promise<void>

Returns a promise that resolves after ms milliseconds.

Collection runs

setNextRequest(name)

bru.setNextRequest(name: string): void

Picks the collection runner's next request; it has no effect on a single send.

runner

bru.runner.skipRequest(): void
bru.runner.stopExecution(): void
bru.runner.setNextRequest(name: string): void

Controls for a collection run. skipRequest() stops the request from being sent, in pre-request scripts only. stopExecution() and setNextRequest() have no effect on a single send.

The req object

Reading the request

req.getUrl(): string
req.getMethod(): string
req.getName(): string
req.getHeader(name: string): string | undefined
req.getHeaders(): object
req.getBody(): any

Return the request's URL, HTTP method, name, the value of the header called name, the headers as an object of names and values, and the body, parsed when it's JSON.

Changing the request

req.setUrl(url: string): void
req.setMethod(method: string): void
req.setHeader(name: string, value: string): void
req.setHeaders(headers: object): void
req.deleteHeader(name: string): void
req.setBody(body: any): void

Replace the URL or method, set a header (replacing one with the same name), set each header in an object of names and values, remove a header, and replace the body, serializing objects as JSON. Pre-request scripts only.

Properties

req.url: string
req.method: string
req.headers: object
req.body: any

The request's URL, method, headers and body, parsed when it's JSON. Assigning url, method or body changes the request.

The res object

Post-response scripts only. In a pre-request script, res is undefined.

Reading the response

res.getStatus(): number
res.getStatusText(): string
res.getHeader(name: string): string | undefined
res.getHeaders(): object
res.getBody(): any
res.getResponseTime(): number
res.getSize(): { body: number, header: number, total: number }

Return the status code, the status text, the value of the header called name, the headers as an object with lowercase names, the body (parsed when it's JSON), the time in milliseconds, and the sizes in bytes.

Properties

res.status: number
res.statusText: string
res.headers: object
res.body: any
res.responseTime: number

The status code, status text, headers with lowercase names, body (parsed when it's JSON) and time in milliseconds.

res(path)

res(path: string): any

Returns the value at a path such as "data.items[0].id" in the body.

Unsupported members

runRequest(), cwd()

bru.runRequest(path)
bru.cwd()

Calling them throws an error.

Discussion

The first time a script calls bru.setVar() in a send, Relay writes a note to the Console that the value lasts for this send only. To keep a value for later requests, use bru.setEnvVar().

See Also