How to Manage Variables in Bruno

Variables allow values to be stored and reused in Bruno. This is essential from a productivity, workflow, and security perspective. A variable is simply a moniker that represents data which is stored elsewhere. This allows you to abstract the detail (and sensitivity) away from your requests, scripts, headers, authentication, and elsewhere.

Understanding the different types of variables available and how to use them can save you a lot of time and effort, and it’s also crucial from a security perspective. In this post, we'll walk through how variables are configured in Bruno, and how to access them. 

Variable Types

Bruno allows you to work with seven different types of variables. Six of these variables are managed directly inside of the Bruno application and one is managed in the underlying file containing the collection.  

Below are the six variables managed through the Bruno application, arranged by both scope and precedence. 

The seventh variable type is  Process Environment Variables (.env), which follow the development standard of including a .env file in the root of your collection. This is a developer-centric enhancement and is not a requirement for using Bruno. 

All environment types are detailed below: 

1. Runtime Variables

Runtime variables are mainly used for scripting and manipulating response data. Bruno stores these variables in app memory, and they are available only during runtime.

Create Runtime Variables:

bru.setVar(key, value); // Create a runtime variable
bru.getVar(key);        // Get the value of the runtime variable

You can also debug these variables by using the "EYE" icon in the top-right corner of the Bruno interface.

2. Request Variables

Request-level variables are essential for API testing, debugging, and troubleshooting errors. These variables are stored in the <request-name>.bru file, and you can create them inside Bruno’s Vars tab. They are ideal for testing specific requests and capturing parameters or responses.

3. Folder Variables

Folder variables are mainly used to store output from requests or automated scripts. If you need to use the same value across multiple requests within a folder, setting it as a folder-level variable avoids repetitive work. This is particularly useful when you want to avoid passing the same variable manually between requests.

4. Collection Variables

Collection-level variables work similarly to folder variables but are not limited to a folder. These variables can be accessed throughout the entire collection, including all folders and requests within it.

Once you set a collection variable, you can use it across all folders and requests within the collection. Keep in mind that your request must be within the folder to use specific folder variables.

5. Environment Variables

Environment variables are extremely useful for setting up different environments such as Prod, Dev, or Local environments. In Bruno, you can select specific environment variables for testing setups. You can also use these variables in the Bruno CLI by passing the --env flag, which will pick the environment from the folder created in the Bruno collection root directory.

They are accessed by clicking the drop-down in the top toolbar. By default, this value will be  No Environment. When you are actively using an environment, you will see the relevant name displayed there. 

6. Global Environment Variables

Global Environment variables are available throughout the entire collection, folder, and request. You can use them globally by simply adding the variable’s key.  They are accessed by clicking the `Globe` icon in the top toolbar. 

7. Process Environment Variables

Process Environment variables (.env) are external variables that you create in a .env file inside your Bruno collection. This follows the standard development workflow that you would use with any other code repository.

These variables are useful for storing sensitive data like API keys or other secrets. You can reference them directly in your collections like this:

Or you can assign these variables as GlobalEnv or Environment variables:

It's important to also use a .gitignore file when leveraging these variables to ensure that the contents are not displayed if you chose to commit the collection to Git. 

The structure for creating and storing these environments is as follows:

bruno-collection/
├── api-folder/
├── .gitignore
├── bruno.json
├── package.json
└── .env

Variable Storage

Each variable has it's own storage location either within your collection file or within the app's memory. All storage is local. 

Using Variables 

You can use these variables in various places such as auth, scripts, headers, body, and request params. Accessing all these variables through the script is straightforward with a common sytnax.

Syntax:

bru.set[Type]Var(key, value);  // create a variable
bru.get[Type]Var(key);         // get a variable

Where:

• [Type] is the variable type (Runtime, Request, Folder, etc.)
• key is the variable name you want to access

Best Practices

1. Scoping: Always try to limit the scope of your variables according to the context. Avoid creating complex structures with similar variables for the same use case.

2. Reusability: For variables that you need to access in multiple locations, consider using Global Environment Variables.

3. Troubleshooting & Errors: Use Runtime Variables for debugging and error handling to make your workflow smoother and more controlled. These variables are helpful for capturing values during the execution of requests or scripts, making it easier to track issues as they arise.

4. Variable Naming: Choose meaningful and pattern-orientated names for your variables. It’s a good practice to use names like basic-url, org-secret-api-key, etc. This will help avoid conflicts and ensure your variables are easily identifiable.

Conclusion

Understanding how to manage and work with variables is crucial for efficient API testing. With Bruno, you can leverage different types of variables to streamline your workflow, enhance reusability, and maintain a clean and organised testing environment. Whether you’re using Global Environment Variables, Collection Variables, or Runtime Variables, Bruno gives you full control over how variables are set, accessed, and reused.

Don’t forget to refer to the official Bruno documentation to dive deeper into variables.