Script Execution Flow in Bruno

When you're building and testing APIs, automation is key. Bruno, as an API client, empowers you to automate your API workflows using powerful JavaScript scripts. But to truly master Bruno's scripting capabilities and write effective, bug-free tests, you need to understand one crucial concept: script execution flow

Bruno offers two distinct ways your scripts can execute during a collection run: the Sandwich Flow and the Sequential (Natural) Flow. Knowing which one to use and how they work will help you write cleaner, more organized, and more efficient scripts.

Let's dive in!

Understanding Script Execution Flow in Bruno

In Bruno, you can attach scripts at different levels:

• Collection Level: Scripts that apply to the entire collection.
• Folder Level: Scripts that apply to all requests within a specific folder.
• Request Level: Scripts that apply to an individual request.

Additionally, each of these levels can have a Pre-request Script (runs before the request is sent) and a Post-response Script (runs after the response is received, typically for assertions and tests).

Script Execution Flow: Sandwich vs. Sequential

Bruno provides two modes for how these layered scripts interact during a collection run:

1. Sandwich Flow

The Sandwich Flow is named for how it "sandwiches" the individual request's execution between the collection and folder level scripts. This is the default and most commonly used flow because it ensures all setup (pre-scripts) happens before the request, and all teardown/validation (post-scripts) happens after the request, across all layers.

Imagine it like preparing and cleaning up a meal:

• Collection Pre-Script: Prepare the kitchen (global setup).
• Folder Pre-Script: Prepare the table (folder-specific setup).
• Request Pre Script: Cook the specific dish (request-specific setup).
• (The Actual Request Executes)
• Request Post Script: Taste the dish and clean your plate (request-specific validation).
• Folder Post Script: Clear the table (folder-specific teardown).
• Collection Post Script: Clean the kitchen (global teardown).

Here's a visual representation of the Sandwich Flow:

This flow is ideal for managing authorization tokens, setting global variables, and performing clean-up operations that need to happen around the core request logic.

2. Sequential (Natural) Flow

The Sequential Flow, also called Natural Flow, executes all pre-scripts first (from outermost to innermost), then the request, and then all post-scripts (again, from outermost to innermost). It's more of a batch execution model.

Think of it as preparing all the ingredients, then cooking, then doing *all* the cleaning:

• Collection Pre Script: Gather all kitchen items.
• Folder Pre Script: Gather all table items.
• Request Pre Script: Gather all specific dish items.
• (The Actual Request Executes)
• Collection Post Script: Clean kitchen.
• Folder Post Script: Clean table.
• Request Post Script: Clean specific dish area.

Here's a visual representation of the Sequential Flow:

While less common for typical API testing, this flow can be useful in specific scenarios where you want all pre actions to complete before any post actions begin, across the entire scope.

Key Rule: Collection-Level Scripts Execute for Each Request

Regardless of whether you're using Sandwich or Sequential flow, there's a crucial rule to remember when running a collection:

Any Collection-level Pre-request or Post-response script will execute once for every single request that runs in that collection. The same applies to folder-level scripts for requests within that folder.

This means if you have 10 requests in a collection and a script at the collection level:

1. The Collection Pre-request script runs.
2. Request 1 executes.
3. The Request 1 Post-response script runs.
4. The Collection Post-response script runs.
5. Then, the Collection Pre-request script runs again.
6. Request 2 executes.
7. ...and so on for all 10 requests.

This behavior is fundamental for tasks like:

• Token Management: A collection-level pre-request script can refresh an authentication token before every request if it's expired.
• Global Setup/Teardown: Performing logging, setting environment variables, or clearing data per request.
• Automated Assertions: A collection-level post-response script can check for a common status code.

How Request-Level Scripts (Pre & Post) Integrate

At the most granular level, Request Pre-request scripts execute before the API call for that specific request, allowing you to prepare the request body, headers, or URL dynamically. Request Post-response scripts execute after the API call, enabling you to extract data from the response, perform assertions and conduct tests.

These request-level scripts are where you define the specific setup and validation logic unique to each API call, working in concert with the broader collection and folder scripts.

Configuring Script Execution Flow in `bruno.json`

While the Sandwich Flow is the default behavior, you can explicitly set the desired execution flow (either Sandwich or Sequential) for your collection within your bruno.json configuration file.

This allows you to override the default and specify the flow type that best suits your testing needs.

Here’s how you can configure the flow property:

bruno.json
{
  "scripts": {
    "moduleWhitelist": ["crypto", "buffer", "form-data"],
    "filesystemAccess": {
      "allow": true
    },
    "flow": "sequential" // Or "sandwich"
  }
}

By setting "flow": "sequential", all collection runs for this bruno.json file will use the Sequential Flow. If this property is omitted, Bruno will default to the Sandwich Flow.

Conclusion

Bruno's script execution flows, particularly the default Sandwich Flow, provide a powerful framework for organizing your API automation. By understanding when and where each script executes, you can write sophisticated tests, manage complex authentication, and streamline your entire API development and testing workflow.

Dive into Bruno's scripting features, experiment with different flows, and build API test suites that are not just functional but also clean, efficient, and robust!

For more detailed examples and advanced use cases, refer to the official Bruno documentation on Script Flow.

Join our Discord server to connect with the Bruno community!