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.

Introduction

In this tutorial, we’ll explore the Collection Runner feature, which enables you to run collections using custom data for each iteration.

Steps to Get Started

1. Open the Bruno app.
2. Create a collection called runner-example
3. Create a POST request and name it runner-request
4. Use the URL: https://reqres.in/api/users
5. Select the JSON format for the request body and add the following data:

{
    "name": "morpheus",
    "job": "leader"
}

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:

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:

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

1. Click on the runner icon in the right-hand navbar.
2. Check the Run with Parameters option.
3. Select the file type: CSV or JSON.
4. Click Run Collection.

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, the variables within the file can be accessed using the {{var}} syntax. You can access these variables dynamically in your requests and use them within Bruno.

Accessing Variables in Request Body

request-body

{
  "name": "{{name}}",
  "email": "{{email}}"
}

In this example, {{name}} and {{email}} will be replaced by the actual values from the uploaded JSON file.

request-body

{
  "name": "John Doe",
  "email": "[e-mail]"
}

Accessing Variables in Scripts

You can also access these variables directly in your pre-request or post-response scripts using bru.getVar().

console.log(bru.getVar("name")); // Outputs: John Doe
console.log(bru.getVar("email")); // Outputs: [e-mail]

When you run the request, you’ll see the output of these variables in the console.

Using the Bruno CLI

1. Navigate to the root directory of your Bruno collection.
2. Run the following command:

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.

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

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

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
bru.request.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