Iterate Using Data Files
The Collection Runner feature allows you to iterate over data files, making it easy to automate and manage data-driven requests. Bruno supports both CSV and JSON files for running requests, so you can efficiently run tests or process multiple data inputs.
Data-driven testing, parallel execution, and reports
| Feature | Plan |
|---|---|
| CSV or JSON data files (Run with Parameters) | Pro and Ultimate |
| Run in parallel | Pro and Ultimate |
| Download test reports | Ultimate |
Parallel execution
Run in parallel sends iterations at the same time instead of waiting for each one to finish. It is available on Bruno Pro and Ultimate.
Report generation
Download Report saves the run as an HTML file (report.html). Report generation is a Bruno Ultimate feature.
How request bodies and data files work together
Understanding this avoids the most common confusion with data-driven runs:
-
The data file does not replace your request body.
Uploading CSV/JSON does not merge row objects into the body or overwrite a hardcoded JSON payload. Row values are available as iteration variables for each run. -
To use row values in the body, reference them explicitly with
{{columnName}}(same names as CSV headers or JSON object keys). Example:"name": "{{name}}"uses thenamefield from the current row. -
If the body has no
{{...}}placeholders for your data columns, Bruno sends exactly the body you typed on every iteration. The file still controls how many iterations run, but each request uses the same static payload. In the runner, the Data column shows the current iteration’s row (iteration data), not “the body Bruno built from the file.” -
In scripts, read the current row with
bru.runner.iterationData.get("columnName")(or build the body there withreq.setBody(...)). See Runner iteration utilities below.
{"name": "morpheus", "job": "leader"} is fine for a single request or when you want the same body every time while the runner still steps through rows (e.g. for side effects or tests only). To send different name / job per row, the body must use {{name}} and {{job}} (or set the body from a script).
Introduction
In this tutorial, we'll use the Collection Runner with a CSV or JSON file so each iteration sends different name and job values to https://reqres.in/api/users.
Steps to Get Started
- Open the Bruno app.
- Create a collection called
runner-example. - Create a POST request and name it
runner-request. - Use the URL:
https://reqres.in/api/users. - Set the request body to JSON and use placeholders that match your data file columns (
nameandjob):
{
"name": "{{name}}",
"job": "{{job}}"
}
For a one-off request without a data file, you could use fixed values instead (e.g. morpheus / leader); that is unrelated to substituting CSV/JSON rows.
Using the Collection Runner
We will create a sample data file csv-example.csv that includes input fields such as name and job to be used in data-driven testing. You need to create a CSV or JSON file according to the specific requirements of the API you're working with.
Since the API in this case expects two data inputs name and job the file should contain these fields. Here's an example of how to structure your data:
1. CSV Format Example
A sample CSV file might look like this:
```csv copy name,job John Doe,Software Engineer Jane Smith,Product Manager Mark Lee,Data Scientist
### 2. JSON Format Example
A sample JSON file might look like this:
```json copy
[
{ "name": "John Doe", "job": "Software Engineer" },
{ "name": "Jane Smith", "job": "Product Manager" },
{ "name": "Mark Lee", "job": "Data Scientist" }
]
Now you're ready to use the Collection Runner. You can access it in two ways:
Using the Bruno App
- Click on the runner icon in the right-hand navbar.
- Select the file type: CSV or JSON and upload your data file.
- Click Run Collection to start the iterations.
Once the execution is complete, you can review the results for each individual request and check their statuses.
How to Use Variables from CSV/JSON Files
When you upload a CSV or JSON file, each column (CSV) or object key (JSON) becomes an iteration variable. Use the {{variableName}} syntax in the URL, headers, or body so each iteration sends that row’s values.
Accessing Variables in Request Body
Template the body with names that match your file:
```json showLineNumbers filename="request-body" { "name": "{{name}}", "email": "{{email}}" }
For a given iteration, Bruno resolves those placeholders from the current row—for example:
```json showLineNumbers filename="resolved-example-one-iteration"
{
"name": "John Doe",
"email": "john.doe@example.com"
}
Accessing Variables in Scripts
In pre-request or post-response scripts, read the current iteration with bru.runner.iterationData.get("columnName").
console.log(bru.runner.iterationData.get("name"));
When you run the collection, check the Timeline for the actual request body sent on each iteration.
Using the Bruno CLI
- Navigate to the root directory of your Bruno collection.
- Run the following command:
```bash copy bru run --reporter-html results.html --csv-file-path /path/to/csv/file.csv
It will create a `results.html` file in your Bruno collection's root directory. You can view this file in your browser.
For how to open and use test reports in the Bruno app (including downloaded HTML reports), see **[View test report](./manual-test#view-test-report)**.
### Command Overview
- `--reporter-html results.html`: Generates a human-readable HTML report.
- `--csv-file-path /path/to/csv/file.csv`: Specifies the path to the CSV file you want to use.
[Bruno CLI Overview](../../bru-cli/overview)
## Runner Iteration Utilities
Bruno provides various utility functions to access and manipulate data from attached data files (CSV/JSON) during collection runs.
### Accessing Iteration Data
#### Check if a variable exists
```javascript
if (bru.runner.iterationData.has("username")) {
console.log("Username exists in current iteration");
}
Get a specific value
const username = bru.runner.iterationData.get("username");
console.log(`Current username: ${username}`);
Get all iteration data
const allData = bru.runner.iterationData.get();
console.log("All iteration data:", allData);
Convert to JSON string
const jsonData = bru.runner.iterationData.stringify();
console.log("JSON data:", jsonData);
Remove a variable
bru.runner.iterationData.unset("password");
Iteration Information
Get current iteration index
const currentIteration = bru.runner.iterationIndex;
console.log(`Running iteration ${currentIteration}`);
Get total iterations
const total = bru.runner.totalIterations;
console.log(`Total iterations: ${total}`);
Example Usage
Basic Data Access
// Get values from current iteration
const username = bru.runner.iterationData.get("username");
const password = bru.runner.iterationData.get("password");
// Use in request (pre-request script only)
req.setBody({
username: username,
password: password
});
Conditional Logic Based on Iteration
// Only modify data in first iteration
if (bru.runner.iterationIndex === 0) {
bru.runner.iterationData.unset("password");
}
// Check if variable exists
if (bru.runner.iterationData.has("password")) {
console.log("Password available");
}
Data File Examples
CSV Format
username,password
user1,pass123
user2,pass456
JSON Format
[
{ "username": "user1", "password": "pass123" },
{ "username": "user2", "password": "pass456" }
]
Notes
- Variables removed with
unset()only affect the current iteration. - Each iteration runs with fresh data from the file.
- Supports both CSV and JSON data files.
- Data is automatically loaded from the attached file at the start of each iteration.
- Iteration count comes from the number of rows (CSV) or objects (JSON) in the file.
- The request body is not ignored: if you use no
{{}}references, the same static body is sent every time; the data file still drives how many times the request runs and what appears under Data for each iteration.