使用 Playwright CLI 进行视觉 QA
黄金法则：没有新鲜的命令输出就没有结论。绝不能只说“应该看起来没问题”。
最小化设置
- Playwright 作为项目的 devDependency；
playwright.config.ts需显式设置 viewport 为 375px（不要用devices['Pixel 7']，那是 412px），并包含desktop-chrome和mobile-chrome两个项目。 - 截图脚本位于
scripts/shot.mjs（不要使用 MCP 来做这个：CLI 更快且可重复）。 - 对于 axe：
@axe-core/playwright。 - 提供生产构建（
npm run build && npm run start）来测量真实性能；仅调试时使用开发环境。
每页和每区域设置需执行的检查
- 控制台和网络：
page.on('console')、page.on('pageerror')、page.on('requestfailed')以及状态码 ≥400 的响应。失败 = 红色。 - 溢出：在每个视口检查
document.documentElement.scrollWidth <= clientWidth + 1；如果存在溢出，列出导致问题的元素（getBoundingClientRect().right > innerWidth）。 - 无障碍：axe 无
critical/serious违规；只有一个h1；完整的img[alt]；所有可交互元素可见焦点（使用真实键盘检查:focus-visible，不要用肉眼检查 CSS）；逻辑的 Tab 顺序。 - Reduced motion：
page.emulateMedia({ reducedMotion: 'reduce' })；不应出现旋转、自动播放或超过 200ms 的动画。 - 链接：提取所有
href，验证内部链接（200）并将外部链接标记为信息性；0 个无事件处理器的href="#"。 - SEO：
title、meta description、canonical、OG、各区域设置的hreflang、可解析的 JSON-LD、sitemap.xml和robots.txt返回 200。 - 性能：加载后使用 PerformanceObserver 测量 LCP/CLS；桌面上 LCP 目标 < 2.5s，CLS < 0.1；通过 rAF 在自动滚动 5 秒内统计长帧（>50ms）来测量滚动卡顿。
- Canvas/滚动：由于 headless 模式下 Canvas 可能输出黑色，需通过 DOM 验证：元素具有期望的透明度/变换、节拍文本在正确范围内存在且可见，以及（如果存在）暴露在
window上的状态。
循环
- 每次执行后：提供包含门控/命令/结果/状态的表格报告，以及带有证据（选择器、日志或截图）的阻塞项列表。
- 如果某个门控失败：修复（自己的测试/脚本）或提出具体的
src/修复方案并附上证据；重复完整的循环。 - 将带日期的截图保存到
docs/qa/（每个主要区域设置的桌面 + 移动端），并与基线比较以检测回归。 - 如果仍有门控处于红色或未执行状态，则不得声明“就绪”。
诚实的局限性
- 无法在 headless 模式下验证真实 iOS 上的帧序列：应在报告中注明。
- 通过
npx lighthouse运行 Lighthouse 是可选的，但在生产构建中推荐使用；如果无法运行，应如实说明而非估算。