# Parallel Testing

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.

### How sessions work

The `--session` flag (or `BROWSE_SESSION` env var) gives each `browse` command its own isolated browser:

```bash
# 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, refs
```

Local 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

### When to use parallel vs sequential

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

### Phase 1: Group tests by independence

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.

### Phase 2: Launch parallel agents

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:**
- Every `browse` command in the agent MUST be prefixed with `BROWSE_SESSION=<name>`
- If the target URL is localhost/127.0.0.1, each agent should start with `browse open <url> --local` for clean/reproducible runs
- Use `browse open <url> --auto-connect` only when the test explicitly needs existing local Chrome state
- Each agent must call `browse stop` when done (with its session name)
- Pass the full test steps and assertion protocol to each agent — they don't have the skill context
- Include the before/after snapshot pattern in each agent's prompt
- Tell each agent to `mkdir -p .context/ui-test-screenshots` and save screenshots on failure with the naming convention `<session>-<step-id>.png`

### Phase 3: Collect and merge results

As 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 violations
```

### Parallel with cookie-sync (authenticated pages)

If testing authenticated pages, sync cookies once and share the context ID across sessions:

```bash
# 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"
```

### Cleanup

Always stop all sessions when done, even if a test fails:

```bash
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
```