需要跨浏览器测试时：用分析数据设计浏览器矩阵并执行测试…

适用于需要决定测试哪些浏览器、配置 Playwright/云平台跨浏览器执行、并记录浏览器差异的场景。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`；若存在则使用其中信息，跳过已回答的问题。
2. 从分析工具导出最近 90 天的浏览器/OS 数据，按会话占比排序。
3. 将会话占比分组为 P0/P1/P2/Skip 等层级，并为每层分配测试覆盖：P0 >10% 每次 PR/部署跑全量；P1 3-10% nightly/pre-release 跑 smoke + 关键路径；P2 1-3% 每周/pre-release 跑 smoke；<1% 不测试，仅在收到报告时手动抽查。
4. 创建浏览器矩阵文件（如 markdown 表格），包含 Browser、Version、Platform、Traffic %、Tier、Notes，并记录 next-review 日期。
5. 版本覆盖策略：始终测试当前稳定版；仅对分析显示 >1% 使用旧版本的 P0 浏览器测试 Latest - 1；仅当企业用户占比显著时测试 Firefox ESR；不要测试 Beta/Canary/Nightly，除非你是浏览器厂商或构建面向浏览器的工具。
6. 将桌面和移动浏览器作为独立矩阵条目：Mobile Safari on iOS 和 Chrome on Android 与桌面版渲染不同。
7. 决定采用渐进增强还是像素完美，以确定通过/失败标准；渐进增强接受优雅降级，像素完美要求相同渲染。
8. 如果项目已有 Playwright 配置，将跨浏览器测试作为配置变更而不是引入新工具。
9. 定义「可用」为：核心功能可操作、内容可访问、布局可用；接受阴影、渐变、动画时序等视觉差异。
10. 优先测试 Safari 和 Firefox，因为它们与 Chromium 行为差异最大。
11. 测试用户能否完成任务，而不是测试 CSS 属性渲染是否相同；像素级差异交给视觉比较工具。
12. 报告覆盖率时写明 WebKit coverage 而不是 Safari coverage，除非在云网格上运行了真实 Safari；Playwright 的 WebKit ≠ Safari，Chromium ≠ Chrome。
13. 一套测试多处运行：只写一次测试，通过配置在多个浏览器项目上运行；绝不为不同浏览器复制测试逻辑。
14. 在 Playwright 中定义每个矩阵条目对应一个 project；用 `devices[...]` 映射移动设备；用 `channel` 选项驱动本地安装的品牌浏览器。
15. 当需要与捆绑引擎不同的真实品牌行为时使用 channels：安装的 Chrome (`channel: 'chrome'`) 或 Edge (`channel: 'msedge'`) 用于扩展支持、企业策略、编解码器；WebKit 和 Firefox 没有 channel 选项，始终使用 Playwright 捆绑引擎。
16. 配置中只保留一个 `edge` project，不要同时合并 `msedge` channel 片段；它们是示例替代方案。
17. 使用 `page.screencast()`（Playwright 1.59+，1.60 当前）捕获带注释的跨浏览器运行视频，用于人工审查矩阵失败。
18. 对 agent 驱动的重跑和单步调试，使用 `--ui`（UI 模式）或 `--debug`（Inspector）；`PWDEBUG=1` 和 `--headed` 是其他真实入口；没有 `--debug=cli` 标志。
19. 云平台配置：使用 BrowserStack、Sauce Labs 等提供真实品牌浏览器/OS 实例，Playwright 通过 CDP/Playwright WebSocket endpoint 连接。
20. 通过环境变量传入云平台凭据和 capabilities；将平台的 `playwrightVersion` 与 `package.json` 中的 Playwright 版本对齐（当前 1.60.x），避免 socket 错误。
21. BrowserStack 新设置推荐 `npx browserstack-node-sdk` runner 加 `client.playwrightVersion` capability（以及 `browserstack.playwrightVersion`）使客户端和网格 socket 同步；原始 `wsEndpoint`/CDP 配置仍可用于直接连接。
22. 对常见跨浏览器差异，为每个引擎编写检测模式和修复；覆盖：iframe 中的 partitioned cookies/CHIPS、`<input type="date">`、Clipboard API、`scroll-behavior`、`backdrop-filter`、`<dialog>` 元素、View Transitions、Web Animations timing。
23. 对第三方 cookie：在每个引擎的 iframe 中测试，而不是只测「浏览器支持 cookie」；参考 per-engine iframe test。
24. 对 `:has()` 选择器性能：若页面在某引擎卡顿则在该引擎 profile；减少 `:has()` 作用域；在 `visual-testing` 中做视觉回归。
25. 对跨文档 View Transitions：视为渐进增强，验证无过渡回退；同文档过渡已是 Baseline，不再作为差异。
26. 对 WebDriver BiDi：作为 watch list；新跨 runner 项目可关注，Selenium 4 已生产就绪，Playwright 部分支持。
27. 当差异真实且无法立即修复时，记录到提交的文件 `docs/browser-issues.md`。
28. 在 known-issues 表中，每行包含：Affected browser、Repro、Workaround/fallback/ticket、Test asserts（用户结果，不是 CSS）。
29. 每个差异一行；没有 ticket 和 fallback 的行是未关闭 bug，不是已记录问题。
30. 对浏览器特定测试逻辑，仅当行为真正不同时才根据 `browserName` 分支（例如 WebKit date-input fallback、Chromium-only clipboard permission）；保持这种分支稀少，过多分支说明应用兼容性 bug 需要修复。
31. 视觉跨浏览器比较：使用 `toHaveScreenshot` 加 `maxDiffPixelRatio` 容差；每个浏览器项目生成自己的基线（如 `homepage-chromium.png`、`homepage-webkit.png` 等）；阈值策略和基线管理用 `visual-testing`。
32. 渐进增强验证：中止脚本请求（仅 Chromium），验证核心功能仍能通过原生 HTML 工作。
33. 避免像素完美断言无容差；使用 `maxDiffPixelRatio` 或 `maxDiffPixels`。
34. 云测试 socket/handshake 失败时：将 `playwrightVersion`/`client.playwrightVersion` 设置为与 `npx playwright --version` 匹配；使用 `browserstack-node-sdk` runner。
35. Clipboard 测试在 Chromium 通过但在 Firefox/WebKit 失败时：断言 UI 反馈（如 `Copied!`）而不是 clipboard API；仅在 `browserName === 'chromium'` 时启用 `grantPermissions`。
36. 渐进增强测试在 Firefox/WebKit 报错时：脚本中止路由拦截仅 Chromium 支持；在 `browserName === 'chromium'` 时启用该路由，其他地方跳过 JS-disabled 断言。
37. WebKit project 通过但真实 Safari 用户报告问题时：为受影响流程在云网格添加真实 Safari 行。
38. 视觉基线差异仅某一浏览器爆炸时：为每个 project 生成独立基线；每个浏览器保留自己的 `*-<project>.png`。
39. 完成标准：浏览器矩阵使用真实分析数据（最近 90 天），P0/P1/P2 层级有文档并依据流量占比，提交到带 `next-review` 日期的文件。
40. Playwright project 配置（或 BrowserStack/Sauce Labs 配置）反映矩阵，P0 浏览器每次 PR 运行；云配置固定 `playwrightVersion` 与 `package.json` 匹配。
41. `docs/browser-issues.md` 存在，每个已知差异一行，包含受影响浏览器、复现、workaround/fallback 或链接 ticket、断言用户结果（不是 CSS）的测试。
42. 对 P0/P1 浏览器相关的常见差异清单（partitioned cookies、date inputs、clipboard、scroll behavior、backdrop-filter、`<dialog>`、View Transitions）每项有测试或 known-issues 行。
43. 为下一次季度矩阵审查创建跟踪 issue（或矩阵文件 `next-review` 日期在未来），避免刷新丢失。
44. 参考文件：`references/playwright-and-cloud-config.md` 提供 `playwright.config.ts` project 列表、branded channels、`--project` 运行命令、BrowserStack/Sauce Labs/CI 矩阵配置；`references/common-browser-issues.md` 提供 per-engine partitioned-cookie iframe test、date-input WebKit fallback、clipboard、scroll behavior、backdrop-filter、`<dialog>`、View Transitions、Web Animations；`references/testing-patterns.md` 提供 same-test-multiple-browsers、`browserName` branching、visual comparison、progressive-enhancement 的可运行代码。

适用边界 · 注意事项

• 需要像素级基线策略和阈值调优时，应使用 visual-testing。
• 需要原生/混合应用的设备农场测试时，应使用 mobile-testing。
• 除非你是浏览器厂商或构建面向浏览器的工具，否则不要测试 Beta/Canary/Nightly 版本。