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

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

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, 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:

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:

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, any STEP_FAIL requires an automatic screenshot using the browse screenshot command:

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:

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 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:

mkdir -p .context/ui-test-screenshots

Launch each agent with its own unique session name:

# 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:

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:

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.
• Reference complete implementation examples in skills/ui-test/EXAMPLES.md and configuration details in 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, 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 recommends creating unique session names for each test group to ensure cookies, local storage, and network connections remain completely independent across parallel executions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}