Running API Tests

The bru run command executes your API requests and tests from the command line. You can run individual requests, folders, or entire collections.

Basic Usage

Navigate to your collection directory and run:

bru run

This runs all requests in the current collection directory.

Running Specific Requests

Single Request

Run a specific .bru file:

bru run request.bru

Folder

Run all requests in a folder:

bru run auth

Folder (Recursive)

Run all requests in a folder and its subfolders:

bru run auth -r

Multiple Paths

Run multiple requests and folders:

bru run auth/login.bru users payments -r

Working with Environments

Using Collection Environments

Run with a specific environment:

bru run --env production

The CLI looks for the environment file in environments/production.bru (or .yml for OpenCollection format).

Using Environment Files

Load environment from a custom file:

bru run --env-file custom-env.bru

Supported formats:

.bru - Bruno environment format
.json - JSON format
.yml/.yaml - YAML format

Global Environments

Use a global environment from a workspace:

bru run --global-env production

Specify workspace path if not auto-detected:

bru run --global-env production --workspace-path /path/to/workspace

Overriding Variables

Override specific environment variables:

bru run --env staging --env-var apiKey=secret123

Override multiple variables:

bru run --env staging --env-var apiKey=secret123 --env-var baseUrl=https://api.test.com

Output and Reporting

JSON Output

Save results as JSON:

bru run --output results.json

Or using the reporter flag:

bru run --reporter-json results.json

JUnit XML Output

Generate JUnit-compatible XML for CI/CD:

bru run --output results.xml --format junit

Or:

bru run --reporter-junit results.xml

HTML Report

Generate an HTML report:

bru run --output report.html --format html

Or:

bru run --reporter-html report.html

Multiple Reports

Generate multiple report formats simultaneously:

bru run --reporter-json results.json --reporter-junit results.xml --reporter-html report.html

Security Options

Custom CA Certificates

Add a custom CA certificate:

bru run --cacert myCustomCA.pem

Use custom CA exclusively (ignore default truststore):

bru run --cacert myCustomCA.pem --ignore-truststore

Client Certificates

Use client certificates for authentication:

bru run --client-cert-config client-cert-config.json

The config file format:

client-cert-config.json

{
  "enabled": true,
  "certs": [
    {
      "domain": "https://api.example.com",
      "certFilePath": "/path/to/cert.pem",
      "keyFilePath": "/path/to/key.pem",
      "passphrase": "optional-passphrase"
    }
  ]
}

Insecure Connections

Allow insecure server connections (skip SSL verification):

Only use this in development/testing environments. Never in production.

bru run --insecure

Execution Control

Run Only Requests with Tests

Skip requests that don’t have tests or assertions:

bru run --tests-only

Bail on Failure

Stop execution immediately after any failure:

bru run --bail

Delay Between Requests

Add a delay (in milliseconds) between each request:

bru run --delay 1000

This adds a 1-second delay between requests.

Tag-Based Filtering

Run only requests with specific tags:

bru run --tags=smoke,critical

Exclude requests with certain tags:

bru run --tags=api --exclude-tags=skip,wip

Proxy Configuration

Disable Proxy

Disable all proxy settings:

bru run --noproxy

This disables both collection-defined proxies and system proxies.

JavaScript Sandbox

Choose the JavaScript runtime for scripts:

bru run --sandbox safe

Options:

safe (default) - Uses QuickJS for security
developer - Uses Node.js VM for more features

Customizing Reporter Output

Skip Headers

Omit all headers from reports:

bru run --reporter-skip-all-headers

Skip specific headers:

bru run --reporter-skip-headers Authorization Cookie

Skip Request/Response Bodies

Omit request bodies:

bru run --reporter-skip-request-body

Omit response bodies:

bru run --reporter-skip-response-body

Omit both:

bru run --reporter-skip-body

Disable automatic cookie handling:

bru run --disable-cookies

Verbose Output

Enable verbose output for debugging:

bru run --verbose

Understanding Test Results

After execution, you’ll see a summary:

Requests:     10 passed, 0 failed, 10 total
Tests:        25 passed, 0 failed, 25 total
Assertions:   42 passed, 0 failed, 42 total

Ran all requests - 2547 ms

The CLI reports:

Requests - HTTP request execution status
Pre-Request Tests - Tests run before the request
Post-Response Tests - Tests run after the response
Tests - General test results
Assertions - Assertion results

Common Examples

CI/CD Pipeline

bru run \
  --env production \
  --reporter-junit results.xml \
  --reporter-html report.html \
  --bail

Development Testing

bru run \
  --env local \
  --env-var apiKey=$DEV_API_KEY \
  --tests-only \
  --verbose

Smoke Tests

bru run \
  --tags=smoke \
  --env staging \
  --bail \
  --reporter-json smoke-results.json

Testing with Custom Certificates

bru run \
  --env internal \
  --cacert corporate-ca.pem \
  --client-cert-config client-certs.json

Exit Codes

The CLI returns different exit codes for automation:

bru run || echo "Tests failed with code: $?"

See the CLI Overview for all exit codes.

Next Steps

CLI Options Reference

Complete reference of all CLI flags and options

Importing Collections

Import collections from OpenAPI and other formats

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

​Running API Tests

​Basic Usage

​Running Specific Requests

​Single Request

​Folder

​Folder (Recursive)

​Multiple Paths

​Working with Environments

​Using Collection Environments

​Using Environment Files

​Global Environments

​Overriding Variables

​Output and Reporting

​JSON Output

​JUnit XML Output

​HTML Report

​Multiple Reports

​Security Options

​Custom CA Certificates

​Client Certificates

​Insecure Connections

​Execution Control

​Run Only Requests with Tests

​Bail on Failure

​Delay Between Requests

​Tag-Based Filtering

​Proxy Configuration

​Disable Proxy

​JavaScript Sandbox

​Customizing Reporter Output

​Skip Headers

​Skip Request/Response Bodies

​Cookie Management

​Verbose Output

​Understanding Test Results

​Common Examples

​CI/CD Pipeline

​Development Testing

​Smoke Tests

​Testing with Custom Certificates

​Exit Codes

​Next Steps

CLI Options Reference

Importing Collections

Build docs developers (and LLMs) love

Running API Tests

Basic Usage

Running Specific Requests

Single Request

Folder

Folder (Recursive)

Multiple Paths

Working with Environments

Using Collection Environments

Using Environment Files

Global Environments

Overriding Variables

Output and Reporting

JSON Output

JUnit XML Output

HTML Report

Multiple Reports

Security Options

Custom CA Certificates

Client Certificates

Insecure Connections

Execution Control

Run Only Requests with Tests

Bail on Failure

Delay Between Requests

Tag-Based Filtering

Proxy Configuration

Disable Proxy

JavaScript Sandbox

Customizing Reporter Output

Skip Headers

Skip Request/Response Bodies

Cookie Management

Verbose Output

Understanding Test Results

Common Examples

CI/CD Pipeline

Development Testing

Smoke Tests

Testing with Custom Certificates

Exit Codes

Next Steps