browser-qa

用途：用真实浏览器对 Web 应用做质量检查，发现用户能遇到的问题。适用场景包括构建完前端功能后、提交 UI 变更 PR 前、用户反馈“看起来坏了”时，以及部署后的冒烟测试。\n\n主要能力：启动带真实 Chromium 的 Playwright，访问应用中每个可发现的页面，检查控制台错误、网络失败、资源缺失，测试表单、按钮、链接等交互元素，验证移动端响应性，并生成结构化 QA 报告。\n\n检查类别：1）页面健康：HTTP 状态为 2xx、无 JS 控制台错误、无失败网络请求（4xx/5xx）、无缺失图片或资源、页面 3 秒内加载。2）布局与响应式：桌面 1280px 无横向滚动、无重叠元素；移动 375px 无横向滚动、文本可读、按钮可点；内容未被意外裁剪或隐藏。3）交互元素：按钮点击后有反应（无死按钮）；链接点击后导航到有效页面（无 404）；表单空提交显示校验、有效提交给出成功反馈；下拉框/弹窗打开显示内容、关闭隐藏内容。4）导航流程：导航中每个链接指向有效页面；返回按钮行为符合预期；面包屑（如有）准确；鉴权重定向正常（受保护页面→登录→重定向回来）。5）数据展示：列表有数据时显示数据而非空状态；分页（如有）可用；搜索/筛选更新结果；加载状态在数据请求期间显示；API 失败时显示错误状态。\n\n用法与限制：真实浏览器，仅用 Playwright + Chromium，不做纯 HTTP 测试；默认无头运行，不主动打开可见窗口；同时测试桌面 1280px 与移动 375px；控制台错误视为 bug 必须报告；一次性模式，启动、测试、关闭，无守护进程；失败时截图；不要未经询问就修复，先报告再提议修复。注意：有 WebSocket 或轮询的应用用 networkidle 会一直等待，改用 domcontentloaded 或具体元素选择器；对不可见元素调用 page.click() 会静默通过，交互前先用 await expect(locator).toBeVisible() 验证；移动视口测试需在浏览器上下文设置 hasTouch: true，仅设视口大小会漏掉真实 bug；控制台警告不是错误，别把 React hydration 警告或弃用提示当 bug，只上报 console.error 和失败网络请求；CI 截图与本地不同，字体渲染、抗锯齿与 DPI 有差异，用视觉比较阈值而非像素级匹配。Playwright 代码片段与报告模板见 playwright-snippets.md。