cross-browser-testing

仅在 Chrome 中测试会带来虚假的信心：在 Chromium 中正常的布局可能在 WebKit 中崩坏，在 Chrome 中成功的剪贴板调用可能在 Firefox 中悄无声息地失效，而分区 Cookie 流程可能在所有浏览器中都通过，唯独在用户使用的那个引擎中失败。这项技能会生成由分析数据驱动的浏览器矩阵、用于运行该矩阵的 Playwright（或云平台）配置，以及一份已提交的已知浏览器差异记录——每项差异都由一个断言用户结果（而非 CSS）的测试验证。

快速导航

情况	前往
需要决定要测试哪些浏览器	浏览器矩阵设计
已在使用 Playwright，只需添加浏览器	Playwright 浏览器配置 → references/playwright-and-cloud-config.md
需要真实 Safari／Windows／旧版 OS，而不只是引擎	云平台设置
某个浏览器表现异常；想为此编写测试	常见跨浏览器问题 + references/testing-patterns.md 中的 browserName 分支
需要记录某项差异，避免重复调试	已知问题日志
像素差异／基线阈值	使用 visual-testing

调研问题

先检查 .agents/qa-project-context.md——如果文件存在，就使用其中的信息，并跳过已回答的问题。然后：

1. 根据分析数据确定目标浏览器： 实际用户使用哪些浏览器？从分析工具中提取浏览器／OS 数据。测试无人使用的浏览器是浪费；漏掉 15% 用户依赖的浏览器则是一个缺陷。
2. 桌面端和移动端？ iOS 上的 Mobile Safari 和 Android 上的 Chrome，其渲染效果与对应的桌面版不同。应将它们作为矩阵中的独立项。
3. 云平台： BrowserStack、Sauce Labs、LambdaTest，还是仅使用本地引擎？云平台提供带品牌的真实浏览器和 OS；Playwright 附带的引擎涵盖 Chromium、Firefox 和 WebKit（而非 Chrome／Safari 本身）。
4. 渐进增强还是像素级一致？ 渐进增强接受优雅降级。像素级一致则要求渲染结果完全相同。答案决定通过／失败标准。
5. 已有 Playwright 配置？ 如果项目已经使用 Playwright，跨浏览器测试只需更改配置，无需新增工具。

---

核心原则

1. 由分析数据驱动矩阵。 测试用户实际使用的浏览器。流量占比为 0.3% 的浏览器不需要与占比为 40% 的浏览器投入同等资源。每季度检查一次分析数据——浏览器份额会变化。

2. 优先采用渐进增强，而非像素级一致。 不可能也没必要让所有浏览器的渲染结果完全相同。应明确“正常工作”的含义：核心功能可用、内容可访问、布局易用。阴影、渐变或动画时序方面的视觉差异可以接受。

3. Safari 和 Firefox 最容易暴露跨浏览器问题。 仅在 Chrome 中测试只能发现 Chrome 的问题。Safari 的 WebKit 引擎和 Firefox 的 Gecko 引擎与 Chromium 的行为差异最大。应优先测试它们。

4. 测试功能，而非渲染引擎内部细节。 跨浏览器测试应验证用户能否完成任务，而非验证某个 CSS 属性的渲染是否完全一致。像素级差异应交由视觉对比工具处理。

5. 引擎不等于品牌。 Playwright 的 WebKit 不是 Safari，Playwright 的 Chromium 也不是 Chrome——它们共享引擎，但并非用户实际使用的产品（编解码器、字体、企业策略、更新周期均不相同）。除非你在云端网格上运行了真实 Safari，否则应报告“WebKit 覆盖”，而非“Safari 覆盖”。

6. 一个测试，多个浏览器。 测试只编写一次，并在不同浏览器配置下运行。绝不要针对不同浏览器重复编写测试逻辑。

---

浏览器矩阵设计

基于分析数据的方法

Step 1: Export browser/OS data from analytics (last 90 days)
Step 2: Rank by session share
Step 3: Group into tiers
Step 4: Assign test coverage per tier
Step 5: Review quarterly

分层系统

层级	标准	覆盖范围	运行时机
P0	流量占比 >10%	完整测试套件	每次 PR、每次部署
P1	流量占比 3-10%	冒烟测试 + 关键路径	每晚、发布前
P2	流量占比 1-3%	仅冒烟测试	每周、发布前
跳过	流量占比 <1%	不测试	收到报告时手动抽查

示例矩阵（根据分析数据得出）

## Browser Matrix — Q1 2026 (next-review: 2026-04-01)

| Browser | Version | Platform | Traffic % | Tier | Notes |
|---------|---------|----------|-----------|------|-------|
| Chrome | Latest | Windows | 34% | P0 | |
| Chrome | Latest | macOS | 12% | P0 | |
| Safari | Latest | macOS | 11% | P0 | WebKit-specific issues |
| Chrome | Latest | Android | 15% | P0 | Mobile viewport |
| Safari | Latest | iOS | 14% | P0 | Mobile Safari quirks |
| Firefox | Latest | Windows | 5% | P1 | Gecko rendering |
| Edge | Latest | Windows | 4% | P1 | Chromium-based but different UA/policy |
| Samsung Internet | Latest | Android | 3% | P1 | Chromium fork, lagging engine |
| Firefox | Latest | macOS | 1.5% | P2 | |
| Chrome | N-1 | Windows | 1.2% | P2 | Previous major version |

版本覆盖策略

• 最新版本： 始终测试当前稳定版。
• 最新版本 - 1： 仅当分析数据显示旧版本的占比 >1% 时，才测试 P0 浏览器的上一个主要版本。
• 扩展支持版本（ESR）： 仅当企业用户占据重要比例时，才测试 Firefox ESR。
• 不测试： 除非你是浏览器厂商或正在构建面向浏览器的工具，否则不测试 Beta/Canary/Nightly 版本。

---

Playwright 浏览器配置

Playwright 附带三个浏览器引擎——Chromium、Firefox、WebKit，因此基础的引擎级覆盖无需云平台。这是引擎覆盖，而非品牌覆盖：捆绑的 WebKit ≠ Safari，捆绑的 Chromium ≠ Chrome（见核心原则 5）。为矩阵中的每个条目定义一个项目，通过 devices[...] 映射移动设备，并使用 channel 选项驱动本地安装的品牌浏览器。

完整的 playwright.config.ts 项目列表、品牌渠道代码片段和 --project 运行命令，请参阅 references/playwright-and-cloud-config.md。

何时使用渠道： 当你需要与捆绑引擎行为不同的真实品牌浏览器特性时，例如使用已安装的 Chrome（channel: 'chrome'）或 Edge（channel: 'msedge'）来支持扩展、企业策略或编解码器。WebKit 和 Firefox 没有渠道选项；它们始终使用 Playwright 捆绑的引擎。请注意，配置中的 edge 项目和 msedge 渠道代码片段是两种示例方案，并非要合并成两个项目——配置中需要一个 edge 项目，而不是两者都要。

**page.screencast()（Playwright 1.59+，当前版本为 1.60）**可录制带注释的跨浏览器运行视频——当矩阵测试失败、需要人工检查不同引擎的表现时很有用。要通过 Agent 驱动重新运行并逐步排查故障，请使用 --ui（UI 模式）或 --debug（Inspector）；PWDEBUG=1 和 --headed 是另外两个有效入口。不存在 --debug=cli 标志。

---

云平台设置

云平台（BrowserStack、Sauce Labs）提供真实品牌浏览器/OS 实例，Playwright 可通过 CDP/Playwright WebSocket 端点连接到这些实例。通过环境变量传递凭据和功能参数，并确保平台的 playwrightVersion 与 package.json 中的 Playwright 版本一致（当前为 1.60.x——客户端/服务端版本不匹配会导致套接字错误）。

BrowserStack 现在推荐使用 npx browserstack-node-sdk 运行器，并设置 client.playwrightVersion 功能参数（除 browserstack.playwrightVersion 外），以确保客户端和网格套接字版本完全一致。下方的原始 wsEndpoint/CDP 配置仍适用于直接连接；新设置请使用 SDK 方案。

BrowserStack 配置（含 client.playwrightVersion 参数）、Sauce Labs 配置，以及用于并行覆盖云端浏览器的 GitHub Actions 矩阵，请参阅 references/playwright-and-cloud-config.md。

---

常见跨浏览器问题

跨浏览器测试中出现的真实差异，以及相应的检测模式和修复方法。每个问题对应的 CSS 变通方案和 Playwright 测试见 references/common-browser-issues.md，涵盖：iframe 中的分区 Cookie / CHIPS、<input type="date">、Clipboard API、scroll-behavior、backdrop-filter、<dialog> 元素、View Transitions 以及 Web Animations 的计时。

现代跨浏览器注意事项（2026）

经典的 Safari 支持滞后问题大多已解决（flexbox gap、:has() 正式上线、同文档 View Transitions 均已达到 Baseline）。如今真正存在差异的是：

• 分区 Cookie / 分区存储： Chrome 的 CHIPS（Partitioned 属性）、Safari 的 ITP 和 Firefox 的 State Partitioning，对嵌入式第三方上下文的处理各不相同。请在每种浏览器引擎的 iframe 中测试第三方 Cookie，而不要只确认“浏览器支持 Cookie”。可运行的逐引擎 iframe 测试见 references/common-browser-issues.md。
• :has() 选择器性能： 自 2023 年起已得到普遍支持，但大量使用 :has() 的页面在不同引擎中的样式重新计算成本可能大相径庭。注意事项——如果页面在某个引擎中感觉卡顿，请进行性能分析；并在 visual-testing 中进行视觉回归测试。
• View Transitions API： 同文档过渡已达到 Baseline（Chrome 111、Safari 18、Firefox 144——2025 年 10 月），因此不再是差异项。跨文档过渡仍存在差距：Chrome 126+、Safari 18.2+ 支持，Firefox 则需启用标志。应将跨文档过渡视为渐进增强，并验证无过渡时的回退方案。
• WebDriver BiDi： 已可在 Selenium 4 中用于生产环境，在 Playwright 中则仅获部分支持。对于新的跨运行器项目，BiDi 是趋同方向。注意事项。

---

已知问题日志

当确实存在差异且无法立即修复应用时，请将其记录在已提交的文件（docs/browser-issues.md）中，以免之后从头重新排查。下表是 Done When 检查所需的产物，并且每行的测试都必须断言用户体验结果，而不是 CSS 属性：

| Affected browser | Repro | Workaround / fallback / ticket | Test asserts (user outcome, not CSS) |
|------------------|-------|--------------------------------|--------------------------------------|
| Safari (WebKit) ≤17 | scroll-behavior: smooth is partial | rely on anchor nav; no JS scroll dependency | anchor link puts heading in viewport (`toBeInViewport`) |
| Firefox ≤102 | backdrop-filter unsupported | -webkit- prefix + rgba background fallback | overlay readable; modal content visible |
| Firefox (current) | cross-document View Transitions flagged off | progressive enhancement; instant nav fallback | navigation completes; target page heading visible |

每项差异单独占一行。没有工单且没有回退方案的条目属于未解决的 Bug，而不是已记录的问题。

---

测试模式

核心模式及其适用规则如下：

• 同一测试，多种浏览器——默认方式。测试只编写一次；配置项目，让它在所有浏览器中运行。绝不要按浏览器重复测试逻辑。
• 浏览器专属测试逻辑——仅当行为确实不同时，才根据 browserName 分支处理（WebKit 日期输入回退方案和仅限 Chromium 的剪贴板权限就是实际案例）。规则： 尽量少用。浏览器分支过多，通常表明应用存在需要修复的兼容性 Bug，而不是需要绕过的问题。
• 跨浏览器视觉对比——使用带有 maxDiffPixelRatio 容差的 toHaveScreenshot；每个浏览器项目都会生成自己的基准图（homepage-chromium.png、homepage-webkit.png，……）。有关阈值策略和基准图管理，请参阅 visual-testing。
• 渐进增强验证——中止脚本请求（仅限 Chromium），并验证核心功能仍可通过原生 HTML 正常使用。

四种模式的可运行代码见 references/testing-patterns.md。

反模式

只在 Chrome 上测试。 Chrome 的桌面市场份额最大，但它使用的引擎与 Edge、Opera 和 Brave 相同。Safari（WebKit）和 Firefox（Gecko）才会暴露真正的跨浏览器问题。只在 Chrome 上测试会让人产生虚假的信心。

把 WebKit/Chromium 测试结果报告为 Safari/Chrome。 内置引擎共享的是渲染能力，并非实际发布的浏览器。仅凭 WebKit 项目就声称「覆盖 Safari」，会掩盖只有在真实 Safari 中才会出现的编解码器、字体和策略问题。

对所有浏览器投入同等测试力度。 流量占比为 1% 的浏览器不需要和占比为 30% 的浏览器投入同等资源。使用分级系统按比例分配精力。

为每种浏览器重复编写测试。 只编写一次测试，通过配置在不同浏览器项目中运行。用相同逻辑编写 checkout.chrome.spec.ts 和 checkout.safari.spec.ts 并不是正确做法。

到处检查 browserName。 在测试中过度分支处理浏览器，说明应用存在兼容性问题。应修复应用，而不是在测试中绕过问题。

使用没有容差的像素级断言。 不同浏览器和平台的字体渲染、抗锯齿和亚像素舍入各不相同。在视觉对比中使用 maxDiffPixelRatio 或 maxDiffPixels。

忽略移动浏览器。 移动版 Chrome 和移动版 Safari 并非桌面版浏览器的简单延伸，它们的视口行为、触控处理和 CSS 支持各不相同。应将它们作为矩阵中的独立条目进行测试。

浏览器矩阵一成不变。 浏览器使用情况会发生变化。基于两年前数据制定的矩阵已经不准确。每季度查看一次分析数据并更新 next-review 日期。

记录差异，却没有回退方案或工单。 已知问题表中既没有解决方法，也没有待处理工单，这种把未记录的 Bug 假装成已记录问题的做法不可取。

---

故障模式

症状	可能原因	修复或检查
云端测试因套接字/握手错误而失败	Grid Playwright 版本 ≠ 本地版本	设置 playwrightVersion/client.playwrightVersion，使其与 npx playwright --version 一致；使用 browserstack-node-sdk 运行器
剪贴板测试在 Chromium 中通过，在 Firefox/WebKit 中失败	grantPermissions 仅适用于 Chromium	断言 UI 反馈（Copied!），而非剪贴板 API；仅在 browserName === 'chromium' 时使用 grantPermissions
渐进增强测试在 Firefox/WebKit 中出错	中止脚本的路由拦截仅适用于 Chromium	仅在 browserName === 'chromium' 时启用该路由；在其他浏览器中跳过禁用 JS 的断言
WebKit 项目「通过」，但 Safari 的真实用户报告故障	WebKit 引擎 ≠ 实际发布的 Safari	在云端网格中为受影响的流程添加一行真实 Safari 测试
只有一种浏览器的视觉基线差异大幅增加	所有浏览器共用同一基线	按项目生成基线；每种浏览器各自使用 *-<project>.png
某一种引擎中的 :has() 密集页面出现卡顿	不同引擎的样式重新计算开销不同	在该引擎中分析性能；缩小 :has() 的作用范围；使用 visual-testing 进行视觉回归测试

---

完成标准

• 使用真实分析数据（最近 90 天）定义浏览器矩阵，记录并说明 P0/P1/P2 分级的流量占比依据，并将矩阵提交到包含带日期 next-review 字段的文件中。
• Playwright 项目配置（或 BrowserStack/Sauce Labs 配置）反映该矩阵，并在每个 PR 上运行 P0 浏览器；云端配置中的 playwrightVersion 与 package.json 保持一致。
• 存在 docs/browser-issues.md，其中每个已知差异占一行，列出受影响的浏览器、复现步骤、解决方法/回退方案或关联工单，以及断言用户体验结果（而非 CSS）的测试。
• 常见差异检查清单（分区 Cookie、日期输入框、剪贴板、滚动行为、backdrop-filter、<dialog>、View Transitions）中，与 P0/P1 浏览器相关的每一项都应有测试或已知问题记录。
• 存在用于跟踪下一次季度矩阵审查的工单（或者矩阵文件中的 next-review 日期晚于当前日期），以免遗漏更新。

相关技能

• visual-testing — 负责像素级基线策略、阈值表和 toHaveScreenshot 配置。需要了解截图差异应有多宽容时，请查阅此技能；此技能仅决定哪些浏览器需要基线。
• playwright-automation — Playwright 核心模式、fixtures 和 CI 配置，是跨浏览器测试的基础。
• ci-cd-integration — 并行浏览器矩阵执行和制品收集的流水线配置。
• mobile-testing — 设备云和原生／混合应用测试（Appium/Detox）；当目标是应用而非浏览器视口时，请查阅此技能。
• accessibility-testing — 跨浏览器的无障碍差异（屏幕阅读器行为、ARIA 支持），与此矩阵有交集。

参考文件（位于 references/ 中）

• playwright-and-cloud-config.md — playwright.config.ts 项目列表、品牌渠道、--project 运行命令，以及 BrowserStack（SDK + client.playwrightVersion）/Sauce Labs/CI 矩阵配置。
• common-browser-issues.md — 按引擎划分的分区 Cookie iframe 测试、日期输入框的 WebKit 回退方案、剪贴板、滚动行为、backdrop-filter、<dialog>、视图过渡和 Web Animations。
• testing-patterns.md — 同一测试在多个浏览器中运行、browserName 分支、视觉对比和渐进增强代码。