Request
Thereq variable represents the HTTP request object and is automatically available inside your scripting and testing context. It provides methods to access and modify the current request’s properties such as URL, method, headers, body, and other configuration options before the request is sent to the server.
The
req object is available in pre-request scripts and test scripts, allowing you to modify request properties before execution and access them after completion.req object.
| Method | Description |
|---|---|
| req.getUrl() | Get the current request URL. |
| req.setUrl(url) | Set the current request URL. |
| req.getHost() | Get the hostname from the request URL. |
| req.getPath() | Get the path from the request URL. |
| req.getQueryString() | Get the raw query string from the request URL. |
| req.getPathParams() | Extract path parameters using the path template. |
| req.getAuthMode() | Get the current authentication mode. |
| req.getMethod() | Get the current request method. |
| req.setMethod(method) | Set the current request method. |
| req.getName() | Get the current request name. |
| req.getTags() | Get the current request tags as an array of strings. |
| req.getHeader(name) | Get the request header by name. |
| req.getHeaders() | Get all request headers. |
| req.setHeader(name, value) | Set a request header by name. |
| req.setHeaders(headers) | Set multiple request headers. |
| req.deleteHeader(name) | Remove a request header by name. |
| req.deleteHeaders([names]) | Remove multiple request headers by name. |
| req.getBody(options?) | Get the current request body/payload (supports raw option). |
| req.setBody(body) | Set the request body/payload. |
| req.setMaxRedirects(count) | Set the maximum number of redirects to follow. |
| req.getTimeout() | Get the current timeout value of the request. |
| req.setTimeout(milliseconds) | Set a timeout for the request. |
| req.getExecutionMode() | Get the current active execution mode (runner or standalone). |
| req.getExecutionPlatform() | Get the platform on which the request is being executed (app or cli). |
| req.onFail(callback) | Handle request errors with a custom callback function. |
req.
req.getUrl()
Get the current request URL.
req.setUrl(url)
Set the current request URL.
req.getHost()
Get the hostname from the request URL.
req.getPath()
Get the path from the request URL.
req.getQueryString()
Get the raw query string from the request URL.
req.getPathParams()
Extract path parameters using the path template defined in the request.
req.getMethod()
Get the current request method.
req.setMethod(method)
Set the current request method.
req.getName()
Get the current request name.
req.getAuthMode()
Get the current authentication mode.
req.getTags()
Get the current request tags as an array of strings. Useful for conditional logic, filtering, or organizing requests by tag.
Returns: Array of strings representing the request tags.
req.getHeader(name)
Get the request header by name.
req.getHeaders()
Get all request headers.
req.setHeader(name, value)
Set a request header by name.
req.setHeaders(headers)
Set multiple request headers.
req.deleteHeader(name)
Remove a request header by name.
req.deleteHeaders(names)
Remove multiple request headers by name. Pass an array of header names.
req.getBody(options?)
Get the current request body/payload.
Parameters:
options(object, optional):raw(boolean) — whentrue, returns the raw body without parsing; otherwise returns the parsed body (default).
req.setBody(body)
Set the request body/payload.
req.setTimeout(milliseconds)
Set a timeout for the request.
req.getTimeout()
Get the current timeout value of the request.
req.setMaxRedirects(count)
Set the maximum number of redirects to follow.
req.getExecutionMode()
Get the current active execution mode: runner (collection run) or standalone (single request).
req.getExecutionPlatform()
Get the platform: app (desktop) or cli (Bruno CLI).
req.onFail(callback)
Handle request errors with a custom callback. error includes details about the failure.
The
onFail function is only available in Developer mode and should be called in pre-request scripts. When using Bruno CLI (v3.0.0+), pass the --sandbox=developer flag.Response
Theres variable represents the HTTP response object and is automatically available inside your scripting and testing context after a request is executed. It contains all the information about the response received from the server, including status codes, headers, body data, and timing information.
The
res object is only available in post-request scripts and test scripts, as it contains the response data from the completed request.res object.
| Property / Method | Description |
|---|---|
| res.status | The HTTP response status code (e.g., 200, 404, 500). |
| res.statusText | The HTTP response status text (e.g., “OK”, “Not Found”). |
| res.headers | An object containing all response headers. |
| res.body | The response body data (automatically parsed as JSON if applicable). |
| res.responseTime | The total time taken for the request in milliseconds. |
| res.url | The final response URL (after following redirects). |
| res.getStatus() | Get the response status code. |
| res.getStatusText() | Get the response status text. |
| res.getHeader(name) | Get a specific response header by name. |
| res.getHeaders() | Get all response headers. |
| res.getBody() | Get the response body data. |
| res.setBody(body) | Set the response body data. |
| res.getResponseTime() | Get the response time in milliseconds. |
| res.getUrl() | Get the response URL (final URL after redirects). |
| res.getSize() | Get the response size in bytes (returns object with body, headers, total). |
The
body property is automatically parsed as JSON if the response has a JSON content type. For other content types, it will be a string.res object.
res.status
The HTTP response status code (e.g., 200, 404, 500).
res.statusText
The HTTP response status text (e.g., "OK", "Not Found").
res.headers
An object containing all response headers.
res.body
The response body data (automatically parsed as JSON when the response has a JSON content type).
res.responseTime
The total time taken for the request in milliseconds.
res.url
The final response URL (after following redirects).
res.getStatus()
Get the response status code.
res.getStatusText()
Get the response status text.
res.getHeader(name)
Get a specific response header by name.
res.getHeaders()
Get all response headers.
res.getBody()
Get the response body data.
res.setBody(body)
Set the response body data.
res.getUrl()
Get the response URL after redirects (same information as res.url).
res.getResponseTime()
Get the response time in milliseconds.
res.getSize()
Get the response size in bytes. Returns { body, headers, total }.
Environments
Thebru object provides methods for managing environments in Bruno. Environments allow you to maintain different configurations for various deployment stages (development, staging, production, etc.).
Environment variables are specific to the selected environment and can be accessed across all requests in your collection.
| Method | Description |
|---|---|
| bru.getEnvName() | Retrieves the environment name. |
| bru.hasEnvVar(key) | Checks if the environment variable exists. |
| bru.getEnvVar(key) | Retrieves the value of an environment variable. |
| bru.setEnvVar(key, value) | Sets a new environment variable. |
| bru.deleteEnvVar(key) | Deletes a specific environment variable. |
| bru.getAllEnvVars() | Retrieves all environment variables as an object. |
| bru.deleteAllEnvVars() | Deletes all environment variables in the current environment. |
| bru.getGlobalEnvVar(key) | Get the Bruno global environment variable. |
| bru.setGlobalEnvVar(key, value) | Set the Bruno global environment variable. |
| bru.getAllGlobalEnvVars() | Retrieves all global environment variables as an object. |
bru.getEnvName()
Retrieves the current environment name.
bru.getEnvVar(key)
Get the Bruno environment variable for the selected environment.
bru.setEnvVar(key, value, options?)
Set the Bruno environment variable. By default, variables are in-memory only; use { persist: true } to save to disk.
Parameters: key (string), value (any), options.persist (boolean, optional).
bru.hasEnvVar(key)
Check if the environment variable exists.
bru.deleteEnvVar(key)
Delete a specific environment variable.
bru.getAllEnvVars()
Get all environment variables in the current environment as an object.
bru.deleteAllEnvVars()
Delete all environment variables in the current environment.
bru.getGlobalEnvVar(key)
Get a Bruno global (workspace) environment variable.
bru.setGlobalEnvVar(key, value)
Set a Bruno global environment variable.
bru.getAllGlobalEnvVars()
Get all global environment variables as an object.
Variables
Bruno provides a comprehensive variable system that allows you to manage and access different types of variables throughout your scripts. Variables are resolved in a specific order of precedence, with runtime variables taking the highest priority.Variable precedence (highest to lowest): Runtime Variables → Request Variables → Folder Variables → Collection Variables → Environment Variables
| Method | Description |
|---|---|
| bru.getProcessEnv(key) | Fetches the process environment variable for a given key. |
| bru.getCollectionName() | Retrieves the current collection name. |
| bru.getCollectionVar(key) | Retrieves the collection-level variable for the key. |
| bru.hasCollectionVar(key) | Checks if a collection variable exists. |
| bru.getFolderVar(key) | Fetches a folder-specific variable by key. |
| bru.getRequestVar(key) | Retrieves the value of a request variable. |
| bru.hasVar(key) | Checks if a variable exists. |
| bru.getVar(key) | Retrieves the value of a variable. |
| bru.setVar(key, value) | Sets a new variable with a key-value pair. |
| bru.getAllVars() | Retrieves all runtime variables as an object. |
| bru.deleteVar(key) | Deletes a specific variable. |
| bru.deleteAllVars() | Deletes all runtime variables. |
| bru.getOauth2CredentialVar(key) | Retrieves an OAuth2 credential variable value. |
| bru.resetOauth2Credential(credentialId) | Resets an OAuth2 credential so it can be re-authorized. |
| bru.getSecretVar(key) | Retrieves a secret variable from a configured secret manager. |
bru.getProcessEnv(key)
Get a Node process.env value (useful for secrets without committing them to the collection).
bru.getCollectionVar(key)
Get a collection-level variable.
bru.hasCollectionVar(key)
Check if a collection variable exists.
bru.getCollectionName()
Retrieve the name of the current collection.
bru.getFolderVar(key)
Get a folder variable.
bru.getRequestVar(key)
Get a request variable.
bru.hasVar(key)
Check if a runtime variable exists.
bru.getVar(key)
Get a runtime variable.
bru.setVar(key, value)
Set a runtime variable.
bru.deleteVar(key)
Delete a runtime variable.
bru.deleteAllVars()
Delete all runtime variables.
bru.getAllVars()
Get all runtime variables as an object.
bru.getOauth2CredentialVar(key)
Retrieve an OAuth2 credential variable (e.g. access token).
bru.resetOauth2Credential(credentialId)
Reset an OAuth2 credential so it can be re-authorized.
bru.getSecretVar(key)
Retrieve a secret from a configured secret manager. Key pattern: <secret-name>.<key-name>.
Secrets must be configured in your collection’s secret manager settings before they can be accessed via
bru.getSecretVar(). See Secret Managers for setup details.Runner
The Runner API provides methods to control the execution flow of your collection runs. These methods are specifically designed for use within the collection runner context, allowing you to skip requests, change execution order, or stop the run entirely. Here are all available runner-related methods:| Method | Description |
|---|---|
| bru.setNextRequest(requestName) | Sets the next request to execute. |
| bru.runner.setNextRequest(requestName) | Alter the order of requests by specifying the next request. |
| bru.runner.skipRequest() | Skip the execution of the current request. |
| bru.runner.stopExecution() | Terminate a collection run. |
bru.setNextRequest(requestName)
Change runner order: after the current request completes, jump to the named request (skipping intermediates). Use in a post-request or test script only. Use the request’s display name (not a folder path). Pass null to stop the run.
bru.runner.setNextRequest(requestName)
Same behavior as bru.setNextRequest — specify the next request to run after the current one.
bru.runner.skipRequest()
Skip the current request. Use in a pre-request script during a collection run.
bru.runner.stopExecution()
Stop the collection run. Callable from pre-request, post-response, or test scripts during a run.
Utilities
The Utilities API provides a collection of helper functions for common tasks such as making HTTP requests, working with cookies, managing tests, and other utility operations. Here are all available utility methods:| Method | Description |
|---|---|
| bru.sendRequest(options, callback) | Sends a programmatic HTTP request within your script. |
| bru.sleep(milliseconds) | Pauses execution for the specified duration. |
| bru.interpolate(string) | Evaluates dynamic variables within a string. |
| bru.disableParsingResponseJson() | Disables JSON response parsing for the request. |
| bru.isSafeMode() | Detects whether the script is running in Safe Mode. |
| bru.cwd() | Returns the current working directory. |
| bru.runRequest(requestPathName) | Executes a request by its path name. |
| bru.getAssertionResults() | Retrieves the results of assertions. |
| bru.getTestResults() | Fetches the test results. |
| bru.cookies.jar() | Creates a cookie jar instance for managing cookies. |
bru.sendRequest(options, callback?)
Send a programmatic HTTP request from your script. Supports method, url, headers, data, timeout, httpsAgent, and optional callback(err, res); also supports await without a callback.
Bruno applies your TLS (custom CA, SSL verification), proxy, and client certificate settings to
bru.sendRequest() unless you override with httpsAgent.fs):
bru.sleep(milliseconds)
Pause execution for the given duration.
bru.interpolate(string)
Resolve Bruno dynamic variables (e.g. {{$randomFirstName}}) inside a string.
bru.disableParsingResponseJson()
Disable automatic JSON parsing for this request’s response; use in a pre-request script.
bru.cwd()
Returns the current working directory (collection context).
bru.isSafeMode()
Returns true in Safe Mode, false in Developer Mode. Use to branch when features need require() or filesystem access.
bru.runRequest(requestPathName)
Run another request in the collection by path/name and await its response.
bru.getTestResults()
Get test results for the current request (use in test scripts).
bru.getAssertionResults()
Get assertion results for the current request (use in test scripts).
Create a jar with
bru.cookies.jar(), then call methods on the returned instance.bru.cookies.jar()
Create a cookie jar instance.
jar.setCookie(url, name, value) / jar.setCookie(url, cookieObject)
Set one cookie: either (url, name, value) or (url, { key, value, domain, path, expires, maxAge, secure, httpOnly, sameSite }).
jar.setCookies(url, cookies)
Set multiple cookies from an array of cookie objects.
jar.getCookie(url, name)
Get a cookie by name; returns the cookie object or null.
jar.hasCookie(url, name, callback?)
Returns a Promise of true/false, or invokes callback(error, exists) if provided.