browser-qa

Three-layer browser testing workflow

Parameter format:[layer1|layer2|layer3|all] <target-description>(prefix optional, inferred by intent when triggered via natural language).

Parameter parsing (three levels: explicit prefix > intent inference > asking)

Parse $ARGUMENTS：

Explicit prefix(compatible with legacy usage):layer1|layer2|layer3|all <描述> → execute by prefix
No prefix → intent inference：
- "add/write E2E, regression tests" → Layer 1
- "accept/check/take a look at this page|feature" → Layer 2 (automatically append Layer 3 when failing items are found)
- "diagnose/troubleshoot/why… doesn't work" → Layer 3
- "comprehensive testing/full acceptance" → all
Ambiguous intent(e.g., only a URL is given, no verb) → ask the user for the test goal and expected level

Extract the target description as the feature under test.

Pre-checks

Before executing any layer, complete environment detection first.

Script first: run the detection script bundled with the skill (outputs all filesystem-determinable items at once, replacing multiple rounds of probing):

node <skill-base-directory>/scripts/detect-env.mjs [--cwd <project>]

The output JSON contains node_project / package_manager / playwright_config / playwright_installed / test_dir / suggestions, process each item by suggestions before proceeding to layer execution. The MCP connection status cannot be detected by the script; still confirm it within the session as described in Section 3 below.

When the script is unavailable, fall back to the following manual detection checklist:

1. Project structure scan

检测以下内容是否存在：
├── package.json                # 项目是否为 Node.js 项目
├── playwright.config.*         # Playwright 是否已配置
└── tests/ 或 e2e/ 或 __tests__/ # 测试目录位置

2. Playwright installation detection

If playwright.config.* does not exist → do not directly run npm init playwright@latest(the interactive wizard will hang a non-interactive agent session). Instead use a non-interactive sequence:
```
npm install -D @playwright/test
npx playwright install chromium
```
Then, based on the parallel execution configuration at the end of references/e2e-patterns.md , create a minimal playwright.config.ts. If the user prefers the full scaffold, suggest they run the interactive wizard in their own terminal.
If dependencies are not installed → npm install

3. MCP Server readiness detection

The plugin .mcp.json has pre-configured the following MCP Servers; check whether they are connected properly:

playwright MCP Server (required for Layer 2) — npx @playwright/mcp@latest
chrome-devtools MCP Server (recommended for Layer 3) — npx chrome-devtools-mcp@latest
If MCP is not connected → refer to mcp-setup.md for troubleshooting

4. Browser Harness readiness detection (optional for Layer 3)

Browser Harness is used to penetrate Shadow DOM/iframe; it is an optional tool for Layer 3, not run via MCP but used as a CLI tool.

See installation steps at mcp-setup.md。Installation involves executing instructions from a third-party repository (browser-use/browser-harness); the user must first be informed and consent obtained—this is the trust boundary for external code entering the local machine.

Layer 1: Deterministic E2E testing

Principle: pure native Playwright code, no MCP, no LLM reasoning. Every operation path must be deterministically repeatable.

Execution flow

Step 1: Analyze the feature under test

Based on the user's target description, identify the user flows that need to be tested. For example:

"Login function" → navigate to login page → enter credentials → click submit → verify redirect
"Shopping cart" → add item → view cart → change quantity → checkout

Step 2: Generate E2E test code

Use templates/e2e-test.ts as the template skeleton, combined with the patterns in references/e2e-patterns.md to generate test code.

Patterns that must be followed:

Use data-testid selectors (preferred over CSS selectors and text selectors)
Each test is independent and does not depend on the state of other tests
Arrange → Act → Assert three-part structure
Set reasonable timeouts (default 30s, adjustable per project)
Use test.describe to group by feature
Each test case must contain at least one business assertion that would fail if the functionality were broken (data changes, URL redirects, error messages). Asserting only that elements are visible is prohibited—always-true/too-weak assertions make tests meaningless

Test file placement: consistent with the project's existing test directory structure (tests/、e2e/, or __tests__/）。

Step 3: Run tests

npx playwright test <本次生成的测试文件路径> --reporter=list

Only run the files generated this time—existing project failures are not part of this acceptance scope; mixing them in will pollute the Layer 1 conclusion and falsely trigger Layer 3 diagnostics. If the user explicitly requests a full regression, then run the complete suite, and distinguish between "newly added this time" and "existing failures" in the report.

If there are failing test cases → record failure information, mark as Layer 3 candidates
All pass → output a pass report

Step 4: Output report

## Layer 1 报告: E2E 测试

| 用例 | 状态 | 耗时 |
|------|------|------|
| 用户登录 - 正确凭据 | ✅ PASS | 1.2s |
| 用户登录 - 错误密码 | ✅ PASS | 0.8s |
| 用户登录 - 空表单提交 | ✅ PASS | 0.5s |

总计: 3 通过 / 0 失败

Layer 2: AI autonomous acceptance

Principle: Through Playwright MCP, let the AI Agent autonomously explore the interface and discover interaction issues not covered by E2E. Use natural-language acceptance criteria and tolerate a certain degree of ambiguity.

Prerequisites

Playwright MCP Server is configured (otherwise refer to references/mcp-setup.md）
The target application is accessible (local dev server or online address)

Execution flow

Step 1: Generate the acceptance checklist (two-part)

A fixed checklist has zero relevance to the functionality under test (the login page and the data dashboard should not use the same list). Generate a customized checklist in two parts:

验收目标: {{用户描述}}

1) 定制检查项（3-6 条）: 从目标描述提取功能要点逐条生成
   （如"购物车数量修改后小计实时更新"、"错误密码提交后表单显示明确错误提示"）
2) 通用项筛选: 从下列通用项中只挑选适用的附加
   - 响应式布局（至少桌面端）
   - 页面跳转和导航正确性
   - 加载状态反馈
   - 无明显视觉异常

每条检查项写明: 操作序列（具体步骤） + 预期表现（可观察的结果）

Step 2: Layer 2 orchestration (fully serial—Playwright MCP is a single browser session; parallel driving will destroy each other's state)

checklist = 定制检查项(3-6 条，来自目标描述) + 适用的通用项     # Step 1 两段式生成
results = []
for item in checklist:                       # 串行逐项
    执行 item.ops（browser_navigate / click / type / fill_form ...）
    取证: browser_snapshot 关键片段 或 browser_take_screenshot 文件名
    results += {check, ops, result, evidence_ref, notes}
    # 无证据 → result 只能是 unverified（不允许无证据的 pass）

落盘 browser-check-items 契约 JSON
→ node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-output.mjs browser-check-items <file>
→ 校验失败：按 errors 清单补全一次；再失败将缺失项标记 unverified 并在报告说明

# 对抗复核（仍串行，同一浏览器）：仅 result ∈ {fail, warn} 的项
for item in results where item.result in {fail, warn}:
    以"不信任原结论"的视角重新执行 item.ops 一次:
      - 原判 fail → 优先尝试证明功能其实正常（操作时序问题？选择器选错？等待不足？）
      - 复现成功 → 维持原判并补第二份证据
      - 复现失败 → 降级为 warn 并注明"结果不稳定"

# 证据审计（独立子代理，只读已落盘证据、不操作浏览器——不占浏览器会话，可与上面的复核并行发起）：
#   全部 pass 项批量交给 1 个子代理，输入=契约 JSON + 截图文件 + 各检查项的预期表现，指令为
#   "试图反驳每个 pass：证据是否真能支撑该检查项的预期表现？证据缺失、内容与预期对不上、
#    或只能证明'操作过'不能证明'符合预期'，该项即降级为 unverified 并注明证据缺口"
#   动机：AI 验收的主导失败模式是假阳性，执行者判读自己的证据存在系统性确认偏差——
#   重执行复核只覆盖 fail/warn 方向，pass 方向由主体独立的审计兜底
# 重执行式 pass 复核仍仅在用户要求"严格验收"时抽查 2 项（占浏览器会话，成本控制）

# 复核/审计结论回写契约 JSON 的 items[].recheck（status: 维持/降级/翻案 + evidence_ref）并重新校验

Evidence collection rules: The conclusion for each check item must be accompanied by an evidence reference (key snapshot fragment or screenshot filename). Items without evidence support should be marked as "unverified" rather than "passed"—the value of AI acceptance is built on "actually having operated it"; an unsupported ✅ is more harmful than no report.

Step 3: Output the acceptance report

## Layer 2 报告: AI 自主验收

| 检查项 | 结果 | 证据 | 复核 | 备注 |
|--------|------|------|------|------|
| 购物车数量修改后小计实时更新 | ✅ | snapshot: 小计 ¥58→¥116 | 审计维持（证据含修改前后对比） | 数量 1→2 |
| 错误密码提交显示错误提示 | ⚠️ | screenshot: login-error.png | 维持（第二份证据: snapshot 同现象） | 提示对比度不足 |
| 加载反馈 | ❌ | snapshot: 按钮无 disabled/loading | 维持（复现成功，二次 snapshot 一致） | 可能重复提交 |
| 响应式布局（桌面端） | ✅→未验证 | snapshot: 1280px 布局正常 | 审计降级（证据为首屏截图，未覆盖布局完整性） | 需补证 |
| 导航正确性 | 未验证 | —（会话超时未操作到该项） | — | 需补测 |

发现问题: 2（1 警告 / 1 阻塞）；未验证: 1
建议: 为提交按钮添加 loading/disabled 状态

There are only four possible results:✅ 通过(has evidence and confirmed by audit),⚠️ 警告(has evidence),❌ 阻塞(has evidence),未验证(no evidence, evidence does not support the conclusion, or not executed—unsupported ✅ is not allowed). The review column records: for fail/warn items = re-execution review conclusion (maintain/downgrade/overturn + second evidence reference); for pass items = evidence audit conclusion (audit maintain/audit downgrade + gap explanation).

Layer 3: Debugging and diagnosis

Principle: Perform in-depth diagnosis for failures in Layer 1/2. Execute only when failures exist.

Trigger conditions

Layer 1 has E2E test failures
Layer 2 detected an interaction anomaly
The user explicitly requested diagnosis of a specific problem

Execution flow

Step 1: Failure classification

Classify failures into the following categories:

Rendering issues: elements invisible, layout broken, styles abnormal
Performance issues: slow loading, laggy interactions, oversized resources
Logic issues: incorrect functionality, state management errors
Network issues: request failures, timeouts, CORS errors

Step 2: Select diagnostic tools based on category

Problem category	Diagnostic tool	Action
Rendering issues	Playwright MCP	Screenshot comparison, DOM structure inspection
Rendering issues (Shadow DOM/iframe)	Browser Harness	Coordinate click-through inspection
Performance issues	Chrome DevTools MCP	Record performance trace
Network issues	Chrome DevTools MCP	Check network request waterfall
Logic issues	Playwright MCP + source code analysis	Interaction reproduction + code review

Step 3: Execute diagnosis

Chrome DevTools MCP diagnostic flow:

performance_start_trace → Start recording
Execute the operation that triggers the problem via MCP
Stop recording → analyze trace results
Check console errors, network requests, rendering frame rate

Browser Harness diagnostic flow(only in Shadow DOM/iframe scenarios):

If Browser Harness is not installed, follow the steps in mcp-setup.md to install it (requires user consent first).

Connect to a real Chrome browser via CLI (CDP WebSocket)
Use coordinate clicks (Input.dispatchMouseEvent) to locate the problematic element
Inspect rendering state across DOM boundaries (piercing iframe/Shadow DOM/cross-origin boundaries)

The root cause must be hypothesis-verified before being written into the report: make one observable prediction following "if the root cause holds, doing X should observe Y" and actually verify it (read the source code to confirm the corresponding line indeed lacks that logic / reproduce once to confirm the phenomenon matches the root cause). If verification is inconsistent → return to Step 1 and reclassify and diagnose — an unverified reasoning conclusion will lead the user to fix in the wrong direction and mask the true cause.

Step 4: Output diagnostic report

## Layer 3 报告: 调试诊断

### 问题 1: 提交按钮无 loading 状态

**根因**: 提交按钮未绑定 isLoading 状态，点击后无视觉反馈
**诊断工具**: Playwright MCP (DOM 快照) + 源码分析
**定位**: src/components/LoginForm.tsx:42 — handleSubmit 缺少 isSubmitting 状态
**验证**: 预测"点击提交后按钮无 disabled 属性变化"——snapshot 复核一致；源码确认 42 行无 isSubmitting 绑定
**修复建议**:
  1. 在 handleSubmit 开始时 setSubmitting(true)
  2. Button 组件添加 disabled={isSubmitting}
  3. 添加 Spinner 或文字变更 "登录中..."
**优先级**: P1 — 影响用户体验，可能导致重复提交

Final summary report

After all layers have finished executing, output the merged report.

Output convention: if triggered by spec-flow accept (or another workflow), the report file and screenshots are written to the evidence directory specified by the caller (e.g. .specs/active/<id>/evidence/browser/) and the file paths are returned — a report only printed in the conversation cannot be referenced by subsequent acceptance orchestration. When addressing the user directly, outputting in the conversation is sufficient.

# 浏览器测试报告: {{目标功能}}
# 时间: {{当前时间}}

## 总览

| 层级 | 状态 | 通过 | 失败 | 警告 |
|------|------|------|------|------|
| Layer 1: E2E 测试 | ✅ | 3 | 0 | 0 |
| Layer 2: AI 验收 | ⚠️ | 5 | 1 | 1 |
| Layer 3: 调试诊断 | ✅ | 1 个根因已定位 | — | — |

## 关键发现

1. [P1] 提交按钮缺少 loading 状态（Layer 2 发现 → Layer 3 定位）
2. [P3] 错误提示颜色对比度不足（Layer 2 发现，建议修复）

## 修复建议优先级

1. **立即修复**: LoginForm.tsx 添加 isSubmitting 状态
2. **建议改进**: 调整错误提示文字颜色为符合 WCAG AA 标准的对比度

## 附件

- E2E 测试文件: `tests/login.spec.ts`
- 验收截图: (如需要，可通过 MCP 工具截图)

Notes

Things not to do

Do not run E2E with MCP: Layer 1 must be pure native Playwright code to ensure determinism
Do not use an LLM in Layer 1: test assertions must match exactly, probabilistic judgments are not tolerated
Do not skip prerequisite checks: an unconfigured MCP Server will cause Layer 2/3 to fail
Do not run Layer 2 in CI: AI acceptance consumes Tokens, suitable only for manual triggering
Do not drive the browser in parallel: Multiple sub-agents operating the same Playwright MCP session simultaneously will corrupt each other's page state (single-instance hard constraint); all Layer 2 checks and reviews are executed serially

Flexible adjustments

If the project is not a Node.js/Playwright tech stack, Layer 1 can be adapted to the corresponding testing framework (Cypress, Vitest, etc.)
If the user only needs quick acceptance, Layer 1 can be skipped and Layer 2 executed directly
If all tests pass, Layer 3 is automatically skipped

Reference materials

MCP Server configuration guide: references/mcp-setup.md
E2E testing patterns: references/e2e-patterns.md
Test file templates: templates/e2e-test.ts

About this skill

Parameter parsing (three levels: explicit prefix > intent inference > asking)

Pre-checks

1. Project structure scan

2. Playwright installation detection

3. MCP Server readiness detection

4. Browser Harness readiness detection (optional for Layer 3)

Layer 1: Deterministic E2E testing

Execution flow

Step 1: Analyze the feature under test

Step 2: Generate E2E test code

Step 3: Run tests

Step 4: Output report

Layer 2: AI autonomous acceptance

Prerequisites

Execution flow

Step 1: Generate the acceptance checklist (two-part)

Step 2: Layer 2 orchestration (fully serial—Playwright MCP is a single browser session; parallel driving will destroy each other's state)

Step 3: Output the acceptance report

Layer 3: Debugging and diagnosis

Trigger conditions

Execution flow

Step 1: Failure classification

Step 2: Select diagnostic tools based on category

Step 3: Execute diagnosis

Step 4: Output diagnostic report

Final summary report

Notes

Things not to do

Flexible adjustments

Reference materials