Back to Details

cross-browser-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Chrome-only testing gives false confidence: a layout that works in Chromium can break in WebKit, a clipboard call that succeeds in Chrome silently no-ops in Firefox, and a partitioned-cookie flow can pass everywhere except the one engine your users are on. This skill produces an analytics-driven browser matrix, a Playwright (or cloud-platform) config that runs it, and a committed log of known browser divergences — each verified by a test that asserts the user outcome, not the CSS. </objective>
<objective> 仅在Chrome中测试会带来错误的信心：在Chromium中正常的布局可能在WebKit中崩溃，在Chrome中成功的剪贴板调用在Firefox中会静默无操作，而分区Cookie流程可能在除用户使用的那个引擎之外的所有环境中都能通过。本技能会生成基于数据分析的浏览器矩阵、运行该矩阵的Playwright（或云平台）配置，以及一份已确认的已知浏览器差异日志——每个差异都由验证用户结果而非CSS的测试所确认。 </objective>

Quick Route

快速指南

SituationGo to
Need to decide which browsers to testBrowser Matrix Design
Already on Playwright, just add browsersPlaywright Browser Configuration → 
references/playwright-and-cloud-config.md
Need real Safari/Windows/older OS, not enginesCloud Platform Setup
One browser misbehaves; want a test for itCommon Cross-Browser Issues + 
browserName
branch in 
references/testing-patterns.md
Need to record a divergence so it is not re-debuggedKnown-Issues Log
Pixel diffs / baseline thresholdsuse 
visual-testing
场景前往查看
需要确定要测试哪些浏览器浏览器矩阵设计
已使用Playwright，只需添加浏览器Playwright浏览器配置 → 
references/playwright-and-cloud-config.md
需要真实的Safari/Windows/旧版操作系统，而非引擎云平台设置
某一浏览器行为异常，需要针对其编写测试常见跨浏览器问题 + 
references/testing-patterns.md
中的
browserName
分支
需要记录差异以避免重复调试已知问题日志
像素差异/基线阈值使用
visual-testing

Discovery Questions

探索问题

Check 
.agents/qa-project-context.md
first — if it exists, use it and skip anything already answered there. Then:
  1. Target browsers from analytics: What do actual users use? Pull browser/OS data from your analytics tool. Testing browsers nobody uses is waste; missing a browser 15% of users rely on is a bug.
  2. Desktop and mobile? Mobile Safari on iOS and Chrome on Android render differently than their desktop counterparts. Treat them as separate matrix entries.
  3. Cloud platform: BrowserStack, Sauce Labs, LambdaTest, or local engines only? Cloud platforms provide real branded browsers and OSes; Playwright's bundled engines cover Chromium, Firefox, and WebKit (not Chrome/Safari themselves).
  4. Progressive enhancement or pixel-perfect? Progressive enhancement accepts graceful degradation. Pixel-perfect demands identical rendering. The answer determines pass/fail criteria.
  5. Existing Playwright config? If the project already uses Playwright, cross-browser testing is a configuration change, not a new tool.
首先查看
.agents/qa-project-context.md
——如果存在，请使用该文件并跳过已回答的问题。然后：
  1. 来自数据分析的目标浏览器： 实际用户使用哪些浏览器？从分析工具中提取浏览器/操作系统数据。测试无人使用的浏览器是浪费；遗漏占15%用户的浏览器则是漏洞。
  2. 是否包含桌面端和移动端？ iOS上的Mobile Safari和Android上的Chrome与对应的桌面端渲染效果不同。将它们视为矩阵中的独立条目。
  3. 云平台： BrowserStack、Sauce Labs、LambdaTest，还是仅使用本地引擎？云平台提供真实的品牌浏览器和操作系统；Playwright的捆绑引擎覆盖Chromium、Firefox和WebKit（但并非Chrome/Safari本身）。
  4. 渐进式增强还是像素级完美？ 渐进式增强接受优雅降级。像素级完美要求渲染完全一致。答案将决定通过/失败的标准。
  5. 是否已有Playwright配置？ 如果项目已使用Playwright，跨浏览器测试只是配置变更，无需引入新工具。

Core Principles

核心原则

  1. Analytics-driven matrix. Test what your users actually use. A browser at 0.3% traffic does not need the same investment as one at 40%. Check analytics quarterly — browser share shifts.
  2. Progressive enhancement over pixel-perfect. Identical rendering across all browsers is neither achievable nor necessary. Define what "works" means: core functionality operates, content is accessible, layout is usable. Visual differences in shadows, gradients, or animation timing are acceptable.
  3. Safari and Firefox surface the most cross-browser bugs. Chrome-only testing catches Chrome bugs. Safari's WebKit engine and Firefox's Gecko engine have the most behavioral differences from Chromium. Prioritize them.
  4. Test functionality, not rendering-engine internals. A cross-browser test should verify that the user can complete a task, not that a CSS property renders identically. Visual comparison tools handle pixel-level differences.
  5. Engines are not brands. Playwright's WebKit is not Safari and its Chromium is not Chrome — they share an engine, not the shipped product (codecs, fonts, enterprise policy, update cadence all differ). Report "WebKit coverage," not "Safari coverage," unless you ran real Safari on a cloud grid.
  6. One test, multiple browsers. Write tests once. Run them across browser configurations. Never duplicate test logic for different browsers.
  1. 基于数据分析的矩阵。 测试用户实际使用的浏览器。流量占比0.3%的浏览器无需投入与占比40%的浏览器相同的资源。每季度检查一次分析数据——浏览器份额会变化。
  2. 优先渐进式增强而非像素级完美。 在所有浏览器中实现完全一致的渲染既不可能也不必要。定义“正常工作”的含义：核心功能可运行、内容可访问、布局可用。阴影、渐变或动画时长等视觉差异是可接受的。
  3. Safari和Firefox最容易暴露跨浏览器漏洞。 仅在Chrome中测试只能发现Chrome的漏洞。Safari的WebKit引擎和Firefox的Gecko引擎与Chromium的行为差异最大。优先测试它们。
  4. 测试功能，而非渲染引擎内部机制。 跨浏览器测试应验证用户能否完成任务，而非CSS属性是否渲染一致。视觉对比工具负责处理像素级差异。
  5. 引擎不等于品牌。 Playwright的WebKit并非Safari，其Chromium也并非Chrome——它们共享引擎，但不是已发布的产品（编解码器、字体、企业策略、更新节奏均不同）。除非你在云网格上运行了真实的Safari，否则请报告“WebKit覆盖范围”，而非“Safari覆盖范围”。
  6. 一次编写，多浏览器运行。 编写一次测试，在不同浏览器配置中运行。绝不为不同浏览器重复测试逻辑。

Browser Matrix Design

浏览器矩阵设计

Analytics-Based Methodology

基于数据分析的方法

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
Step 1: 从分析工具导出浏览器/操作系统数据（最近90天）
Step 2: 按会话占比排序
Step 3: 分组为不同层级
Step 4: 为每个层级分配测试覆盖范围
Step 5: 每季度复查

Tier System

层级体系

TierCriteriaCoverageWhen to run
P0>10% traffic shareFull test suiteEvery PR, every deploy
P13-10% traffic shareSmoke + critical pathsNightly, pre-release
P21-3% traffic shareSmoke tests onlyWeekly, pre-release
Skip<1% traffic shareNot testedManual spot-check if reported
层级标准覆盖范围运行时机
P0流量占比>10%完整测试套件每个PR、每次部署
P1流量占比3-10%冒烟测试+关键路径夜间、预发布
P2流量占比1-3%仅冒烟测试每周、预发布
跳过流量占比<1%不测试如有反馈则手动抽查

Example Matrix (derived from analytics)

示例矩阵（基于数据分析）

markdown
undefined
markdown
undefined

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

浏览器矩阵 — 2026年第一季度（下次复查：2026-04-01）

BrowserVersionPlatformTraffic %TierNotes
ChromeLatestWindows34%P0
ChromeLatestmacOS12%P0
SafariLatestmacOS11%P0WebKit-specific issues
ChromeLatestAndroid15%P0Mobile viewport
SafariLatestiOS14%P0Mobile Safari quirks
FirefoxLatestWindows5%P1Gecko rendering
EdgeLatestWindows4%P1Chromium-based but different UA/policy
Samsung InternetLatestAndroid3%P1Chromium fork, lagging engine
FirefoxLatestmacOS1.5%P2
ChromeN-1Windows1.2%P2Previous major version
undefined
BrowserVersionPlatformTraffic %TierNotes
ChromeLatestWindows34%P0
ChromeLatestmacOS12%P0
SafariLatestmacOS11%P0WebKit-specific issues
ChromeLatestAndroid15%P0Mobile viewport
SafariLatestiOS14%P0Mobile Safari quirks
FirefoxLatestWindows5%P1Gecko rendering
EdgeLatestWindows4%P1Chromium-based but different UA/policy
Samsung InternetLatestAndroid3%P1Chromium fork, lagging engine
FirefoxLatestmacOS1.5%P2
ChromeN-1Windows1.2%P2Previous major version
undefined

Version Coverage Strategy

版本覆盖策略

  • Latest: Always test current stable release.
  • Latest - 1: Test previous major version only for P0 browsers where analytics show >1% on older versions.
  • Extended Support Release (ESR): Test Firefox ESR only if enterprise users are a significant segment.
  • Do not test: Beta/Canary/Nightly releases unless you are a browser vendor or building browser-facing tools.
  • Latest： 始终测试当前稳定版本。
  • Latest - 1： 仅当分析数据显示P0浏览器的旧版本占比>1%时，才测试前一个主要版本。
  • Extended Support Release (ESR)： 仅当企业用户是重要群体时，才测试Firefox ESR。
  • 不测试： Beta/Canary/Nightly版本，除非你是浏览器厂商或开发面向浏览器的工具。

Playwright Browser Configuration

Playwright浏览器配置

Playwright ships three browser engines — Chromium, Firefox, WebKit — so no cloud platform is needed for basic engine-level coverage. This is engine coverage, not brand coverage: bundled WebKit ≠ Safari and bundled Chromium ≠ Chrome (see Core Principle 5). Define one project per matrix entry, map mobile devices via 
devices[...]
, and drive locally installed branded browsers with the 
channel
option.
See 
references/playwright-and-cloud-config.md
for the full 
playwright.config.ts
project list, branded-channel snippets, and 
--project
run commands.
When to use channels: When you need real branded behavior that differs from the bundled engine — installed Chrome (
channel: 'chrome'
) or Edge (
channel: 'msedge'
) for extension support, enterprise policy, or codecs. WebKit and Firefox have no channel option; they are always Playwright's bundled engines. Note the 
edge
project in the config and the 
msedge
channel snippet are illustrative alternatives, not two projects to merge — a config needs one 
edge
project, not both.
page.screencast()
(Playwright 1.59+, current in 1.60) captures annotated video of a cross-browser run — useful when a matrix failure needs human review across engines. For agent-driven re-runs and stepping through a failure, use 
--ui
(UI mode) or 
--debug
(Inspector); 
PWDEBUG=1
and 
--headed
are the other real entry points. There is no 
--debug=cli
flag.
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
（检查器）；
PWDEBUG=1
和
--headed
是其他常用入口点。不存在
--debug=cli
标志。

Cloud Platform Setup

云平台设置

Cloud platforms (BrowserStack, Sauce Labs) provide real branded-browser/OS instances Playwright connects to over a CDP/Playwright WebSocket endpoint. Pass credentials and capabilities via environment variables, and keep the platform's 
playwrightVersion
aligned with the Playwright version in 
package.json
(currently 1.60.x — a client/server mismatch causes socket errors).
BrowserStack now recommends the 
npx browserstack-node-sdk
runner plus a 
client.playwrightVersion
capability (in addition to 
browserstack.playwrightVersion
) to keep the client and grid sockets in lock-step. The raw 
wsEndpoint
/CDP config below still works for direct connections; use the SDK path for new setups.
See 
references/playwright-and-cloud-config.md
for the BrowserStack config (with the 
client.playwrightVersion
cap), the Sauce Labs config, and the GitHub Actions parallel matrix that fans out across cloud browsers.
云平台（BrowserStack、Sauce Labs）提供真实的品牌浏览器/操作系统实例，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
。

Common Cross-Browser Issues

常见跨浏览器问题

Real divergences that surface in cross-browser testing, with detection patterns and fixes. The CSS workarounds and Playwright tests for each are in 
references/common-browser-issues.md
, covering: partitioned cookies / CHIPS in iframes, 
<input type="date">
, the Clipboard API, 
scroll-behavior
, 
backdrop-filter
, the 
<dialog>
element, View Transitions, and Web Animations timing.
跨浏览器测试中出现的真实差异，包含检测模式和修复方案。每个问题的CSS解决方法和Playwright测试请查看
references/common-browser-issues.md
，涵盖：iframe中的分区Cookie/CHIPS、
<input type="date">
、剪贴板API、
scroll-behavior
、
backdrop-filter
、
<dialog>
元素、视图过渡和Web动画时长。

Modern Cross-Browser Gotchas (2026)

2026年现代跨浏览器陷阱

The classic Safari-laggard list is mostly resolved (flexbox 
gap
, 
:has()
shipping, same-document View Transitions are all Baseline). Today's real divergences:
  • Partitioned cookies / partitioned storage: Chrome's CHIPS (
    Partitioned
    attribute), Safari's ITP, and Firefox's State Partitioning each behave differently for embedded third-party contexts. Test third-party cookies in an iframe per engine, not just "the browser supports cookies." See the runnable per-engine iframe test in 
    references/common-browser-issues.md
    .
  • :has()
    selector performance:     Universally supported since 2023, but a 
    :has()
    -heavy page can have very different style-recalc cost across engines. Watch list — profile if a page feels janky in one engine; visual-regression it in 
    visual-testing
    .
  • View Transitions API: Same-document transitions are Baseline (Chrome 111, Safari 18, Firefox 144 — Oct 2025), so they are no longer a divergence. Cross-document transitions are still the gap: Chrome 126+, Safari 18.2+, Firefox behind a flag. Treat cross-document as progressive enhancement and verify the no-transition fallback.
  • WebDriver BiDi: Production-ready in Selenium 4, partially supported in Playwright. For new cross-runner projects, BiDi is the convergence point. Watch list.
经典的Safari滞后问题大多已解决（flexbox 
gap
、
:has()
已发布、同文档视图过渡均已成为基线功能）。当前的真实差异包括：
  • 分区Cookie/分区存储： Chrome的CHIPS（
    Partitioned
    属性）、Safari的ITP和Firefox的状态分区在嵌入式第三方上下文中的行为各不相同。需在每个引擎的iframe中测试第三方Cookie，而非仅测试“浏览器支持Cookie”。请查看
    references/common-browser-issues.md
    中的可运行的逐引擎iframe测试。
  • :has()
    选择器性能：     自2023年起已全面支持，但大量使用
    :has()
    的页面在不同引擎中的样式重计算成本可能差异很大。需重点关注——如果某页面在某一引擎中卡顿，请进行性能分析；在
    visual-testing
    中进行视觉回归测试。
  • 视图过渡API： 同文档过渡已成为基线功能（Chrome 111、Safari 18、Firefox 144——2025年10月），因此不再是差异点。跨文档过渡仍存在差距：Chrome 126+、Safari 18.2+、Firefox需开启标志。将跨文档过渡视为渐进式增强，并验证无过渡的回退方案。
  • WebDriver BiDi： 在Selenium 4中已投入生产，在Playwright中部分支持。对于新的跨运行器项目，BiDi是融合点。需重点关注。

Known-Issues Log

已知问题日志

When a divergence is real and you cannot fix the app immediately, record it in a committed file (
docs/browser-issues.md
) so it is not re-debugged from scratch. The table is the artifact 
Done When
checks for, and every row's test must assert the user outcome, not the CSS property:
markdown
| 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 |
Keep one row per divergence. A row with no ticket and no fallback is an open bug, not a documented issue.
当差异真实存在且无法立即修复应用时，请将其记录在已提交的文件（
docs/browser-issues.md
）中，避免从头开始重复调试。表格是“完成标准”检查的工件，每一行的测试必须断言用户结果，而非CSS属性：
markdown
| 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 |
每个差异对应一行。没有工单也没有回退方案的行是未解决的漏洞，而非已记录的问题。

Testing Patterns

测试模式

The core patterns and the rules that govern them:
  • Same test, multiple browsers — the default. Write the test once; configure projects to run it everywhere. Never duplicate test logic per browser.
  • Browser-specific test logic — branch on 
    browserName
    only when behavior genuinely differs (the WebKit date-input fallback and Chromium-only clipboard permission are real cases). Rule: keep this rare. Many browser branches signal application compatibility bugs to fix, not work around.
  • Visual cross-browser comparison — 
    toHaveScreenshot
    with a 
    maxDiffPixelRatio
    tolerance; each browser project generates its own baseline (
    homepage-chromium.png
    , 
    homepage-webkit.png
    , …). For threshold strategy and baseline management, use 
    visual-testing
    .
  • Progressive enhancement validation — abort script requests (Chromium only) and verify core functionality still works via native HTML.
See 
references/testing-patterns.md
for the runnable code for all four patterns.
核心模式及其规则：
  • 一次编写，多浏览器运行——默认方式。编写一次测试；配置项目使其在所有环境中运行。绝不为不同浏览器重复测试逻辑。
  • 浏览器特定测试逻辑——仅当行为确实不同时，才基于
    browserName
    分支（WebKit日期输入回退和仅Chromium的剪贴板权限是真实案例）。规则： 尽量少用这种方式。大量浏览器分支表明应用存在兼容性漏洞，需要修复而非规避。
  • 视觉跨浏览器对比——使用
    toHaveScreenshot
    并设置
    maxDiffPixelRatio
    容差；每个浏览器项目生成自己的基线（
    homepage-chromium.png
    、
    homepage-webkit.png
    等）。如需阈值策略和基线管理，请使用
    visual-testing
    。
  • 渐进式增强验证——中止脚本请求（仅Chromium支持），并验证核心功能仍可通过原生HTML正常工作。
所有四种模式的可运行代码，请查看
references/testing-patterns.md
。

Anti-Patterns

反模式

Testing only on Chrome. Chrome is the largest desktop share but uses the same engine as Edge, Opera, and Brave. Safari (WebKit) and Firefox (Gecko) surface the real cross-browser issues. Chrome-only testing gives false confidence.
Reporting WebKit/Chromium as Safari/Chrome. Bundled engines share rendering, not the shipped browser. Claiming "Safari coverage" off a WebKit project hides codec, font, and policy bugs that only real Safari shows.
Testing every browser equally. A browser at 1% traffic share does not need the same investment as one at 30%. Use the tier system to allocate effort proportionally.
Duplicating tests per browser. Write tests once, run them across browser projects via configuration. A 
checkout.chrome.spec.ts
and 
checkout.safari.spec.ts
with identical logic is the wrong shape.
browserName
checks everywhere. Excessive browser branching in tests signals application compatibility issues. Fix the app, do not work around it in tests.
Pixel-perfect assertions without tolerance. Font rendering, anti-aliasing, and sub-pixel rounding differ between browsers and platforms. Use 
maxDiffPixelRatio
or 
maxDiffPixels
in visual comparisons.
Ignoring mobile browsers. Mobile Chrome and mobile Safari are not their desktop counterparts — different viewport behavior, touch handling, and CSS support. Test them as separate matrix entries.
Static browser matrix. Browser usage changes. A matrix based on data from two years ago is wrong. Review analytics quarterly and update the 
next-review
date.
Documenting a divergence with no fallback or ticket. A known-issues row that lists no workaround and no open ticket is an undocumented bug pretending to be documented.
仅在Chrome中测试。 Chrome是桌面端份额最大的浏览器，但与Edge、Opera和Brave使用相同引擎。Safari（WebKit）和Firefox（Gecko）才会暴露真实的跨浏览器问题。仅在Chrome中测试会带来错误的信心。
将WebKit/Chromium报告为Safari/Chrome。 捆绑引擎共享渲染机制，但并非已发布的浏览器。声称“Safari覆盖范围”却基于WebKit项目，会隐藏只有真实Safari才会出现的编解码器、字体和策略漏洞。
平等测试所有浏览器。 流量占比1%的浏览器无需投入与占比30%的浏览器相同的资源。使用层级体系按比例分配精力。
为每个浏览器重复编写测试。 编写一次测试，通过配置在不同浏览器项目中运行。
checkout.chrome.spec.ts
和
checkout.safari.spec.ts
包含相同逻辑是错误的做法。
到处使用
browserName
检查。 测试中过多的浏览器分支表明应用存在兼容性问题。修复应用，而非在测试中规避。
无容差的像素级完美断言。 字体渲染、抗锯齿和亚像素舍入在不同浏览器和平台之间存在差异。在视觉对比中使用
maxDiffPixelRatio
或
maxDiffPixels
。
忽略移动浏览器。 Mobile Chrome和Mobile Safari并非对应的桌面端版本——视口行为、触摸处理和CSS支持均不同。将它们作为矩阵中的独立条目进行测试。
静态浏览器矩阵。 浏览器使用情况会变化。基于两年前数据的矩阵是错误的。每季度复查分析数据并更新
next-review
日期。
记录无回退方案或工单的差异。 已知问题行中未列出解决方法和未关闭工单，是伪装成已记录问题的未记录漏洞。

Failure Modes

故障模式

SymptomLikely causeFix or check
Cloud tests fail with a socket/handshake errorGrid Playwright version ≠ localSet 
playwrightVersion
/
client.playwrightVersion
to match 
npx playwright --version
; use the 
browserstack-node-sdk
runner
Clipboard test passes in Chromium, fails in Firefox/WebKit
grantPermissions
only works in Chromium		Assert UI feedback (
Copied!
), not the clipboard API; gate 
grantPermissions
on 
browserName === 'chromium'
Progressive-enhancement test errors in Firefox/WebKitScript-abort route interception is Chromium-onlyGate the route on 
browserName === 'chromium'
; skip the JS-disabled assertion elsewhere
WebKit project "passes" but real users on Safari report breakageWebKit engine ≠ shipped SafariAdd a real-Safari row on a cloud grid for the affected flow
Visual baseline diff explodes for one browser onlySingle baseline shared across browsersGenerate per-project baselines; each browser keeps its own 
*-<project>.png
:has()
-heavy page janky in one engine only		Style-recalc cost differs by engineProfile in that engine; reduce 
:has()
scope; visual-regress in 
visual-testing
症状可能原因修复或检查方法
云测试因套接字/握手错误失败网格Playwright版本≠本地版本将
playwrightVersion
/
client.playwrightVersion
设置为与
npx playwright --version
匹配；使用
browserstack-node-sdk
运行器
剪贴板测试在Chromium中通过，在Firefox/WebKit中失败
grantPermissions
仅在Chromium中有效		断言UI反馈（如「已复制！」），而非剪贴板API；仅在
browserName === 'chromium'
时使用
grantPermissions
渐进式增强测试在Firefox/WebKit中出错中止脚本请求的路由拦截仅在Chromium中支持仅在
browserName === 'chromium'
时启用该路由；在其他环境中跳过JS禁用断言
WebKit项目「通过」但真实Safari用户报告崩溃WebKit引擎≠已发布的Safari在云网格中为受影响的流程添加真实Safari条目
某一浏览器的视觉基线差异大幅增加所有浏览器共享单一基线生成每个项目的基线；每个浏览器保留自己的
*-<project>.png
大量使用
:has()
的页面在某一引擎中卡顿		样式重计算成本因引擎而异在该引擎中进行性能分析；缩小
:has()
的使用范围；在
visual-testing
中进行视觉回归测试

Done When

完成标准

  • Browser matrix defined using real analytics data (last 90 days), with tier assignments (P0/P1/P2) documented and justified by traffic share, committed to a file carrying a dated 
    next-review
    field.
  • Playwright project config (or BrowserStack/Sauce Labs config) reflects the matrix and runs P0 browsers on every PR; cloud configs pin 
    playwrightVersion
    to match 
    package.json
    .
  • docs/browser-issues.md
    exists with one row per known divergence: affected browser, repro, workaround/fallback or linked ticket, and the test that asserts the user outcome (not the CSS).
  • Common-divergence checklist (partitioned cookies, date inputs, clipboard, scroll behavior, backdrop-filter, 
    <dialog>
    , View Transitions) has a test or a known-issues row for each item relevant to P0/P1 browsers.
  • A tracked issue exists for the next quarterly matrix review (or the matrix file's 
    next-review
    date is in the future), so the refresh is not lost.
  • 使用真实分析数据（最近90天）定义浏览器矩阵，记录层级分配（P0/P1/P2）并通过流量占比证明其合理性，提交至包含
    next-review
    日期字段的文件。
  • Playwright项目配置（或BrowserStack/Sauce Labs配置）与矩阵一致，且P0浏览器在每个PR中运行；云配置固定
    playwrightVersion
    以匹配
    package.json
    。
  • docs/browser-issues.md
    存在，每个已知差异对应一行：受影响的浏览器、复现步骤、解决方法/回退方案或链接工单，以及断言用户结果（而非CSS）的测试。
  • 常见差异检查表（分区Cookie、日期输入、剪贴板、滚动行为、
    backdrop-filter
    、
    <dialog>
    、视图过渡）针对P0/P1浏览器的相关条目均有测试或已知问题行。
  • 存在跟踪问题以安排下一次季度矩阵复查（或矩阵文件的
    next-review
    日期在未来），确保不会遗漏更新。

Related Skills

相关技能

  • visual-testing — Owns pixel-level baseline strategy, threshold tables, and 
    toHaveScreenshot
    config. Go there for how tolerant a screenshot diff should be; this skill only decides which browsers get a baseline.
  • playwright-automation — Core Playwright patterns, fixtures, and CI configuration that cross-browser testing builds on.
  • ci-cd-integration — Pipeline configuration for parallel browser-matrix execution and artifact collection.
  • mobile-testing — Device-farm and native/hybrid app testing (Appium/Detox); go there when the target is an app, not a browser viewport.
  • accessibility-testing — Cross-browser accessibility differences (screen-reader behavior, ARIA support) that overlap with this matrix.
  • visual-testing — 负责像素级基线策略、阈值表和
    toHaveScreenshot
    配置。如需了解截图差异的容差标准，请前往该技能；本技能仅决定哪些浏览器需要基线。
  • playwright-automation — 跨浏览器测试所基于的核心Playwright模式、夹具和CI配置。
  • ci-cd-integration — 用于并行执行浏览器矩阵和收集工件的流水线配置。
  • mobile-testing — 设备农场和原生/混合应用测试（Appium/Detox）；当测试目标是应用而非浏览器视口时，请使用该技能。
  • accessibility-testing — 与本矩阵重叠的跨浏览器可访问性差异（屏幕阅读器行为、ARIA支持）。

Reference Files (in 
references/
)

参考文件（位于
references/
）

  • playwright-and-cloud-config.md — 
    playwright.config.ts
    project list, branded channels, 
    --project
    run commands, and BrowserStack (SDK + 
    client.playwrightVersion
    )/Sauce Labs/CI matrix configs.
  • common-browser-issues.md — Per-engine partitioned-cookie iframe test, date-input WebKit fallback, clipboard, scroll behavior, backdrop-filter, 
    <dialog>
    , View Transitions, and Web Animations.
  • testing-patterns.md — Same-test-multiple-browsers, 
    browserName
    branching, visual comparison, and progressive-enhancement code.
  • 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动画。
  • testing-patterns.md — 一次编写多浏览器运行、
    browserName
    分支、视觉对比和渐进式增强代码。