# Zc Browser QA Testing

> 浏览器质检

- Skill: `zmice/zc-browser-qa-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmice/zc-browser-qa-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmice/zc-browser-qa-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zmice (https://skillmd.com/u/zmice)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zmice/zc-browser-qa-testing

---


# Browser QA Testing

## 角色定位

用真实浏览器验证用户是否真的能完成关键路径。单元测试和 API 测试不能证明页面可用、交互可达、网络错误可见或视觉没有严重错位；浏览器 QA 用运行中的应用和可复查证据补上这层门禁。

本文只给执行骨架。项目已有 Playwright/Cypress/Puppeteer 时优先沿用；没有既有选择时默认 Playwright。

## 何时使用

- 前端页面、组件、导航、表单或状态流改动后。
- 后端 API 改动会影响前端体验时。
- 发布前需要最终用户路径证据时。
- bug 报告来自浏览器行为、视觉错位或交互失败时。
- 单元/API 测试通过，但仍需要确认真实页面没有空白、控制台错误或不可操作状态时。

不适用：纯后端逻辑、纯文档、无需浏览器渲染的配置改动。

## 快速路径

1. 明确 1-3 条失败就不能放行的关键路径。
2. 启动应用或确认目标 URL 可访问。
3. 准备稳定测试数据，避免依赖生产数据。
4. 驱动真实浏览器执行关键路径。
5. 同时检查 DOM 可见结果、控制台错误、网络失败和基本响应式。
6. 失败时保留截图、trace、控制台或网络证据。
7. 修复后重跑原始失败路径，证明不再复发。

## 工具选择

| 工具 | 默认判断 |
|---|---|
| Playwright | 默认推荐，适合跨浏览器、trace、截图、自动等待和 CI |
| Cypress | 项目已经使用 Cypress 时沿用 |
| Puppeteer | 只在需要 Chrome DevTools Protocol 细节时使用 |
| Browser plugin / in-app browser | 适合快速人工式走查和本地交互验证 |

不要为了浏览器 QA 引入第二套 E2E 框架，除非现有工具无法覆盖目标。

## 关键路径选择

优先级：

- P0：应用能打开，核心页面不是空白。
- P1：主要业务动作能完成，并看到可验证结果。
- P2：错误路径有明确反馈，不是静默失败。
- P3：关键移动端/桌面布局没有阻塞性重叠。

bug 修复场景必须先覆盖：

- 原始失败如何复现。
- 修复后如何证明失败不再发生。

## 验收记录格式

浏览器 QA 的结果必须能被复查：

```text
Browser QA transcript:
- Target:
- Build/server:
- Paths tested:
- Data setup:
- Evidence:
- Console/network:
- Screenshots/traces:
- Result:
- Follow-up:
```

没有证据的“我点过了”不算完成。

## 最小检查清单

- 页面加载成功，没有白屏或阻塞性错误。
- 关键按钮、输入框、菜单、弹窗可访问。
- 主流程成功结果可见。
- 失败路径有用户可理解的错误反馈。
- 控制台没有与本次改动相关的新错误。
- 网络请求状态和错误处理符合预期。
- 关键视口下文本和控件不重叠。

## 与自动化测试的关系

- 已有稳定 E2E：优先运行并补充必要断言。
- 没有 E2E：先做最小浏览器走查，再决定是否把路径沉淀为 Playwright 测试。
- 一次性验证：可以只保留 transcript 和截图。
- 高风险回归：应补自动化测试，避免下次靠人工记忆。

## 常见失败处理

- 白屏：先看控制台、构建输出和入口资源 404。
- 点击无效：检查元素是否被遮挡、disabled、事件未绑定或异步状态未完成。
- 表单失败：检查校验、提交 payload、接口响应和错误反馈。
- 布局错位：截 desktop/mobile 两个视口，定位固定宽度、溢出和层级遮挡。
- 间歇失败：避免 `sleep`，使用明确的可见性、URL、网络或状态等待条件。

## 边界

- 不把浏览器 QA 当成完整可访问性审计；需要深挖时转专项工具。
- 不把视觉主观偏好当成阻塞问题，除非它影响可用性或验收标准。
- 不连接生产数据做破坏性动作。
- 不在没有目标路径的情况下机械铺满长尾场景。

## 推荐输出

```text
Recommendation: <放行 / 修复后重测 / 补自动化测试> because <浏览器证据、失败影响和替代方案 trade-off>。
```

推荐必须说明证据来自哪条路径，以及未覆盖风险是什么。