Collections

Learn how Bruno collections work, including folder structure, configuration, and organization

Overview

Bruno collections are stored as plain text files directly in your filesystem. Each collection is a folder containing .bru files for requests, environment files, and a bruno.json configuration file. This approach makes your API collections fully version-controllable and shareable.

Collection Structure

A typical Bruno collection looks like this:

my-api-collection/
├── bruno.json              # Collection configuration
├── collection.bru          # Collection-level settings
├── environments/           # Environment files
│   ├── Local.bru
│   └── Prod.bru
├── auth/                   # Organized by folders
│   ├── login.bru
│   ├── logout.bru
│   └── folder.bru          # Folder-level settings
└── api/
    └── v1/
        ├── users.bru
        └── posts.bru

bruno.json Configuration

The bruno.json file contains collection-wide settings and metadata.

Basic Configuration

bruno.json

{
  "version": "1",
  "name": "My API Collection",
  "type": "collection",
  "ignore": [
    "node_modules",
    ".git"
  ]
}

Advanced Configuration

bruno.json

{
  "version": "1",
  "name": "bruno-testbench",
  "type": "collection",
  "proxy": {
    "enabled": false,
    "protocol": "http",
    "hostname": "{{proxyHostname}}",
    "port": 4000,
    "auth": {
      "enabled": false,
      "username": "anoop",
      "password": "password"
    },
    "bypassProxy": ""
  },
  "scripts": {
    "moduleWhitelist": ["crypto", "buffer", "form-data"],
    "additionalContextRoots": ["../additional-context-root-lib"]
  },
  "clientCertificates": {
    "enabled": true,
    "certs": []
  },
  "presets": {
    "requestType": "http",
    "requestUrl": "http://localhost:6000"
  }
}

Configuration Options

• version - Collection format version (currently “1”)
• name - Display name of your collection
• type - Always “collection”
• ignore - Files/folders to ignore (like .gitignore)
• proxy - HTTP proxy configuration
• scripts - Script execution settings and module access
• clientCertificates - SSL/TLS client certificate configuration
• presets - Default values for new requests

Collection-Level Settings

The collection.bru file defines default settings applied to all requests in the collection.

collection.bru

headers {
  check: again
  token: {{collection_pre_var_token}}
  collection-header: collection-header-value
}

auth {
  mode: bearer
}

auth:bearer {
  token: {{bearer_auth_token}}
}

vars:pre-request {
  collection_pre_var: collection_pre_var_value
  collection_pre_var_token: {{request_pre_var_token}}
  collection-var: collection-var-value
}

script:pre-request {
  // Runs before every request in the collection
  const shouldTestCollectionScripts = bru.getVar('should-test-collection-scripts');
  if(shouldTestCollectionScripts) {
   bru.setVar('collection-var-set-by-collection-script', 'collection-var-value-set-by-collection-script');
  }
}

tests {
  // Runs after every request in the collection
  const shouldTestCollectionScripts = bru.getVar('should-test-collection-scripts');
  const collectionVar = bru.getVar("collection-var-set-by-collection-script");
  if (shouldTestCollectionScripts && collectionVar) {
    test("collection level test - should get the var that was set by the collection script", function() {
      expect(collectionVar).to.equal("collection-var-value-set-by-collection-script");
    }); 
    bru.setVar('collection-var-set-by-collection-script', null); 
    bru.setVar('should-test-collection-scripts', null);
  }
}

docs {
  # bruno-testbench 🐶
  
  This is a test collection that I am using to test various functionalities around bruno
}

Folder Organization

Organize your requests into folders for better structure. Each folder can have a folder.bru file with folder-level settings.

folder.bru

folder.bru

meta {
  name: js
}

headers {
  folder-header: folder-header-value
}

script:pre-request {
  // Runs before requests in this folder
  const shouldTestFolderScripts = bru.getVar('should-test-folder-scripts');
  if(shouldTestFolderScripts) {
   bru.setVar('folder-var-set-by-folder-script', 'folder-var-value-set-by-folder-script');
  }
}

tests {
  // Runs after requests in this folder
  const shouldTestFolderScripts = bru.getVar('should-test-folder-scripts');
  const folderVar = bru.getVar("folder-var-set-by-folder-script");
  if (shouldTestFolderScripts && folderVar) {
    test("folder level test - should get the var that was set by the folder script", function() {
      expect(folderVar).to.equal("folder-var-value-set-by-folder-script");
    }); 
    bru.setVar('folder-var-set-by-folder-script', null); 
    bru.setVar('should-test-folder-scripts', null);
  }
}

Folder-level settings are inherited by all requests within that folder. Request-level settings override folder settings, which override collection settings.

Settings Inheritance

Bruno uses a cascading system for settings:

Collection Settings (collection.bru)
  ↓
Folder Settings (folder.bru)
  ↓
Request Settings (request.bru)

Each level can override or extend settings from parent levels.

Headers

Headers defined at collection or folder level are merged with request headers

Authentication

Requests can use auth: inherit to use collection/folder auth settings

Variables

Variables are available to all child requests and can be overridden

Scripts

Pre-request and post-response scripts run in order: collection → folder → request

Creating a Collection

1. Create a folder

   Create a new folder for your collection:

   mkdir my-api-collection
   cd my-api-collection
   
2. Add bruno.json

   Create a bruno.json file with your collection settings:

   {
     "version": "1",
     "name": "My API Collection",
     "type": "collection"
   }
   
3. Add requests

   Create .bru files for your API requests. See the Bru Language guide for syntax.

4. Open in Bruno

   Open the collection folder in Bruno to start testing your APIs.

Best Practices

Logical Organization

Group related requests into folders (e.g., auth/, users/, products/)

Descriptive Names

Use clear, descriptive names for files and folders

Shared Settings

Put common headers and auth in collection.bru to avoid repetition

Environment Variables

Use environments for different servers (local, staging, production)

Next Steps

Bru Language

Learn the .bru file format for defining requests

Environments

Set up environment variables for different contexts

Git Integration

Version control your API collections with Git

Scripting

Add JavaScript for dynamic request/response handling