bru
Bruno's script API, with its `req` and `res` objects.
Declaration
bru
req
resOverview
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): voidSets a variable in the active environment.
getEnvVar(key)
bru.getEnvVar(key: string): string | undefinedReturns a variable from the active environment.
hasEnvVar(key)
bru.hasEnvVar(key: string): booleanReturns whether the active environment has the variable.
deleteEnvVar(key)
bru.deleteEnvVar(key: string): voidRemoves a variable from the active environment.
getEnvName()
bru.getEnvName(): string | undefinedReturns the active environment's name.
setVar(key, value)
bru.setVar(key: string, value: any): voidSets a variable for this send only.
getVar(key)
bru.getVar(key: string): string | undefinedReturns a variable from any scope, highest precedence first.
hasVar(key)
bru.hasVar(key: string): booleanReturns whether any scope defines the variable.
deleteVar(key)
bru.deleteVar(key: string): voidRemoves a variable set for this send.
deleteAllVars()
bru.deleteAllVars(): voidRemoves every variable set for this send.
getCollectionVar(key)
bru.getCollectionVar(key: string): string | undefinedReturns a variable from the request's collection.
getFolderVar(key)
bru.getFolderVar(key: string): string | undefinedReturns a variable from the request's folders, innermost first.
getGlobalEnvVar(key)
bru.getGlobalEnvVar(key: string): string | undefinedReturns a global variable.
setGlobalEnvVar(key, value)
bru.setGlobalEnvVar(key: string, value: any): voidSets a global variable.
getRequestVar(key)
bru.getRequestVar(key: string): undefinedReturns undefined, since Relay requests don't have variables of their own.
getProcessEnv(key)
bru.getProcessEnv(key: string): undefinedReturns undefined, since Relay scripts can't read process environment variables.
interpolate(text)
bru.interpolate(text: string | object): string | objectReplaces {{name}} tokens in text with their variables' values.
Run details
getRequestName()
bru.getRequestName(): stringReturns the name of the request being sent.
getCollectionName()
bru.getCollectionName(): string | undefinedReturns 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> | undefinedSends 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): voidPicks 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): voidControls 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(): anyReturn 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): voidReplace 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: anyThe 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: numberThe status code, status text, headers with lowercase names, body (parsed when it's JSON) and time in milliseconds.
res(path)
res(path: string): anyReturns 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
- Migrating scripts from Postman and Bruno: Run your existing Postman and Bruno scripts in Relay and learn what's different.
- 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.