Setting the file. One moment.
Subchapter 15.6
references/parallel-testing.mdMarkdown7 KBView on GitHub
Run multiple tests concurrently using named browse sessions. Each named session gets its own independent browser. Use this when you have multiple independent test groups (different pages, different categories) and want faster results.
Works with both local and remote mode. Named sessions are fully independent — each has its own browser process.
The --session flag (or BROWSE_SESSION env var) gives each browse command its own isolated browser:
# Session "signup" gets its own browser
# For localhost/default QA, use clean local mode first
BROWSE_SESSION=signup browse open http://localhost:3000/signup --local
# Session "dashboard" gets a completely separate browser
BROWSE_SESSION=dashboard browse open http://localhost:3000/dashboard --local
# They don't share state — each has its own page, cookies, refsLocal mode variants follow the CLI contract:
browse open <url> --local — clean isolated local browser (default; preferred for reproducible localhost testing)browse open <url> --auto-connect — auto-discover an existing debuggable local Chrome (use only when a test needs existing local login/cookies/state)browse open <url> --cdp <port|url> — explicit CDP attach to a specific local browser target| Scenario | Use |
|---|---|
| Tests on different pages/routes | Parallel — no shared state |
| Tests within one page (fill form → submit → check result) | Sequential — steps depend on each other |
| Accessibility audit + visual audit on same page | Parallel — independent checks |
| Before/after comparison on one element | Sequential — ordering matters |
After generating your test plan (from Workflow A), or identifying pages to test (Workflow B), group tests that can run in parallel:
Parallel Groups (from diff-driven test plan)
=============================================
Group 1 (session: signup) → /signup form validation (happy + adversarial)
Group 2 (session: dashboard) → /dashboard empty state + data display
Group 3 (session: a11y) → /settings accessibility audit (axe-core + keyboard)Rule: tests within a group run sequentially. Groups run in parallel.
Use the Agent tool to fan out. Each agent gets a unique session name and runs its test group independently:
Launch agents in parallel (use Agent tool with multiple invocations in one message):
Agent 1 — prompt: "Run signup form tests using BROWSE_SESSION=signup.
Start with `BROWSE_SESSION=signup browse open <localhost URL> --local`. Run these tests: [list tests].
Follow the before/after assertion protocol.
On any STEP_FAIL, immediately take a screenshot:
BROWSE_SESSION=signup browse screenshot --path .context/ui-test-screenshots/signup-<step-id>.png
Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
Run `BROWSE_SESSION=signup browse stop` when done."
Agent 2 — prompt: "Run dashboard tests using BROWSE_SESSION=dashboard.
Start with `BROWSE_SESSION=dashboard browse open <localhost URL> --local`. Run these tests: [list tests].
Follow the before/after assertion protocol.
On any STEP_FAIL, immediately take a screenshot:
BROWSE_SESSION=dashboard browse screenshot --path .context/ui-test-screenshots/dashboard-<step-id>.png
Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
Run `BROWSE_SESSION=dashboard browse stop` when done."
Agent 3 — prompt: "Run accessibility audit using BROWSE_SESSION=a11y.
Start with `BROWSE_SESSION=a11y browse open <localhost URL> --local`. Run these tests: [list tests].
Follow the before/after assertion protocol.
On any STEP_FAIL, immediately take a screenshot:
BROWSE_SESSION=a11y browse screenshot --path .context/ui-test-screenshots/a11y-<step-id>.png
Return structured STEP_PASS/STEP_FAIL markers (include screenshot path for failures).
Run `BROWSE_SESSION=a11y browse stop` when done."Critical rules for parallel agents:
browse command in the agent MUST be prefixed with BROWSE_SESSION=<name>browse open <url> --local for clean/reproducible runsbrowse open <url> --auto-connect only when the test explicitly needs existing local Chrome statebrowse stop when done (with its session name)mkdir -p .context/ui-test-screenshots and save screenshots on failure with the naming convention <session>-<step-id>.pngAs agents complete, collect their STEP_PASS/STEP_FAIL markers and merge into one report:
## UI Test Results (Parallel Run)
### Group: signup (session: signup)
STEP_PASS|valid-email|heading "Welcome!" appeared after submit
STEP_PASS|empty-submit|validation error shown for empty form
STEP_FAIL|double-submit|expected single submission → two success toasts appeared|.context/ui-test-screenshots/signup-double-submit.png
### Group: dashboard (session: dashboard)
STEP_PASS|empty-state|"No items yet" message with CTA displayed
STEP_PASS|data-display|table rendered 5 rows with correct columns
### Group: a11y (session: a11y)
STEP_FAIL|axe-audit|expected 0 violations → 2 critical: color-contrast, missing-label|.context/ui-test-screenshots/a11y-axe-audit.png
STEP_PASS|keyboard-nav|all 12 elements reachable via Tab
---
**Summary: 5/7 passed, 2 failed (across 3 parallel sessions)**
Failed: double-submit (signup), axe-audit (a11y)
Screenshots: `.context/ui-test-screenshots/`
- signup-double-submit.png — duplicate toast after rapid submit
- a11y-axe-audit.png — page showing color contrast and missing label violationsIf testing authenticated pages, sync cookies once and share the context ID across sessions:
# Sync once
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains staging.app.com
# Output: Context ID: ctx_abc123
# Each named browse session attaches to its own Browserbase session with the same context ID.
SETTINGS_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
SETTINGS_ID="$(echo "$SETTINGS_JSON" | jq -r .id)"
SETTINGS_CDP="$(echo "$SETTINGS_JSON" | jq -r .connectUrl)"
BROWSE_SESSION=settings browse open https://staging.app.com/settings --cdp "$SETTINGS_CDP"
PROFILE_JSON="$(browse cloud sessions create --context-id ctx_abc123 --keep-alive)"
PROFILE_ID="$(echo "$PROFILE_JSON" | jq -r .id)"
PROFILE_CDP="$(echo "$PROFILE_JSON" | jq -r .connectUrl)"
BROWSE_SESSION=profile browse open https://staging.app.com/profile --cdp "$PROFILE_CDP"Always stop all sessions when done, even if a test fails:
BROWSE_SESSION=signup browse stop 2>/dev/null
BROWSE_SESSION=dashboard browse stop 2>/dev/null
BROWSE_SESSION=a11y browse stop 2>/dev/null
browse cloud sessions update "$SETTINGS_ID" --status REQUEST_RELEASE 2>/dev/null
browse cloud sessions update "$PROFILE_ID" --status REQUEST_RELEASE 2>/dev/null