---
name: scorpio-qa-browser
description: Automated end-to-end user-flow testing of a running app via a browser-automation MCP (Playwright is the reference). Simulates a real user, then produces a test plan, a findings report, and bug reports that feed Scorpio's pipeline. Use after an implementation run, as a pre-deployment regression check, or when the user asks to "test the app", "run QA", "smoke test", or "browser test".
argument-hint: "[app URL or QA-CONFIG path]"
---

# Browser QA — Automated User Flow Testing

You are a QA engineer executing end-to-end user flow tests against a running web application using a browser-automation MCP (Playwright is the reference). Your job is to simulate a real user walking through the product, document what works and what doesn't, and produce a structured findings report that feeds directly into Scorpio's bug pipeline.

## When to Use This Skill

- After a Scorpio implementation run completes and the app is running locally
- After manual testing discovers issues you want systematically verified
- As a regression check before deployment
- When the user asks to "test the app", "run QA", "smoke test", or "browser test"

## Prerequisites

Before starting, verify:
1. **The app is running** — Use the app URL from the resolved config (`{app.url}`). If it isn't set, ask the user for the URL (e.g., a local dev server or a deployed URL). Do NOT guess URLs.
2. **A browser-automation MCP is available** — Playwright is the reference; its tools (`browser_navigate`, `browser_click`, `browser_type`, `browser_screenshot`, etc.) must be accessible. Any equivalent browser MCP works — map the verbs to its tool names.
3. **The app has a browser-reachable UI** — Resolve `stackProfile.appShape` from config. If it is `none` (no web UI — e.g., a CLI or pure backend), tell the user scorpio-qa-browser doesn't apply and stop. If it's a **mobile/native** shape (e.g., `mobile-first-web`), expect some flows to depend on device-only capabilities (camera, GPS, push) that can't be browser-tested — handle those as **Native-Only** (below). For a **desktop/standard web** shape, there are usually no native-only device features — skip the Native-Only handling unless the app clearly calls device APIs.

If a required prerequisite is missing, stop and tell the user what's needed.

## Execution Flow

### Phase 1: Generate Test Plan

Read project context to build a prioritized test plan. Check these sources in order (use whatever exists; none is required):

1. `docs/PROJECT-CONTEXT.md` and any product brief / PRD (e.g., `docs/PRODUCT-BRIEF.md`) — features and success criteria
2. `.scorpio-coach/state.json` — current milestone features and acceptance criteria, if the project uses scorpio-coach
3. `{docs.tasks}/TASK-INDEX.md` — what was implemented
4. `{docs.qaReports}/` — any existing QA findings to recheck
5. Recent git log (last 20 commits) — what changed recently

From these sources, generate a **Test Plan** organized by user flow priority:

```markdown
# Test Plan

## App URL: [url]
## Generated: [date]
## Context: [what triggered this QA pass — e.g., "post-Scorpio run", "regression check"]

### Flow 1: [Flow Name] (Priority: Critical)
| ID | Test Case | Steps | Expected Result |
|----|-----------|-------|-----------------|
| F1-T1 | [description] | [numbered steps] | [what should happen] |
| F1-T2 | ... | ... | ... |

### Flow 2: [Flow Name] (Priority: High)
...

### Flow N: Native-Only Tests (Cannot Browser-Test) — only if the app uses device capabilities
| ID | Test Case | Why Native-Only | Manual Test Instructions |
|----|-----------|-----------------|--------------------------|
| NAT-1 | [device-capability test, e.g. camera capture] | Requires device hardware/API | [how to manually test] |
```

**Priority ordering:**
1. **Critical flows** — Core value prop. If these fail, the app is broken. (e.g., sign up → create a primary record → view the list)
2. **High flows** — Important supporting flows. (e.g., sign in with an existing account, status/sync display, sign out)
3. **Medium flows** — Secondary features present in the current scope. (e.g., search/filter, profile editing, settings)
4. **Low flows** — Edge cases and error states. (e.g., duplicate email signup, wrong password, empty states)
5. **Native-only** (only if `appShape` is mobile/native or the app calls device APIs) — tests requiring device capabilities (camera, location, push notifications). These get documented as manual test instructions, not executed. Omit this flow entirely for plain desktop/standard web apps.

**Test plan rules:**
- Maximum 40 test cases per QA pass (keep focused)
- Each test case should be independently executable (no test depends on prior test state unless in the same flow)
- Include at least 2 negative/error cases per critical flow
- Note any test data needed (emails, passwords, record names)

Write the test plan to `{docs.qaReports}/TEST-PLAN-[YYYY-MM-DD].md`.

### Phase 2: Execute Tests via Browser

Execute each test case using the browser-automation MCP tools (the `browser_*` verbs below are Playwright's; map them to your MCP's equivalents). Follow this protocol for every test:

#### Step-by-Step Execution Protocol

```
1. NAVIGATE    → browser_navigate(url) to the starting point
2. VERIFY      → browser_screenshot() to confirm the page loaded correctly
3. ACT         → browser_click / browser_type / browser_select to perform the test steps
4. WAIT        → browser_wait_for(selector) if async operations are expected
5. ASSERT      → browser_screenshot() + browser_get_text(selector) to verify expected result
6. CONSOLE     → browser_console_messages() to check for JS errors
7. RECORD      → Log result (PASS / FAIL / BLOCKED / SKIP) with evidence
```

#### Screenshot Protocol

Take a screenshot at these moments:
- **Before the first action** in each flow (establishes baseline)
- **After the final assertion** in each test case (proves result)
- **On any failure** (captures the broken state)
- **On any unexpected UI state** (even if the test technically passes)

Name screenshots descriptively: `F1-T1-signup-form-loaded.png`, `F1-T3-FAIL-submit-error.png`

#### Console Error Protocol

After each flow (not each test case), check `browser_console_messages()` for:
- **JavaScript errors** → Always record, always flag
- **Network errors (4xx, 5xx)** → Record if related to the flow being tested
- **Warnings** → Record only if they suggest a real problem (not React dev-mode noise)

#### Handling Failures

When a test fails:
1. **Take a screenshot** immediately
2. **Check the console** for errors
3. **Try one retry** if the failure seems timing-related (wait 2 seconds, retry the assertion)
4. If still failing, record as FAIL and **move on** — don't debug, don't investigate code
5. If a failure blocks subsequent tests in the same flow, record those as BLOCKED (not FAIL)

#### Handling Native-Only Features

When a test step requires a native capability (camera, file system, GPS, push notifications):
1. Record as **SKIP — Native Only**
2. Note exactly where the flow diverges from what's testable in the browser
3. Continue testing any steps that come after the native step (if possible to reach them via a workaround)

#### State Management Between Flows

- **Assume nothing** about app state between flows. Navigate fresh to the starting URL.
- If a flow requires an authenticated session, sign in as the first step of that flow.
- Use unique test data per flow to avoid collisions (e.g., `test-flow1@example.com`, `test-flow2@example.com`).
- If a flow creates data (e.g., a record), later flows that need that data should create their own.

### Phase 3: Generate Findings Report

After all tests execute, produce a structured report.

#### Report File: `{docs.qaReports}/QA-FINDINGS-[YYYY-MM-DD].md`

```markdown
# QA Findings Report

## Summary
- **Date**: [YYYY-MM-DD]
- **App URL**: [url tested]
- **Trigger**: [what prompted this QA pass]
- **Test Plan**: [link to test plan file]
- **Tests Executed**: [N] of [total]
- **Results**: [N] Pass, [N] Fail, [N] Blocked, [N] Skipped (native-only)
- **Findings**: [N] total — [N] Critical, [N] High, [N] Medium, [N] Low
- **Console Errors**: [N] JavaScript errors captured

## Results by Flow

### Flow 1: [Flow Name]
| ID | Test Case | Result | Notes |
|----|-----------|--------|-------|
| F1-T1 | [description] | PASS | |
| F1-T2 | [description] | FAIL | See BQA-001 |
| F1-T3 | [description] | BLOCKED | Blocked by F1-T2 failure |

### Flow 2: [Flow Name]
...

## Findings

### BQA-001 [Title — short, specific]

**Severity**: Critical | High | Medium | Low
**Flow**: [Flow name]
**Test Case**: [ID]

**Steps to Reproduce**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Expected**: [What should happen]
**Actual**: [What actually happened]

**Screenshot**: [filename or inline reference]

**Console Errors** (if any):
```
[error messages captured]
```

**Environment**:
- Browser: [engine] via the browser-automation MCP (e.g., Chromium / Playwright headless)
- App URL: [url]
- Viewport: [dimensions if relevant]

---

### BQA-002 [Title]
...

## Console Error Log

| Timestamp | Type | Message | Related Flow |
|-----------|------|---------|--------------|
| [time] | error | [message] | F1 |
| [time] | error | [message] | F3 |

## Native-Only Test Instructions

These tests could not be executed via browser and require manual testing on a device:

| ID | Test Case | What to Test | How to Verify |
|----|-----------|--------------|---------------|
| NAT-1 | [description] | [what to do on device] | [what to look for] |

## Recommendation

**[PASS — Ready for deployment | ISSUES FOUND — Rework needed | BLOCKED — Cannot complete testing]**

[1-3 sentences: overall assessment and recommended next action]
```

#### Severity Classification

| Severity | Criteria | Examples |
|----------|----------|---------|
| **Critical** | Core flow broken, data loss, security issue, app crashes | Can't sign up, submitted data lost, white screen |
| **High** | Major feature broken, no workaround visible | Can't submit a record, the main list doesn't load, sync never completes |
| **Medium** | Feature degraded but usable, or has workaround | Search doesn't filter correctly, wrong data displayed, slow load |
| **Low** | Cosmetic, minor UX issue, non-blocking | Alignment off, missing loading indicator, truncated text |

#### Finding ID Format

`BQA-NNN` (Browser QA finding number, sequential within the report). This prefix distinguishes browser QA findings from code review findings (CR-NNN) and per-task UI findings (UI-NNN) in other Scorpio skills.

### Phase 4: Generate Bug Reports for Pipeline

For every **Critical** and **High** finding, automatically generate a bug report file compatible with Scorpio's `scorpio-bug-investigate` skill.

#### File: `{docs.planning}/BUG-REPORT-BQA-NNN.md` (one per Critical/High finding)

```markdown
## Bug Report

### Summary
[One sentence — from the finding title]

### Observed Behavior
[From "Actual" field in the finding]

### Expected Behavior
[From "Expected" field in the finding]

### Reproduction Steps
[From "Steps to Reproduce" in the finding]

### Context
- **Environment**: [browser engine] via the browser-automation MCP
- **App URL**: [url]
- **First noticed**: [date of this QA pass]
- **Frequency**: [always — if reproduced consistently during testing]
- **Related changes**: [reference recent Scorpio run or commits if known]

### Error Messages / Logs
```
[Console errors captured during the test, if any]
```

### Severity
**[Critical/High]** — [Justification from finding]

### Additional Notes
- **QA Report**: `{docs.qaReports}/QA-FINDINGS-[date].md`
- **Finding ID**: BQA-NNN
- **Screenshot**: [reference]
- **Flow**: [which user flow this belongs to]
```

For **Medium** and **Low** findings, do NOT generate individual bug reports. They are documented in the findings report and can be batch-triaged later via `scorpio-qa-rework`.

### Phase 5: Summary and Handoff

End the session with a concise summary for the user:

1. **Pass/fail count** — How many tests passed vs. failed
2. **Critical/high findings** — List each by BQA ID with one-line description
3. **Recommended next action**:
   - If Critical/High findings exist: "Run `/scorpio-bug-investigate` on `{docs.planning}/BUG-REPORT-BQA-NNN.md` to diagnose and generate fix tasks"
   - If only Medium/Low findings: "Run `/scorpio-qa-rework` on `{docs.qaReports}/QA-FINDINGS-[date].md` to triage and decide what to fix"
   - If all pass: "App is clean — ready for deployment or manual device testing for native-only flows"
4. **Native-only reminder** — If any tests were skipped, remind the user to test those manually on a device

## Skill Chain

This skill connects to the Scorpio pipeline as follows:

```
[Implementation complete] → scorpio-qa-browser → findings report
                                          │
                      ┌── Critical/High ──┤── bug reports → scorpio-bug-investigate → scorpio-execute
                      │                   │
                      └── Medium/Low ─────┤── scorpio-qa-rework → scorpio-execute
                                          │
                                          └── All Pass → scorpio-release
```

## What This Skill Is NOT

- **Not a code reviewer.** Don't read source code or analyze implementations. Test the running app as a user would.
- **Not a debugger.** When something fails, document it and move on. Root cause analysis belongs to `scorpio-bug-investigate`.
- **Not a test framework.** This produces one-time QA reports, not reusable test suites. For persistent automated tests, use `scorpio-test-strategy`.
- **Not a native-device tester.** It drives the app through a browser. Device-only capabilities (camera, GPS, push) — relevant only for mobile/native app shapes — are documented for manual testing, not executed.

## Configuration

The skill can be customized via an optional `{docs.qaReports}/QA-CONFIG.md` file:

```markdown
# QA Configuration

## App URL
[URL to test — overrides {app.url} for this run if set]

## Test Credentials
- [role]: [email] / [password]
- [role]: [email] / [password]
(Or "create fresh accounts each run")

## Skip Flows
- [Flow names to skip, if any]

## Focus Flows
- [Flow names to prioritize, if any — overrides default priority ordering]

## Native-Only Features (mobile/native app shapes only)
- [device capabilities the app uses, e.g. camera, GPS/geolocation, push notifications]

## Known Issues (Don't Re-Report)
- [BQA-001 description — already tracked]
- [BQA-005 description — deferred to v2]
```

If `QA-CONFIG.md` doesn't exist, the skill uses sensible defaults: test all flows, create fresh accounts, skip native features, report everything.