Bruno API Testing

Create and run API test collections using Bruno — a Git-first, offline-only API client that stores collections as plain files.

Format Selection

Bruno supports two file formats. Determine which to use:

YAML (OpenCollection) — Default since Bruno v3.1. Uses
```
.yml
```
files and
```
opencollection.yml
```
root. Preferred for new projects.
Bru (Legacy) — Uses
```
.bru
```
files and
```
bruno.json
```
root. Use only for existing Bru-format collections.

Detect format by checking the collection root:

opencollection.yml

→ YAML,

bruno.json

→ Bru.

For YAML format syntax details, see references/yaml-syntax.md. For Bru format syntax details, see references/bru-syntax.md.

Workflow

1. Create Collection Structure

Create the directory layout with the collection root file, environments, and organized request folders.

YAML format:

my-api-tests/
├── opencollection.yml          # REQUIRED: collection root
├── environments/
│   ├── Local.yml
│   ├── Staging.yml
│   └── Production.yml
├── Auth/
│   ├── folder.yml
│   └── Login.yml
└── Users/
    ├── folder.yml
    ├── Get Users.yml
    ├── Get User by ID.yml
    └── Create User.yml

Minimal

opencollection.yml

yaml

opencollection: 1.0.0

info:
  name: My API Tests

Bru format: Same structure but use

bruno.json

.bru

extensions. See references/bru-syntax.md.

2. Create Environment Files

YAML (

environments/Local.yml

yaml

variables:
  - name: baseUrl
    value: http://localhost:3000/api
  - name: apiKey
    value: ""
    secret: true

Bru (

environments/Local.bru

vars {
  baseUrl: http://localhost:3000/api
}

vars:secret [
  apiKey
]

3. Write Request Files with Tests

YAML format — a complete request with tests:

yaml

info:
  name: Get Users
  type: http
  seq: 1

http:
  method: GET
  url: "{{baseUrl}}/users"
  headers:
    - name: accept
      value: application/json
    - name: authorization
      value: "Bearer {{authToken}}"

runtime:
  assertions:
    - expression: res.status
      operator: eq
      value: "200"
    - expression: res.body
      operator: isArray
  scripts:
    - type: tests
      code: |-
        test("returns 200", function() {
          expect(res.status).to.equal(200);
        });

        test("returns array of users", function() {
          expect(res.body).to.be.an('array');
          expect(res.body).to.have.lengthOf.at.least(1);
        });

        test("each user has required fields", function() {
          res.body.forEach(user => {
            expect(user).to.have.property('id');
            expect(user).to.have.property('email');
          });
        });

settings:
  encodeUrl: true

Use assertions (declarative) for simple checks, tests scripts (Chai.js) for complex logic.

4. Chain Requests with Data Extraction

Extract data from one response and use it in subsequent requests:

YAML — Login request saving a token:

yaml

info:
  name: Login
  type: http
  seq: 1

http:
  method: POST
  url: "{{baseUrl}}/auth/login"
  body:
    type: json
    data: |-
      {
        "username": "{{username}}",
        "password": "{{password}}"
      }
  auth:
    type: none

runtime:
  scripts:
    - type: after-response
      code: |-
        bru.setEnvVar("authToken", res.body.access_token);
    - type: tests
      code: |-
        test("login successful", function() {
          expect(res.status).to.equal(200);
          expect(res.body).to.have.property('access_token');
        });

Then reference

{{authToken}}

in subsequent requests via

Bearer {{authToken}}

5. Run Tests with bru CLI

Install and run:

bash

npm install -g @usebruno/cli

# Run entire collection
cd my-api-tests && bru run --env Local

# Run specific folder
bru run Auth --env Local

# Run with developer mode (for external packages, fs access)
bru run --env Local --sandbox=developer

# Filter by tags
bru run --tags=smoke --env Local

# Generate reports
bru run --env Local \
  --reporter-html results.html \
  --reporter-junit results.xml \
  --reporter-json results.json

# Pass secrets via CLI
bru run --env Local --env-var API_KEY=secret123

# Parallel execution
bru run --env Local --parallel

# Data-driven testing
bru run --csv-file-path data.csv --env Local

v3.0.0 breaking change: Default is now Safe Mode. Use

--sandbox=developer

for developer mode features.

6. Set Up CI/CD

See references/ci-cd.md for complete GitHub Actions workflows, matrix testing, and reporting patterns.

Minimal GitHub Actions workflow:

yaml

name: API Tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @usebruno/cli
      - name: Run API Tests
        working-directory: ./my-api-tests
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: bru run --env CI --reporter-html results.html --reporter-junit results.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: |
            ./my-api-tests/results.html
            ./my-api-tests/results.xml

Critical: Always set

working-directory

to the collection root in CI/CD.

Testing Patterns

Assertions (Declarative) — Use for Simple Checks

yaml

runtime:
  assertions:
    - expression: res.status
      operator: eq
      value: "200"
    - expression: res.body.success
      operator: eq
      value: "true"
    - expression: res.body.data
      operator: isJson
    - expression: res.headers.content-type
      operator: contains
      value: application/json

Operators vary slightly by Bruno version and editor surface. Check Bruno's current Assertions docs for the exact operator names supported by your version when writing declarative assertions.

Tests (Chai.js) — Use for Complex Validation

yaml

runtime:
  scripts:
    - type: tests
      code: |-
        test("status and structure", function() {
          expect(res.status).to.equal(200);
          expect(res.body).to.be.an('object');
          expect(res.body).to.have.all.keys('id', 'name', 'email');
        });

        test("validates email format", function() {
          expect(res.body.email).to.match(/^[\w\-.]+@([\w-]+\.)+[\w-]{2,4}$/);
        });

        test("response time acceptable", function() {
          expect(res.responseTime).to.be.below(2000);
        });

        test("pagination works", function() {
          expect(res.body.data).to.be.an('array');
          expect(res.body.meta.total).to.be.a('number');
          expect(res.body.meta.page).to.equal(1);
        });

For the complete JavaScript API (

req

res

bru

objects), see references/javascript-api.md.

Common Mistakes

Missing
```
opencollection.yml
```
(YAML) or
```
bruno.json
```
(Bru) at collection root
Using
```
meta:
```
instead of
```
info:
```
in YAML request files
Using script type
```
test
```
instead of
```
tests
```
(plural)
Putting request-level fields (
```
http:
```
,
```
method:
```
) in
```
opencollection.yml
```
Forgetting
```
working-directory
```
in CI/CD steps
Committing secrets — use
```
secret: true
```
in env files + CI/CD secrets
Using
```
|-
```
for body data is required in YAML to preserve JSON formatting
Missing
```
seq
```
number in
```
info:
```
— controls execution order
Relying on
folder.yml
script/auth inheritance in CLI — Bruno's Sandwich execution order (Collection → Folder → Request) for
```
before-request
```
scripts may work in the Bruno GUI, but
```
@usebruno/cli
```
does NOT reliably inherit
```
folder.yml
```
scripts or auth settings to individual test files. Always add
```
before-request
```
scripts and
```
auth
```
blocks directly to each request file that needs them. The
```
folder.yml
```
is useful for documentation and GUI users, but CLI-driven tests must be self-contained.

Script Execution Order

Bruno supports two script flows:

Sandwich (default): Collection
```
before-request
```
→ Folder
```
before-request
```
→ Request
```
before-request
```
→ Request is sent → Request
```
after-response
```
→ Folder
```
after-response
```
→ Collection
```
after-response
```
Sequential: Collection
```
before-request
```
→ Folder
```
before-request
```
→ Request
```
before-request
```
→ Request is sent → Collection
```
after-response
```
→ Folder
```
after-response
```
→ Request
```
after-response
```

Request assertions and request

tests

run after the post-response scripts.

⚠️ CLI Inheritance Caveat

The Sandwich/Sequential script execution order described above applies to Bruno GUI only. When running tests with

@usebruno/cli

(the CLI runner used in CI/CD), folder-level

before-request

scripts and

auth

settings are NOT reliably inherited by individual request files.

Impact: If a

folder.yml

contains a

before-request

script (e.g., to skip requests when an environment variable is

"false"

), request files in that folder will NOT inherit this logic when run via CLI.

Workaround: Duplicate the

before-request

logic into each individual request file that needs it:

yaml

# In each request file that needs conditional skip:
runtime:
  scripts:
    - type: before-request
      code: |-
        const featureAvailable = bru.getEnvVar("featureAvailable");
        if (featureAvailable === "false") {
          bru.runner.skipRequest();
        }
    - type: tests
      code: |-
        test("returns 200", function() {
          expect(res.status).to.equal(200);
        });

Same applies to auth: Set

http.auth

in each request file, not just

folder.yml

Variable Precedence (Highest to Lowest)

Runtime variables (
```
bru.setVar()
```
)
Request variables
Folder variables
Collection variables
Environment variables

Use

bru.getGlobalEnvVar()

for global environment values and

bru.getProcessEnv()

for OS process environment variables. They are not documented as part of the standard collection variable precedence chain.

References

YAML Syntax — Complete OpenCollection YAML format for requests, bodies, auth, headers, params, environments, folders, collections
Bru Syntax — Legacy
```
.bru
```
file format reference
JavaScript API — Full
```
req
```
,
```
res
```
,
```
bru
```
object API with runner control, cookies, utilities
CI/CD Integration — GitHub Actions workflows, report generation, matrix testing, environment secrets

bruno-api-testing

NPX Install

Tags

SKILL.md Content

Bruno API Testing

Format Selection

Workflow

1. Create Collection Structure

2. Create Environment Files

3. Write Request Files with Tests

4. Chain Requests with Data Extraction

5. Run Tests with bru CLI

6. Set Up CI/CD

Testing Patterns

Assertions (Declarative) — Use for Simple Checks

Tests (Chai.js) — Use for Complex Validation

Common Mistakes

Script Execution Order

⚠️ CLI Inheritance Caveat

Variable Precedence (Highest to Lowest)

References