# How to Run Parallel UI Tests Across Multiple Browserbase Browsers: A Complete Guide

> Learn to run parallel UI tests on multiple Browserbase browsers. Assign unique session names, launch isolated instances, and get consolidated reports for faster testing.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**Run parallel UI tests across multiple Browserbase browsers by assigning each test group a unique `BROWSE_SESSION` name, launching isolated browser instances with `browse env local`, and aggregating results from sub-agents into a consolidated report.**

The `browserbase/skills` repository ships with a dedicated UI-test skill that provides built-in parallel testing capabilities. This workflow allows you to fan out independent test groups to separate Browserbase browsers, ensuring complete isolation between sessions while aggregating results into a single report. By leveraging named sessions and strict step budgets, you can execute complex test matrices without cross-contamination of state.

## Architecture of Parallel Testing

The parallel testing workflow defined in [`skills/ui-test/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/SKILL.md) operates through three distinct architectural layers:

**Main Agent** – Plans the overall test strategy, groups independent tests by functionality, and launches a sub-agent for each group.

**Sub-agents** – Each receives a short list of test steps, a step budget, and a unique session name. They execute their assigned steps using the `browse` CLI (commands like `open`, `click`, `fill`, and `snapshot`) and report back with `STEP_PASS` or `STEP_FAIL` markers.

**Result Merger** – Collects markers from all sub-agents, concatenates them into a single textual report, and optionally renders the HTML report template located at [`skills/ui-test/references/report-template.html`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/report-template.html).

This layered approach ensures that a failure in one browser session does not block execution in others.

### Isolating Sessions with BROWSE_SESSION

Session isolation is enforced through the `BROWSE_SESSION` environment variable. When you prefix any `browse` command with `BROWSE_SESSION=<name>`, the UI-test skill launches a completely separate Chrome instance for that session.

According to [`skills/ui-test/references/parallel-testing.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/parallel-testing.md), this guarantees that cookies, local storage, page state, and network connections remain isolated per session. Actions taken in a session named `signup` cannot interfere with a session named `dashboard`.

## Launching and Managing Browser Instances

Each sub-agent follows a strict launch protocol. The agent must initialize the environment, execute test steps within a defined budget, and explicitly terminate the session.

### Initializing the Environment

Before running tests, each session requires initialization using `browse env local` for local execution or `browse env remote` for cloud-based testing:

```bash
BROWSE_SESSION=signup browse env local

```

For remote environments requiring authentication, first run the cookie-sync helper script at `skills/cookie-sync/scripts/cookie-sync.mjs` to generate a shared `context-id` that multiple sessions can reference.

### Enforcing Step Budgets

Each sub-agent must be assigned a step budget (typically **25-75 steps** depending on test scope). The agent must halt execution when the budget is exhausted and report any incomplete steps as `STEP_SKIP`. This prevents individual agents from consuming excessive resources or running indefinitely.

### Terminating Sessions

After completing all test steps, explicitly stop each browser instance to release resources:

```bash
BROWSE_SESSION=signup browse stop

```

## Handling Failures and Capturing Screenshots

When a sub-agent encounters a failure, it must capture immediate evidence. As specified in [`skills/ui-test/references/parallel-testing.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/parallel-testing.md), any `STEP_FAIL` requires an automatic screenshot using the `browse screenshot` command:

```bash
BROWSE_SESSION=signup browse screenshot --path .context/ui-test-screenshots/signup-double-submit.png

```

Store all failure screenshots in `.context/ui-test-screenshots/<session>-<step-id>.png`. This naming convention ensures the result merger can locate and embed screenshots in the final HTML report.

## Merging Results into a Final Report

The main agent aggregates output from all sub-agents using standardized markers:

- `STEP_PASS|<step-id>|<description>` – Step completed successfully
- `STEP_FAIL|<step-id>|<description>|<screenshot-path>` – Step failed with evidence path
- `STEP_SKIP|<step-id>|<reason>` – Step skipped due to budget exhaustion or dependencies

The merger concatenates these markers and computes summary statistics including total tests, passed count, failed count, agent utilization, and pass rate. To generate a visual report, render the HTML template:

```bash
node scripts/render-report.js .context/ui-test-report.txt .context/ui-test-report.html

```

The template at [`skills/ui-test/references/report-template.html`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/report-template.html) formats the aggregated data with embedded screenshots and summary tables.

## Complete Example: Running Three Parallel Test Groups

Below is a practical implementation demonstrating three independent test groups running simultaneously. First, create the required directory:

```bash
mkdir -p .context/ui-test-screenshots

```

Launch each agent with its own unique session name:

```bash

# Agent 1: Signup form validation

BROWSE_SESSION=signup \
  browse env local && \
  BROWSE_SESSION=signup browse open http://localhost:3000/signup && \
  # ... run validation steps ... && \

  BROWSE_SESSION=signup browse stop

# Agent 2: Dashboard functionality  

BROWSE_SESSION=dashboard \
  browse env local && \
  BROWSE_SESSION=dashboard browse open http://localhost:3000/dashboard && \
  # ... run dashboard tests ... && \

  BROWSE_SESSION=dashboard browse stop

# Agent 3: Accessibility audit

BROWSE_SESSION=a11y \
  browse env local && \
  BROWSE_SESSION=a11y browse open http://localhost:3000/settings && \
  BROWSE_SESSION=a11y browse eval "await axe.run()" && \
  # ... run additional audit steps ... && \

  BROWSE_SESSION=a11y browse stop

```

For agent-driven execution, dispatch the following prompt structure to each sub-agent:

```text
Agent 1 —
Prompt:
"Run signup form tests using BROWSE_SESSION=signup.
First run `browse env local`, then open http://localhost:3000/signup.
Execute the following steps (budget = 30):
1. Fill valid email → submit → expect success toast.
2. Fill invalid email → submit → expect error.
3. Submit empty form → expect validation error.
4. Rapid double-click submit → expect only one request (STEP_FAIL on duplicate toast).
On any STEP_FAIL take a screenshot saved as .context/ui-test-screenshots/signup-<step-id>.png.
When done run `BROWSE_SESSION=signup browse stop`."

```

After all agents complete, merge the results into a text report:

```bash
cat <<'REPORT' > .context/ui-test-report.txt

## UI Test Results (Parallel Run)

### Group: signup (session: signup)

STEP_PASS|valid-email|Valid email submission successful
STEP_FAIL|double-submit|Expected single submission → duplicate toast|.context/ui-test-screenshots/signup-double-submit.png

### Group: dashboard (session: dashboard)  

STEP_PASS|empty-state|Dashboard empty state rendered
STEP_PASS|data-display|Data grid populated correctly

### Group: a11y (session: a11y)

STEP_FAIL|axe-audit|Expected 0 violations → 2 critical|.context/ui-test-screenshots/a11y-axe-audit.png
STEP_PASS|keyboard-nav|Tab order follows logical sequence

---  
Summary: 5/7 passed, 2 failed (across 3 sessions)
REPORT

```

## Summary

- Use `BROWSE_SESSION=<name>` to create isolated browser instances that do not share cookies, storage, or network state with other sessions.
- Structure parallel tests with a main agent coordinating sub-agents, each operating within a strict step budget of 25-75 steps.
- Always run `browse env local` (or `env remote` with cookie-sync) before testing and `browse stop` after completion to properly manage resources.
- Capture failure evidence immediately using `browse screenshot` and store files in `.context/ui-test-screenshots/<session>-<step-id>.png`.
- Aggregate results using `STEP_PASS`, `STEP_FAIL`, and `STEP_SKIP` markers, then render the final HTML report using the template at [`skills/ui-test/references/report-template.html`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/report-template.html).
- Reference complete implementation examples in [`skills/ui-test/EXAMPLES.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/EXAMPLES.md) and configuration details in [`skills/ui-test/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/SKILL.md).

## Frequently Asked Questions

### How many parallel sessions can I run simultaneously?

The number of concurrent sessions depends on your Browserbase plan and local system resources. Each `BROWSE_SESSION` launches an independent Chrome process, so allocate sufficient memory per instance. According to [`skills/ui-test/SKILL.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/SKILL.md), you should constrain each sub-agent with a step budget (25-75 steps) to prevent resource exhaustion regardless of how many sessions you run in parallel.

### What is the difference between `browse env local` and `browse env remote`?

`browse env local` launches a browser instance on your local machine, suitable for CI environments or development workflows. `browse env remote` connects to Browserbase's cloud infrastructure, enabling tests to run on managed browsers in the cloud. When using remote mode with authentication, first execute the cookie-sync script at `skills/cookie-sync/scripts/cookie-sync.mjs` to generate a shared context ID that multiple sub-agents can reference.

### How do I prevent test steps from running indefinitely?

Enforce a step budget when dispatching sub-agents. Specify a hard limit based on test complexity (typically 25 steps for simple flows, up to 75 for complex journeys) and instruct the agent to report `STEP_SKIP` for any remaining steps once the budget is exhausted. This mechanism ensures agents terminate predictably even if tests encounter infinite loops or hanging network requests.

### Can I reuse browser sessions across different test files?

While technically possible by referencing the same `BROWSE_SESSION` name, doing so violates isolation principles and risks state contamination between tests. The parallel testing guide in [`skills/ui-test/references/parallel-testing.md`](https://github.com/browserbase/skills/blob/main/skills/ui-test/references/parallel-testing.md) recommends creating unique session names for each test group to ensure cookies, local storage, and network connections remain completely independent across parallel executions.