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.

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

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);
  });

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.

Here is a complete table for all available properties and methods on the res object.

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);
  });

Bru

The bru variable is available inside your scripting and testing context. It exposes methods that allow you to interact with, e.g., process variables, environment variables and collection variables.

Here is a complete table for all available methods with the bru.

Below is the API documentation for the methods available on bru

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);

Variables

Bruno provides a comprehensive variable system that allows you to manage and access different types of variables throughout your scripts. These include process environment variables, environment variables, collection variables, folder variables, request variables, and runtime variables.

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");

Environment Variables

• getEnvName() - Retrieves the current environment name.

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

• 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 });
  }

• 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");

• 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");

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

• 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();

Request Execution & Order

This section covers methods for executing requests and controlling the execution flow in Bruno, including collection runner utilities.

Running Requests

• 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");

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 Utilities

• 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();

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();

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");

Cookie Management

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.

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();