JavaScript API Reference

Bruno offers powerful scripting capabilities that allow you to extend and automate your API testing workflows. Here is the complete set of API reference for the scripting feature in Bruno.

Request

The req 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.

Here is a complete table for all available methods on the req object.

Method	Description
req.getUrl()	Get the current request URL.
req.setUrl(url)	Set the current request URL.
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.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.

Below is the API documentation for the methods available on req

URL Methods

getUrl() - Get the current request URL.
```
let url = req.getUrl();
```

setUrl(url) - Set the current request URL.

req.setUrl("https://api.github.com/search/repositories?q=vue");

HTTP Method

getMethod() - Get the current request method.
```
const method = req.getMethod();
```
setMethod(method) - Set the current request method.
```
req.setMethod("POST");
```

Request Information

getName() - Get the current request name.
```
const name = req.getName();
```
getAuthMode() - Get the current authentication mode.
```
let authMode = req.getAuthMode();
```

getTags() - Get the current request tags as an array of strings. This method allows you to access the tags associated with the current request, which can be useful for conditional logic, filtering, or organizing requests based on their tags. Returns: Array of strings representing the request tags

const tags = req.getTags();
console.log("Request tags:", tags);

// Check if request has specific tags
if (tags.includes("smoke-test")) {
    console.log("This is a smoke test request");
}

// Use tags for conditional logic
if (tags.includes("skip-in-ci")) {
    bru.runner.skipRequest();
}

// Filter based on tags
if (tags.includes("integration-test")) {
    // Run additional integration test logic
    console.log("Running integration test validations");
}

Header Methods

getHeader(name) - Get the request header by name.
```
req.getHeader("transaction-id");
```
getHeaders() - Get all request headers.
```
const headers = req.getHeaders();
```
setHeader(name, value) - Set a request header by name.
```
req.setHeader("content-type", "application/json");
```

setHeaders(headers) - Set multiple request headers.

req.setHeaders({
  "content-type": "application/json",
  "transaction-id": "foobar",
});

Body Methods

getBody(options?) - Get the current request body/payload. Parameters:
- options (object, optional): Configuration options
  - raw (boolean): When true, returns the raw body without any parsing. When false or not provided, returns the parsed body (default behavior).
Examples:
```
// Get parsed body (default)
const body = req.getBody();

// Get raw body without parsing
const rawBody = req.getBody({ raw: true });
```

setBody(body) - Set the request body/payload.

req.setBody({
  username: "john nash",
  password: "governingdynamics",
});

Request Configuration

setTimeout(milliseconds) - Set a timeout for the request.

req.setTimeout(5000); // Sets the timeout to 5000 milliseconds (5 seconds)

getTimeout() - Get the current timeout value of the request.

const timeout = req.getTimeout();
console.log(timeout); // Logs the current timeout value

setMaxRedirects(count) - Set the maximum number of redirects to follow.
```
req.setMaxRedirects(5);
```

Execution Context

getExecutionMode() - Get the current active execution mode of the request. Returns:
- runner: When the request is being executed as part of a collection run
- standalone: When the request is being executed individually
```
const executionMode = req.getExecutionMode();
console.log(`Request is running in ${executionMode} mode`);
```
getExecutionPlatform() - Get the platform on which the request is being executed. Returns:
- app: When running in the Bruno desktop application
- cli: When running through the Bruno CLI
```
const platform = req.getExecutionPlatform();
console.log(`Request is running on ${platform} platform`);
```

Error Handling

onFail(callback) - Handle request errors with a custom callback function. This is useful for implementing custom error handling logic, logging, or taking specific actions when a request fails. Parameters:

error: The error object containing details about the request failure

Example:

// Handle request failures with custom logic
req.onFail((error) => {
  console.error('Request failed:', error.message);
  
  // Log error details for debugging
  console.log('Error details:', {
    status: error.status,
    statusText: error.statusText,
    url: error.url,
    method: error.method
  });
  
  // Set a variable to track failure
  bru.setVar('lastError', error.message);
});

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

The res 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.

Here is a complete table for all available properties and methods on the 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(options?)	Get the response body data (supports raw option).
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.

Below are the detailed descriptions for properties and methods available on the res object.

Response Properties

res.status - The HTTP response status code (e.g., 200, 404, 500).
```
console.log(res.status); // 200
```
res.statusText - The HTTP response status text (e.g., “OK”, “Not Found”, “Internal Server Error”).
```
console.log(res.statusText); // "OK"
```
res.headers - An object containing all response headers.
```
console.log(res.headers);
```
res.body - The response body data (automatically parsed as JSON if the response has a JSON content type).
```
console.log(res.body);
```
res.responseTime - The total time taken for the request in milliseconds.
```
console.log(res.responseTime); // 245
```
res.url - The final response URL (after following redirects).
```
console.log(res.url);
```

Status Methods

getStatus() - Get the response status code.
```
let status = res.getStatus();
```
getStatusText() - Get the response status text.
```
let statusText = res.getStatusText();
```

Header Methods

getHeader(name) - Get a specific response header by name.
```
let transactionId = res.getHeader("transaction-id");
```
getHeaders() - Get all response headers.
```
let headers = res.getHeaders();
```

Body Methods

getBody(options?) - Get the response body data. Parameters:
- options (object, optional): Configuration options
  - raw (boolean): When true, returns the raw response body without any parsing. When false or not provided, returns the parsed body (default behavior).
Examples:
```
// Get parsed response data (default)
let data = res.getBody();

// Get raw response body without parsing
let rawData = res.getBody({ raw: true });
```

setBody(body) - Set the response body data.

res.setBody({ message: "Custom response data" });

URL Methods

getUrl() - Get the response URL. In case of redirects, you will get the final URL which may be different from the original request URL if redirects were followed. This functionality is also available as a property res.url.
This method is only available in post-response scripts and test scripts.
Returns: Response URL as a string. Example:
```
// Get the response URL
const responseUrl = res.getUrl();
console.log("Response URL:", responseUrl);

// Test that the response URL is as expected
test("should end up at correct URL after redirects", () => {
  const url = res.getUrl();
  expect(url).to.equal("https://www.apple.com");
});
```

Timing & Size Methods

getResponseTime() - Get the response time in milliseconds.
```
let responseTime = res.getResponseTime();
```

getSize() - Get the response size in bytes. Returns an object with the following properties:

body: number
headers: number
total: number

Example:

const responseSize = res.getSize();

test("Response body size is less than 1KB", () => {
  const responseSize = res.getSize().body;
  expect(responseSize).to.be.lessThan(1024);
});

Environments

The bru 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.

Here are all available environment-related methods:

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.getGlobalEnvVar(key)	Get the Bruno global environment variable.
bru.setGlobalEnvVar(key, value)	Set the Bruno global environment variable.

Environment Information

getEnvName() - Retrieves the current environment name.

const envName = bru.getEnvName();
console.log('Current environment:', envName);

Environment Variables

getEnvVar(key) - Get the Bruno environment variable.
```
let token = bru.getEnvVar("access_token");
```
setEnvVar(key, value, options?) - Set the Bruno environment variable. By default, environment variables are temporary and do not persist between app restarts. Parameters:
- key (string): The environment variable name
- value (any): The value to set
- options (object, optional): Configuration options
  - persist (boolean): When true, saves the variable to file system. When false or not provided, maintains in-memory behavior.
Examples:
```
// In-memory only (default behavior)
bru.setEnvVar("sessionId", "temp");

// Persist to file system
bru.setEnvVar("apiToken", "12345", { persist: true });

// In post-response script
function onResponse(res) {
  let data = res.getBody();
  let token = bru.setEnvVar("access_token", data.token, { persist: true });
}
onResponse(res);
```

hasEnvVar(key) - Check if the environment variable exists.

if (bru.hasEnvVar("access_token")) {
  console.log("Token exists");
}

deleteEnvVar(key) - Delete a specific environment variable.
```
bru.deleteEnvVar("access_token");
```

Global Environment Variables

getGlobalEnvVar(key) - Get the Bruno global environment variable.
```
const val = bru.getGlobalEnvVar("val");
```
setGlobalEnvVar(key, value) - Set the Bruno global environment variable.
```
bru.setGlobalEnvVar("val", "bruno");
```

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

Here are all available variable-related methods:

Method	Description
bru.getProcessEnv(key)	Fetches the process environment variable for a given key.
bru.getCollectionVar(key)	Retrieves the collection-level variable for the key.
bru.getCollectionName()	Retrieves the current collection name.
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.deleteVar(key)	Deletes a specific variable.
bru.deleteAllVars()	Deletes all runtime variables.
bru.getOauth2CredentialVar(key)	Retrieves an OAuth2 credential variable value.

Process Environment Variables

getProcessEnv(key) - Get the Node process environment variable. This allows secret token usage without committing secrets to version control.
```
let secret_token = bru.getProcessEnv("secret_access_token");
```

Collection Variables

getCollectionVar(key) - Get the collection variable.

let namespace = bru.getCollectionVar("namespace");

getCollectionName() - Retrieve the name of the current collection.

const collectionName = bru.getCollectionName();
console.log('Current collection:', collectionName);

Folder Variables

getFolderVar(key) - Get the folder variable.

let company = bru.getFolderVar("company");

Request Variables

getRequestVar(key) - Get the request variable.

let source = bru.getRequestVar("source");
let destination = bru.getRequestVar("destination");

Runtime Variables

Runtime variables are temporary variables that exist only during the execution of your requests. They are commonly used to pass data between requests in a collection run.

hasVar(key) - Check if a runtime variable exists.

if (bru.hasVar("petId")) {
  console.log("Pet ID exists");
}

getVar(key) - Get the runtime variable.
```
let petId = bru.getVar("petId");
```

setVar(key, value) - Set the runtime variable.

let data = res.getBody();
bru.setVar("petId", data.id);

deleteVar(key) - Delete the runtime variable.
```
bru.deleteVar("petId");
```
deleteAllVars() - Delete all runtime variables.
```
bru.deleteAllVars();
```

OAuth2 Credentials

getOauth2CredentialVar(key) - Retrieve an OAuth2 credential variable value. This is useful for accessing OAuth2 tokens and credentials.
```
const accessToken = bru.getOauth2CredentialVar("access_token");
```

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.

Runner methods like skipRequest() and stopExecution() only work during collection runs and will have no effect when running individual requests.

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.

Controlling Execution Order

setNextRequest(requestName) - Change the order of request execution. By default, the collection runner (UI) and the CLI run requests in order. You can change the order by calling setNextRequest with the name of the next request to be run. This works only in a post-request script or test-script. How it works:
- setNextRequest works with single requests - it executes the current request first, then jumps to the specified request
- It skips all requests between the current one and the target request
- The target request must exist in the collection and be specified by its exact name
- For requests inside folders: Use just the request name (e.g., “request-name”), not the full path
- Works the same way with both bru.setNextRequest() and bru.runner.setNextRequest()
Examples:
```
// Basic usage - in post-request script of "one.bru"
bru.setNextRequest("three"); // Will skip "two.bru" and jump to "three.bru"

// Request inside folder - use just the request name
bru.setNextRequest("request-name");

// Abort the run gracefully
bru.setNextRequest(null);
```
bru.runner.setNextRequest(requestName) - Alter the order of requests by specifying the name of the next request to execute. This function is applicable only within post-request scripts or test scripts.
```
bru.runner.setNextRequest("Get process status");
```

Collection Runner Control

bru.runner.skipRequest() - Skip the execution of the current request. Use this in the pre-request script section. This function is valid only within the context of a collection run.
```
bru.runner.skipRequest();
```
bru.runner.stopExecution() - Terminate a collection run. This function can be called from a pre-request, post-response, or test script and only takes effect during a collection run.
```
bru.runner.stopExecution();
```

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.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.

HTTP Request Methods

sendRequest(options, callback) - Send a programmatic HTTP request within your script. This allows you to make additional API calls during script execution. Parameters:
- method: HTTP method (GET, POST, PUT, etc.)
- url: The URL to send the request to
- headers: (Optional) Request headers
- data: (Optional) Request data. Can be a string or object
- timeout: (Optional) Request timeout in milliseconds
- callback: Function to handle the response with signature (err, res)
Example:
```
await bru.sendRequest({
  method: 'POST',
  url: 'https://echo.usebruno.com',
  headers: {
    'Content-Type': 'application/json',
  },
  data: { key: 'value' },
}, function (err, res) {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log('Response:', res.data);
});
```

Helper Functions

sleep(milliseconds) - Pauses execution for the specified duration. This is useful for introducing delays or waiting for a specific amount of time before proceeding with the next operation.
```
await bru.sleep(3000);
```

interpolate(string) - Evaluates dynamic variables and environment variables within a string. This function allows you to use Bruno’s dynamic variables (like {{$randomFirstName}}) directly in your scripts.

// Generate a random first name
const firstName = bru.interpolate('{{$randomFirstName}}');
console.log('Random first name:', firstName);

// Generate a random email
const email = bru.interpolate('{{$randomEmail}}');

// Generate multiple dynamic values in one call
const userInfo = bru.interpolate(`
  Name: {{$randomFullName}}
  Job: {{$randomJobTitle}}
  Email: {{$randomEmail}}
`);

disableParsingResponseJson() - Prevent the automatic parsing of the JSON response body and work directly with the raw data. Use this in the pre-request script of the request.
```
bru.disableParsingResponseJson();
```

cwd() - Returns the current working directory.

const currentDir = bru.cwd();
console.log('Current directory:', currentDir);

Request Execution

runRequest(requestPathName) - Execute any request in the collection and retrieve the response directly within the script.
Avoid using bru.runRequest() in collection-level scripts. Since collection scripts run for all requests, calling bru.runRequest() from a collection script will trigger the target request, which will also execute the collection script again, creating an infinite loop.
Example:
```
const requestResponse = await bru.runRequest("echo/echo json");
```

Test Utilities

getTestResults() - Obtain the test results of a request. Use this within test scripts.
```
const testResults = await bru.getTestResults();
```
getAssertionResults() - Obtain the assertion results of a request. Use this within test scripts.
```
const assertionResults = await bru.getAssertionResults();
```

Bruno provides Cookie Jar APIs that enable programmatic cookie management in request scripts. These APIs allow you to set, get, and delete cookies programmatically using a cookie jar instance.

Cookie management APIs are available in pre-request scripts, post-request scripts, and test scripts.

Creating a Cookie Jar

cookies.jar() - Create a cookie jar instance for managing cookies. Returns: A cookie jar instance with methods for cookie management
```
const jar = bru.cookies.jar();
```

Cookie Jar Methods

Once you have a cookie jar instance, you can use the following methods:

jar.setCookie(url, name, value) or jar.setCookie(url, cookieObject) - Set a single cookie with specified attributes. This method has two overloads for different use cases. Parameters (Key-value format):
- url: The URL for which the cookie should be set
- name: The name of the cookie
- value: The value of the cookie
Parameters (Object format):
- url: The URL for which the cookie should be set
- cookieObject: Cookie object with properties: key, value, domain, path, expires, maxAge, secure, httpOnly, sameSite
Example:
```
const jar = bru.cookies.jar();

// Set a simple cookie using key-value format
jar.setCookie("https://example.com", "sessionId", "abc123");

// Set a cookie with options using object format
jar.setCookie("https://example.com", {
  key: "userToken",
  value: "xyz789",
  domain: "example.com",
  path: "/api",
  secure: true,
  httpOnly: true,
  maxAge: 3600 // 1 hour
});
```

jar.setCookies(url, cookies) - Set multiple cookies at once using an array of cookie objects. Parameters:

url: The URL for which the cookies should be set
cookies: Array of cookie objects

Example:

const jar = bru.cookies.jar();

jar.setCookies("https://example.com", [
  {
    key: "sessionId",
    value: "abc123",
    secure: true,
    httpOnly: true
  },
  {
    key: "userPreference",
    value: "dark-mode",
    path: "/",
    maxAge: 86400 // 24 hours
  }
]);

jar.getCookie(url, name) - Get a specific cookie by name. Returns: The cookie object or null if not found Example:

const jar = bru.cookies.jar();
const sessionCookie = await jar.getCookie("https://example.com", "sessionId");
if (sessionCookie) {
  console.log("Session ID:", sessionCookie.value);
  console.log("Expires:", sessionCookie.expires);
}

jar.getCookies(url) - Get all cookies for a specific URL. Returns: Array of cookie objects or empty array if no cookies found Example:

const jar = bru.cookies.jar();
const allCookies = await jar.getCookies("https://example.com");
console.log("All cookies:", allCookies);

jar.deleteCookie(url, name) - Delete a specific cookie by name.
When deleting cookies, the domain and path options must match the original cookie’s domain and path for the deletion to be successful.
Example:
```
const jar = bru.cookies.jar();
jar.deleteCookie("https://example.com", "sessionId");
```

jar.deleteCookies(url) - Delete all cookies for a specific URL.

const jar = bru.cookies.jar();
jar.deleteCookies("https://example.com");

jar.clear() - Clear all cookies from the cookie jar.
```
const jar = bru.cookies.jar();
jar.clear();
```

Getting Started

Core Features

API Tools

Developer Tools

License Management

Advanced Guides

​Request

​URL Methods

​HTTP Method

​Request Information

​Header Methods

​Body Methods

​Request Configuration

​Execution Context

​Error Handling

​Response

​Response Properties

​Status Methods

​Header Methods

​Body Methods

​URL Methods

​Timing & Size Methods

​Environments

​Environment Information

​Environment Variables

​Global Environment Variables

​Variables

​Process Environment Variables

​Collection Variables

​Folder Variables

​Request Variables

​Runtime Variables

​OAuth2 Credentials

​Runner

​Controlling Execution Order

​Collection Runner Control

​Utilities

​HTTP Request Methods

​Helper Functions

​Request Execution

​Test Utilities

​Cookie Management

Creating a Cookie Jar

Cookie Jar Methods

Request

URL Methods

HTTP Method

Request Information

Header Methods

Body Methods

Request Configuration

Execution Context

Error Handling

Response

Response Properties

Status Methods

Header Methods

Body Methods

URL Methods

Timing & Size Methods

Environments

Environment Information

Environment Variables

Global Environment Variables

Variables

Process Environment Variables

Collection Variables

Folder Variables

Request Variables

Runtime Variables

OAuth2 Credentials

Runner

Controlling Execution Order

Collection Runner Control

Utilities

HTTP Request Methods

Helper Functions

Request Execution

Test Utilities

Cookie Management