Front-End-Checklist 跨浏览器测试实战用 Playwright 矩阵覆盖 Chrome、Firefox、Safari 与 Edge【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist用户从不同浏览器访问同一网站而每个浏览器背后是各不相同的渲染引擎。本文基于 Front-End-Checklist 仓库中的跨浏览器测试规则文档 references/rule.md系统讲解如何用 Playwright 搭建覆盖桌面与移动端的浏览器矩阵、编写跨浏览器测试与视觉回归用例、将测试接入 CI/CD并用特性检测与 Polyfill 策略优雅降级同时结合仓库中真实落地的 Playwright 配置、E2E 测试框架与 CI 脚本展示这套规则在工程中的具体实现形态。规则定位为什么跨浏览器测试是“高优先级”仓库将本规则归类在 testing 类别下元数据标注为Priority: high · Difficulty: intermediate · Time: 60 min见 SKILL.md 头部 frontmatter规则来源为 frontendchecklist.io 的 testing/cross-browser-testing 条目。其核心论断是用户从不同浏览器访问你的网站每个浏览器都有独特的渲染引擎。不做跨浏览器测试相当比例的用户可能遇到破损的布局、缺失的功能甚至完全失败。该规则要求站点至少在Chrome、Firefox、Safari、Edge四个浏览器上验证正确性Quick Reference 给出的操作要点是至少覆盖 Chrome、Firefox、Safari、EdgeCI 中用 Playwright 或 BrowserStack 等自动化工具执行使用 CSS 新特性前先用 caniuse 之类的特性查询工具确认支持度桌面与移动端浏览器版本都要测对不支持的特性要记录并优雅降级。目标浏览器矩阵规则文档给出的目标浏览器与优先级如下浏览器引擎优先级备注ChromeBlinkCritical约 65% 市场份额SafariWebKitCriticaliOS/macOS 默认FirefoxGeckoHigh隐私导向用户群EdgeBlinkHighWindows 默认Samsung InternetBlinkMedium三星设备流行注意一个事实边界表中市场份额数字是规则文档给出的静态标注具体占比会随时间变化落地时应以当前时点的数据为准。仓库的真实 Playwright 配置从规则示例到落地实现规则文档给出的参考配置是 6 个 project 的完整矩阵桌面 chromium/firefox/webkit/edge 移动端 Pixel 5/iPhone 12其中 Edge 通过channel: msedge指向品牌版浏览器// playwright.config.ts testDir: ./e2e, fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: html, projects: [ // 桌面浏览器 { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } }, { name: edge, use: { ...devices[Desktop Edge], channel: msedge } }, // 移动浏览器 { name: mobile-chrome, use: { ...devices[Pixel 5] } }, { name: mobile-safari, use: { ...devices[iPhone 12] } }, ], webServer: { command: pnpm dev, port: 3000, reuseExistingServer: !process.env.CI, }, })仓库里实际存在两份 Playwright 配置可以对照理解这套示例如何被“裁剪落地”。apps/e2e独立 E2E 应用的配置apps/e2e/playwright.config.ts 与规则示例高度一致但做了若干工程化调整import { defineConfig, devices } from playwright/test const PORT process.env.PORT || 3080 export default defineConfig({ testDir: ./e2e, testMatch: **/*.spec.ts, fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: process.env.CI ? github : html, use: { baseURL: http://localhost:${PORT}, trace: on-first-retry, screenshot: only-on-failure, video: retain-on-failure }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } }, { name: Mobile Chrome, use: { ...devices[Pixel 5] } }, { name: Mobile Safari, use: { ...devices[iPhone 12] } } // Microsoft Edge 等品牌浏览器以注释形式保留按需开启 ], webServer: { command: pnpm dev, url: http://localhost:${PORT}, reuseExistingServer: !process.env.CI, stdout: ignore, stderr: pipe } })从源码结构看有几处值得注意的取舍Edge 项目被注释掉。devices[Desktop Edge]channel: msedge需要本地安装品牌版 Edge 浏览器在 Linux CI 上未必可用因此仓库默认启用三个引擎Blink/Gecko/WebKit 两个移动 viewport品牌浏览器以注释形式留作开关——这正体现了规则“Support Notes”里的提醒CI 环境的浏览器自动化能力会因平台而异需要记录不可用能力下的降级方案。失败取证三件套trace: on-first-retry、screenshot: only-on-failure、video: retain-on-failure只在重试或失败时产生工件避免报告体积膨胀。reporter 按环境切换CI 用github结果写入 PR本地用html与规则文档中 CI/CD 一节的意图一致。webServer 绑定 3080 端口并通过reuseExistingServer: !process.env.CI保证 CI 中永远起全新 dev server避免复用残留进程造成的假绿/假红。apps/web主站自身的精简矩阵apps/web/playwright.config.ts 则进一步收敛为三个桌面项目并用构建产物而非 dev server 作为被测对象const baseURL process.env.BASE_URL || http://127.0.0.1:3080 export default defineConfig({ testDir: ./e2e, fullyParallel: true, retries: process.env.CI ? 2 : 0, reporter: process.env.CI ? [[github], [html, { open: never }]] : list, use: { baseURL, trace: retain-on-failure }, webServer: process.env.BASE_URL ? undefined : { command: pnpm exec next start --port 3080, // 用 next start 启动构建产物 reuseExistingServer: !process.env.CI, timeout: 120_000, url: baseURL }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } } ] })两个可借鉴的细节一是webServer用next start起生产构建而非next dev跨浏览器断言的对象更接近线上形态二是当外部注入BASE_URL时直接关闭 webServer允许把同一套测试指向任意环境如预览部署。两份配置共同覆盖了规则要求的“桌面三引擎 移动 viewport”最小矩阵。配套的 npm 脚本定义在 apps/web/package.jsone2eplaywright test、e2e:debug、e2e:headed、e2e:installplaywright install --with-deps、e2e:report、e2e:ui测试框架版本为playwright/test ^1.60.0。编写跨浏览器测试布局、表单、CSS 与 JS 四条主线规则文档给出了一份可直接改造的e2e/cross-browser.spec.ts示例覆盖四类最常见的跨浏览器风险// e2e/cross-browser.spec.ts test.describe(Cross-browser compatibility, () { test(homepage renders correctly, async ({ page, browserName }) { await page.goto(/) // 检查主元素渲染 await expect(page.locator(header)).toBeVisible() await expect(page.locator(main)).toBeVisible() await expect(page.locator(footer)).toBeVisible() // 检查布局偏移CLS const clsValue await page.evaluate(() { return new Promisenumber((resolve) { let cls 0 new PerformanceObserver((list) { for (const entry of list.getEntries()) { if (!(entry as any).hadRecentInput) { cls (entry as any).value } } }).observe({ type: layout-shift, buffered: true }) setTimeout(() resolve(cls), 2000) }) }) expect(clsValue).toBeLessThan(0.1) // 截图用于视觉比对 await expect(page).toHaveScreenshot(homepage-${browserName}.png) }) test(forms work correctly, async ({ page }) { await page.goto(/contact) // 填表 await page.fill([nameemail], testexample.com) await page.fill([namemessage], Test message) // 检查校验是否生效 await page.click(button[typesubmit]) await expect(page.locator([rolealert])).not.toBeVisible() }) test(CSS features degrade gracefully, async ({ page, browserName }) { await page.goto(/) // 检查 CSS Grid 布局 const grid page.locator(.grid-container) const boundingBox await grid.boundingBox() expect(boundingBox?.width).toBeGreaterThan(0) expect(boundingBox?.height).toBeGreaterThan(0) // 检查没有横向溢出 const overflow await page.evaluate(() { return document.documentElement.scrollWidth window.innerWidth }) expect(overflow).toBe(false) }) test(JavaScript features work, async ({ page }) { await page.goto(/) // 测试交互元素 const menuButton page.locator([aria-labelOpen menu]) if (await menuButton.isVisible()) { await menuButton.click() await expect(page.locator([rolemenu])).toBeVisible() } // 测试动态内容加载 const lazyContent page.locator([data-lazy]) if (await lazyContent.count() 0) { await lazyContent.first().scrollIntoViewIfNeeded() await expect(lazyContent.first()).toBeVisible() } }) })几个实现要点值得强调CLS 测量依赖PerformanceObserver的layout-shift条目并通过hadRecentInput过滤掉用户交互引起的位移最后以 2000ms 窗口聚合阈值设为 0.1Core Web Vitals 的“良好”线。browserName被内嵌进截图文件名使同一用例在三个引擎下各留一份基线。横向溢出检查scrollWidth window.innerWidth是跨浏览器布局回归中最便宜也最有效的断言之一Safari 的怪异盒模型与 Firefox 的宽度计算差异经常在此暴露。条件执行isVisible()/count() 0让同一份用例在结构不同的页面上保持幂等。仓库自身的冒烟测试 apps/web/e2e/smoke.spec.ts 展示了更贴近实际的写法——用getByRole语义定位代替 CSS 选择器并用smoke标签打标import { expect, test } from playwright/test test.describe(marketing smoke smoke, () { test(homepage renders the main hero, async ({ page }) { await page.goto(/) await expect( page.getByRole(heading, { name: Trusted front-end quality rules for humans and AI agents }) ).toBeVisible() }) // ... /rules、/mcp 页面类似 })标签体系在 apps/e2e/README.md 中有明确约定smokePR 快速冒烟、critical关键用户流、visual视觉回归、slow长时测试配合pnpm run e2e --grepsmoke就能实现“PR 只跑冒烟、主干跑全量”的分级策略。该 README 还给出了分片并行示例pnpm run e2e --shard1/3…--shard3/3这对浏览器矩阵测试的 CI 耗时控制很实用。视觉回归测试四档 viewport 的截图基线规则文档的视觉回归示例在 4 个 viewport 档位 × 多浏览器上生成截图基线// e2e/visual.spec.ts test.describe(Visual regression, () { const viewports [ { width: 375, height: 667, name: mobile }, { width: 768, height: 1024, name: tablet }, { width: 1280, height: 720, name: desktop }, { width: 1920, height: 1080, name: wide }, ] for (const viewport of viewports) { test(homepage at ${viewport.name}, async ({ page, browserName }) { await page.setViewportSize({ width: viewport.width, height: viewport.height, }) await page.goto(/) await page.waitForLoadState(networkidle) await expect(page).toHaveScreenshot( homepage-${browserName}-${viewport.name}.png, { maxDiffPixels: 100 } ) }) } })要点在于maxDiffPixels: 100是容忍跨引擎抗锯齿差异的关键参数。WebKit 与 Blink 的字体渲染像素级差异很常见阈值过严会产生大量噪声基线更新过松则漏掉真实回归100 像素是文档给出的折中起点截图命名为homepage-${browserName}-${viewport.name}.png把浏览器 × 断点两个维度编码进文件名基线可逐格审查断点档位与仓库 README 中提到的“集中式 viewport 配置”思路一致——apps/e2e/config/test.config.ts 作为所有测试常量URL、超时、viewport、性能阈值、选择器的单一来源避免魔法数字散落。接入 CI/CDGitHub Actions 模式与仓库实际流水线规则文档给出的 CI 工作流模板.github/workflows/cross-browser-tests.yml结构如下name: Cross-Browser Tests on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 with: version: 8 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - name: Install dependencies run: pnpm install - name: Install Playwright browsers run: pnpm exec playwright install --with-deps - name: Build run: pnpm build - name: Run Playwright tests run: pnpm exec playwright test - uses: actions/upload-artifactv4 if: always() with: name: playwright-report path: playwright-report/ retention-days: 30模板中有三个容易踩坑的环节playwright install --with-deps必须在构建之后单独执行因为 webkit 需要系统级依赖库--with-deps会在 CI 容器里补装if: always()保证即使测试失败playwright-report/工件HTML 报告仍会被上传这是事后排查跨浏览器差异的主要证据retries: CI ? 2 : 0与workers: CI ? 1 : undefined的组合含义是CI 中串行执行 失败重试 2 次用稳定性换并发代价是总时长变长长矩阵可再叠加--shard分片。在 Front-End-Checklist 仓库中CI 入口是 scripts/ci/validate.sh其流程为corepack enable→pnpm install --frozen-lockfile→pnpm run lint→ 规则/指南结构校验validate:rule-structure、validate:guide-structure→pnpm --filter web build:content→pnpm run typecheck --filterweb→pnpm run test:ci --filterweb。可以看到仓库把 Playwright E2E 归入web应用的test:ci环节与 lint、类型检查串联执行模板中的pnpm build在 web 应用侧等价于build:content Next 构建之后由next start起服务供 apps/web/playwright.config.ts 的webServer等待就绪超时 120s。扩展矩阵BrowserStack 与真实设备本地 Playwright 的 webkit 项目运行的是桌面 WebKit通常映射到 Linux 上的 Safari 引擎而iOS 上的 Safari 无法被本地完美模拟——规则文档明确提醒触摸交互、PWA 能力等需要真实 iOS 设备或 BrowserStack 之类的云端真机平台。对于必须在云端真机上复用 Playwright 用例的场景文档给出了通过 CDP WebSocket 接入 BrowserStack 的配置方式// browserstack.config.ts use: { connectOptions: { wsEndpoint: wss://cdp.browserstack.com/playwright?caps${encodeURIComponent( JSON.stringify({ browser: chrome, os: Windows, os_version: 11, browserstack.username: process.env.BROWSERSTACK_USERNAME, browserstack.accessKey: process.env.BROWSERSTACK_ACCESS_KEY, }) )}, }, }, })使用要点credentials 只能从环境变量BROWSERSTACK_USERNAME/BROWSERSTACK_ACCESS_KEY注入严禁硬编码——仓库的密钥治理规则如 skills/leaked-secrets 所覆盖的主题与此一致os/os_version/browser三元组决定目标真机组合改一个字段即可扩展矩阵无需改动测试代码。优雅降级特性检测与 CSS Feature Queries自动化测试只能证明“支持的浏览器没坏”跨浏览器体验的另一半靠运行时特性检测 渐进增强。规则文档给出了双端示例。运行时特性检测// utils/feature-detection.ts // CSS 特性 cssGrid: CSS.supports(display, grid), cssSubgrid: CSS.supports(grid-template-columns, subgrid), containerQueries: CSS.supports(container-type, inline-size), hasSelector: CSS.supports(selector(:has(*))), // JavaScript 特性 intersectionObserver: IntersectionObserver in window, resizeObserver: ResizeObserver in window, webComponents: customElements in window, // API 特性 serviceWorker: serviceWorker in navigator, webShare: share in navigator, clipboard: clipboard in navigator, } // 在组件中使用 function FeatureBasedComponent() { if (!features.intersectionObserver) { // 旧浏览器的回退路径 return } return }CSS.supports()用于询问 CSS 能力X in window用于询问 JS 全局两者都是同步、零成本的探测适合在模块初始化时一次性求值。CSSsupports渐进增强/* 渐进增强supports */ .card { /* 所有浏览器的兜底 */ display: flex; flex-direction: column; } supports (display: grid) { .card-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; } } supports (container-type: inline-size) { .card-container { container-type: inline-size; } container (min-width: 400px) { .card { flex-direction: row; } } } /* Safari 专属修正 */ supports (-webkit-touch-callout: none) { .sticky-element { position: -webkit-sticky; position: sticky; } }注意最后一段的前缀回退写法-webkit-sticky在前、sticky在后利用 CSS 层叠规则让支持标准属性的浏览器覆盖前缀版本——这是“旧属性在前、新属性在后”这一通用渐进增强范式。仓库中围绕容器查询、subgrid 等特性的独立规则如 skills/container-queries、skills/subgrid与本文互为参照可进一步按特性查询支持矩阵。常见浏览器差异速查规则文档归纳了高频差异点与对策问题受影响浏览器解决方案Flexbox gapSafari 14.1用 margin 兜底CSS Grid subgrid仅 Firefox支持进度落后使用嵌套 grid:has()选择器旧版 SafariJavaScript 回退平滑滚动Safariscroll-behaviorpolyfill日期输入控件Safari使用日期选择库表单校验 UI全部自定义校验 UIPolyfill 按需加载策略对必须覆盖的旧环境Polyfill 应按探测结果条件加载而不是全量打包// polyfills.ts条件加载 const polyfills: Promisevoid[] [] if (!(IntersectionObserver in window)) { polyfills.push(import(intersection-observer)) } if (!(ResizeObserver in window)) { polyfills.push( import(juggle/resize-observer).then((module) { window.ResizeObserver module.ResizeObserver }) ) } if (!Element.prototype.scrollIntoView) { polyfills.push(import(scroll-into-view-if-needed)) } await Promise.all(polyfills) }动态import()保证每个 polyfill 成为独立 chunk仅在不支持的浏览器中才会请求。这也解释了为什么仓库的性能工具类 apps/e2e/utils/performance.utils.ts 会对资源逐项统计其getResourceMetrics()通过performance.getEntriesByType(resource)汇总totalResources、totalSize、totalDuration与 initiatorType可用来验证“polyfill 未被误加载”这一类优化是否真实生效同一文件里measureMemoryUsage()读取performance.memory这是 Chrome 私有 API在非 Blink 引擎下返回null——本身就是跨浏览器能力差异的实例。仓库的工程化佐证fixtures、Page Object 与性能断言规则文档的示例之外仓库的 E2E 框架apps/e2e/README.md给出了把跨浏览器测试可持续维护的组织方式e2e/ ├── config/ # 集中式测试配置 test.config.ts ├── fixtures/ # 自定义 fixture 与辅助函数 ├── pages/ # Page Objectbase/home/counter ├── tests/ # spec 文件homepage/counter/accessibility/performance └── utils/ # 性能、可访问性等工具类apps/e2e/fixtures/test.fixture.ts 通过base.extendTestFixtures()把homePage、counterPage、accessibilityUtils、performanceUtils、testUtils注入为 fixtureexport const test base.extendTestFixtures({ homePage: async ({ page }, use) { const homePage new HomePage(page) await use(homePage) }, // counterPage / accessibilityUtils / performanceUtils / testUtils 同理 })fixture 的好处是惰性构造 自动注入只有声明了该参数的测试才会实例化对应工具类且 Playwright 的断言自动重试机制天然适配多引擎下的异步渲染差异。人工验收清单与工具选型自动化矩阵之外规则文档列出了 8 项手动验收维度布局— 无破损布局或溢出问题字体排印— 字体正确渲染表单— 输入、校验、提交全部可用导航— 链接、路由、历史记录正常工作媒体— 图片、视频、音频正常播放动画— CSS/JS 动画表现良好触控— 移动端手势可用iOS Safari 重点打印— 打印样式表渲染正确。工具选型表保留原文档口径工具用途成本Playwright自动化测试免费BrowserStack真机测试付费LambdaTest跨浏览器测试付费Sauce LabsCI 集成付费caniuse特性支持度查询免费验证方式与落地检查点规则文档的 Verification 部分要求自动化层面至少覆盖一条主路径与一条受影响的边缘用例并优先使用浏览器或 CI 工具验证修复手动层面在最终渲染结果或运行时行为上确认规则生效并复查共享抽象如公共组件、公共样式保证修复在所有浏览器下一致生效。对照本仓库可操作的验证路径是pnpm --filter web exec e2e:install安装三引擎浏览器与系统依赖pnpm --filter web exec e2e在本地按 apps/web/playwright.config.ts 的 chromium/firefox/webkit 矩阵执行冒烟用例CItrue pnpm --filter web exec e2e复现 CI 行为串行 worker、2 次重试、github reporter失败时用pnpm --filter web exec e2e:report查看 HTML 报告结合trace: retain-on-failure保留的 trace 文件定位引擎差异。最后重申规则“Support Notes”的边界提醒工具链、浏览器自动化行为与 CI 环境在不同平台之间存在差异团队应在实际交付与测试的环境组合中验证工作流当某些浏览器能力在部分支持矩阵中不可用如 CI 上无法装 Edge应当把降级方案显式记录下来——仓库注释掉 msedge 项目的做法正是这一原则的实例。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Front-End-Checklist 跨浏览器测试实战：用 Playwright 矩阵覆盖 Chrome、Firefox、Safari 与 Edge
Front-End-Checklist 跨浏览器测试实战用 Playwright 矩阵覆盖 Chrome、Firefox、Safari 与 Edge【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist用户从不同浏览器访问同一网站而每个浏览器背后是各不相同的渲染引擎。本文基于 Front-End-Checklist 仓库中的跨浏览器测试规则文档 references/rule.md系统讲解如何用 Playwright 搭建覆盖桌面与移动端的浏览器矩阵、编写跨浏览器测试与视觉回归用例、将测试接入 CI/CD并用特性检测与 Polyfill 策略优雅降级同时结合仓库中真实落地的 Playwright 配置、E2E 测试框架与 CI 脚本展示这套规则在工程中的具体实现形态。规则定位为什么跨浏览器测试是“高优先级”仓库将本规则归类在 testing 类别下元数据标注为Priority: high · Difficulty: intermediate · Time: 60 min见 SKILL.md 头部 frontmatter规则来源为 frontendchecklist.io 的 testing/cross-browser-testing 条目。其核心论断是用户从不同浏览器访问你的网站每个浏览器都有独特的渲染引擎。不做跨浏览器测试相当比例的用户可能遇到破损的布局、缺失的功能甚至完全失败。该规则要求站点至少在Chrome、Firefox、Safari、Edge四个浏览器上验证正确性Quick Reference 给出的操作要点是至少覆盖 Chrome、Firefox、Safari、EdgeCI 中用 Playwright 或 BrowserStack 等自动化工具执行使用 CSS 新特性前先用 caniuse 之类的特性查询工具确认支持度桌面与移动端浏览器版本都要测对不支持的特性要记录并优雅降级。目标浏览器矩阵规则文档给出的目标浏览器与优先级如下浏览器引擎优先级备注ChromeBlinkCritical约 65% 市场份额SafariWebKitCriticaliOS/macOS 默认FirefoxGeckoHigh隐私导向用户群EdgeBlinkHighWindows 默认Samsung InternetBlinkMedium三星设备流行注意一个事实边界表中市场份额数字是规则文档给出的静态标注具体占比会随时间变化落地时应以当前时点的数据为准。仓库的真实 Playwright 配置从规则示例到落地实现规则文档给出的参考配置是 6 个 project 的完整矩阵桌面 chromium/firefox/webkit/edge 移动端 Pixel 5/iPhone 12其中 Edge 通过channel: msedge指向品牌版浏览器// playwright.config.ts testDir: ./e2e, fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: html, projects: [ // 桌面浏览器 { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } }, { name: edge, use: { ...devices[Desktop Edge], channel: msedge } }, // 移动浏览器 { name: mobile-chrome, use: { ...devices[Pixel 5] } }, { name: mobile-safari, use: { ...devices[iPhone 12] } }, ], webServer: { command: pnpm dev, port: 3000, reuseExistingServer: !process.env.CI, }, })仓库里实际存在两份 Playwright 配置可以对照理解这套示例如何被“裁剪落地”。apps/e2e独立 E2E 应用的配置apps/e2e/playwright.config.ts 与规则示例高度一致但做了若干工程化调整import { defineConfig, devices } from playwright/test const PORT process.env.PORT || 3080 export default defineConfig({ testDir: ./e2e, testMatch: **/*.spec.ts, fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: process.env.CI ? github : html, use: { baseURL: http://localhost:${PORT}, trace: on-first-retry, screenshot: only-on-failure, video: retain-on-failure }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } }, { name: Mobile Chrome, use: { ...devices[Pixel 5] } }, { name: Mobile Safari, use: { ...devices[iPhone 12] } } // Microsoft Edge 等品牌浏览器以注释形式保留按需开启 ], webServer: { command: pnpm dev, url: http://localhost:${PORT}, reuseExistingServer: !process.env.CI, stdout: ignore, stderr: pipe } })从源码结构看有几处值得注意的取舍Edge 项目被注释掉。devices[Desktop Edge]channel: msedge需要本地安装品牌版 Edge 浏览器在 Linux CI 上未必可用因此仓库默认启用三个引擎Blink/Gecko/WebKit 两个移动 viewport品牌浏览器以注释形式留作开关——这正体现了规则“Support Notes”里的提醒CI 环境的浏览器自动化能力会因平台而异需要记录不可用能力下的降级方案。失败取证三件套trace: on-first-retry、screenshot: only-on-failure、video: retain-on-failure只在重试或失败时产生工件避免报告体积膨胀。reporter 按环境切换CI 用github结果写入 PR本地用html与规则文档中 CI/CD 一节的意图一致。webServer 绑定 3080 端口并通过reuseExistingServer: !process.env.CI保证 CI 中永远起全新 dev server避免复用残留进程造成的假绿/假红。apps/web主站自身的精简矩阵apps/web/playwright.config.ts 则进一步收敛为三个桌面项目并用构建产物而非 dev server 作为被测对象const baseURL process.env.BASE_URL || http://127.0.0.1:3080 export default defineConfig({ testDir: ./e2e, fullyParallel: true, retries: process.env.CI ? 2 : 0, reporter: process.env.CI ? [[github], [html, { open: never }]] : list, use: { baseURL, trace: retain-on-failure }, webServer: process.env.BASE_URL ? undefined : { command: pnpm exec next start --port 3080, // 用 next start 启动构建产物 reuseExistingServer: !process.env.CI, timeout: 120_000, url: baseURL }, projects: [ { name: chromium, use: { ...devices[Desktop Chrome] } }, { name: firefox, use: { ...devices[Desktop Firefox] } }, { name: webkit, use: { ...devices[Desktop Safari] } } ] })两个可借鉴的细节一是webServer用next start起生产构建而非next dev跨浏览器断言的对象更接近线上形态二是当外部注入BASE_URL时直接关闭 webServer允许把同一套测试指向任意环境如预览部署。两份配置共同覆盖了规则要求的“桌面三引擎 移动 viewport”最小矩阵。配套的 npm 脚本定义在 apps/web/package.jsone2eplaywright test、e2e:debug、e2e:headed、e2e:installplaywright install --with-deps、e2e:report、e2e:ui测试框架版本为playwright/test ^1.60.0。编写跨浏览器测试布局、表单、CSS 与 JS 四条主线规则文档给出了一份可直接改造的e2e/cross-browser.spec.ts示例覆盖四类最常见的跨浏览器风险// e2e/cross-browser.spec.ts test.describe(Cross-browser compatibility, () { test(homepage renders correctly, async ({ page, browserName }) { await page.goto(/) // 检查主元素渲染 await expect(page.locator(header)).toBeVisible() await expect(page.locator(main)).toBeVisible() await expect(page.locator(footer)).toBeVisible() // 检查布局偏移CLS const clsValue await page.evaluate(() { return new Promisenumber((resolve) { let cls 0 new PerformanceObserver((list) { for (const entry of list.getEntries()) { if (!(entry as any).hadRecentInput) { cls (entry as any).value } } }).observe({ type: layout-shift, buffered: true }) setTimeout(() resolve(cls), 2000) }) }) expect(clsValue).toBeLessThan(0.1) // 截图用于视觉比对 await expect(page).toHaveScreenshot(homepage-${browserName}.png) }) test(forms work correctly, async ({ page }) { await page.goto(/contact) // 填表 await page.fill([nameemail], testexample.com) await page.fill([namemessage], Test message) // 检查校验是否生效 await page.click(button[typesubmit]) await expect(page.locator([rolealert])).not.toBeVisible() }) test(CSS features degrade gracefully, async ({ page, browserName }) { await page.goto(/) // 检查 CSS Grid 布局 const grid page.locator(.grid-container) const boundingBox await grid.boundingBox() expect(boundingBox?.width).toBeGreaterThan(0) expect(boundingBox?.height).toBeGreaterThan(0) // 检查没有横向溢出 const overflow await page.evaluate(() { return document.documentElement.scrollWidth window.innerWidth }) expect(overflow).toBe(false) }) test(JavaScript features work, async ({ page }) { await page.goto(/) // 测试交互元素 const menuButton page.locator([aria-labelOpen menu]) if (await menuButton.isVisible()) { await menuButton.click() await expect(page.locator([rolemenu])).toBeVisible() } // 测试动态内容加载 const lazyContent page.locator([data-lazy]) if (await lazyContent.count() 0) { await lazyContent.first().scrollIntoViewIfNeeded() await expect(lazyContent.first()).toBeVisible() } }) })几个实现要点值得强调CLS 测量依赖PerformanceObserver的layout-shift条目并通过hadRecentInput过滤掉用户交互引起的位移最后以 2000ms 窗口聚合阈值设为 0.1Core Web Vitals 的“良好”线。browserName被内嵌进截图文件名使同一用例在三个引擎下各留一份基线。横向溢出检查scrollWidth window.innerWidth是跨浏览器布局回归中最便宜也最有效的断言之一Safari 的怪异盒模型与 Firefox 的宽度计算差异经常在此暴露。条件执行isVisible()/count() 0让同一份用例在结构不同的页面上保持幂等。仓库自身的冒烟测试 apps/web/e2e/smoke.spec.ts 展示了更贴近实际的写法——用getByRole语义定位代替 CSS 选择器并用smoke标签打标import { expect, test } from playwright/test test.describe(marketing smoke smoke, () { test(homepage renders the main hero, async ({ page }) { await page.goto(/) await expect( page.getByRole(heading, { name: Trusted front-end quality rules for humans and AI agents }) ).toBeVisible() }) // ... /rules、/mcp 页面类似 })标签体系在 apps/e2e/README.md 中有明确约定smokePR 快速冒烟、critical关键用户流、visual视觉回归、slow长时测试配合pnpm run e2e --grepsmoke就能实现“PR 只跑冒烟、主干跑全量”的分级策略。该 README 还给出了分片并行示例pnpm run e2e --shard1/3…--shard3/3这对浏览器矩阵测试的 CI 耗时控制很实用。视觉回归测试四档 viewport 的截图基线规则文档的视觉回归示例在 4 个 viewport 档位 × 多浏览器上生成截图基线// e2e/visual.spec.ts test.describe(Visual regression, () { const viewports [ { width: 375, height: 667, name: mobile }, { width: 768, height: 1024, name: tablet }, { width: 1280, height: 720, name: desktop }, { width: 1920, height: 1080, name: wide }, ] for (const viewport of viewports) { test(homepage at ${viewport.name}, async ({ page, browserName }) { await page.setViewportSize({ width: viewport.width, height: viewport.height, }) await page.goto(/) await page.waitForLoadState(networkidle) await expect(page).toHaveScreenshot( homepage-${browserName}-${viewport.name}.png, { maxDiffPixels: 100 } ) }) } })要点在于maxDiffPixels: 100是容忍跨引擎抗锯齿差异的关键参数。WebKit 与 Blink 的字体渲染像素级差异很常见阈值过严会产生大量噪声基线更新过松则漏掉真实回归100 像素是文档给出的折中起点截图命名为homepage-${browserName}-${viewport.name}.png把浏览器 × 断点两个维度编码进文件名基线可逐格审查断点档位与仓库 README 中提到的“集中式 viewport 配置”思路一致——apps/e2e/config/test.config.ts 作为所有测试常量URL、超时、viewport、性能阈值、选择器的单一来源避免魔法数字散落。接入 CI/CDGitHub Actions 模式与仓库实际流水线规则文档给出的 CI 工作流模板.github/workflows/cross-browser-tests.yml结构如下name: Cross-Browser Tests on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: pnpm/action-setupv2 with: version: 8 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - name: Install dependencies run: pnpm install - name: Install Playwright browsers run: pnpm exec playwright install --with-deps - name: Build run: pnpm build - name: Run Playwright tests run: pnpm exec playwright test - uses: actions/upload-artifactv4 if: always() with: name: playwright-report path: playwright-report/ retention-days: 30模板中有三个容易踩坑的环节playwright install --with-deps必须在构建之后单独执行因为 webkit 需要系统级依赖库--with-deps会在 CI 容器里补装if: always()保证即使测试失败playwright-report/工件HTML 报告仍会被上传这是事后排查跨浏览器差异的主要证据retries: CI ? 2 : 0与workers: CI ? 1 : undefined的组合含义是CI 中串行执行 失败重试 2 次用稳定性换并发代价是总时长变长长矩阵可再叠加--shard分片。在 Front-End-Checklist 仓库中CI 入口是 scripts/ci/validate.sh其流程为corepack enable→pnpm install --frozen-lockfile→pnpm run lint→ 规则/指南结构校验validate:rule-structure、validate:guide-structure→pnpm --filter web build:content→pnpm run typecheck --filterweb→pnpm run test:ci --filterweb。可以看到仓库把 Playwright E2E 归入web应用的test:ci环节与 lint、类型检查串联执行模板中的pnpm build在 web 应用侧等价于build:content Next 构建之后由next start起服务供 apps/web/playwright.config.ts 的webServer等待就绪超时 120s。扩展矩阵BrowserStack 与真实设备本地 Playwright 的 webkit 项目运行的是桌面 WebKit通常映射到 Linux 上的 Safari 引擎而iOS 上的 Safari 无法被本地完美模拟——规则文档明确提醒触摸交互、PWA 能力等需要真实 iOS 设备或 BrowserStack 之类的云端真机平台。对于必须在云端真机上复用 Playwright 用例的场景文档给出了通过 CDP WebSocket 接入 BrowserStack 的配置方式// browserstack.config.ts use: { connectOptions: { wsEndpoint: wss://cdp.browserstack.com/playwright?caps${encodeURIComponent( JSON.stringify({ browser: chrome, os: Windows, os_version: 11, browserstack.username: process.env.BROWSERSTACK_USERNAME, browserstack.accessKey: process.env.BROWSERSTACK_ACCESS_KEY, }) )}, }, }, })使用要点credentials 只能从环境变量BROWSERSTACK_USERNAME/BROWSERSTACK_ACCESS_KEY注入严禁硬编码——仓库的密钥治理规则如 skills/leaked-secrets 所覆盖的主题与此一致os/os_version/browser三元组决定目标真机组合改一个字段即可扩展矩阵无需改动测试代码。优雅降级特性检测与 CSS Feature Queries自动化测试只能证明“支持的浏览器没坏”跨浏览器体验的另一半靠运行时特性检测 渐进增强。规则文档给出了双端示例。运行时特性检测// utils/feature-detection.ts // CSS 特性 cssGrid: CSS.supports(display, grid), cssSubgrid: CSS.supports(grid-template-columns, subgrid), containerQueries: CSS.supports(container-type, inline-size), hasSelector: CSS.supports(selector(:has(*))), // JavaScript 特性 intersectionObserver: IntersectionObserver in window, resizeObserver: ResizeObserver in window, webComponents: customElements in window, // API 特性 serviceWorker: serviceWorker in navigator, webShare: share in navigator, clipboard: clipboard in navigator, } // 在组件中使用 function FeatureBasedComponent() { if (!features.intersectionObserver) { // 旧浏览器的回退路径 return } return }CSS.supports()用于询问 CSS 能力X in window用于询问 JS 全局两者都是同步、零成本的探测适合在模块初始化时一次性求值。CSSsupports渐进增强/* 渐进增强supports */ .card { /* 所有浏览器的兜底 */ display: flex; flex-direction: column; } supports (display: grid) { .card-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; } } supports (container-type: inline-size) { .card-container { container-type: inline-size; } container (min-width: 400px) { .card { flex-direction: row; } } } /* Safari 专属修正 */ supports (-webkit-touch-callout: none) { .sticky-element { position: -webkit-sticky; position: sticky; } }注意最后一段的前缀回退写法-webkit-sticky在前、sticky在后利用 CSS 层叠规则让支持标准属性的浏览器覆盖前缀版本——这是“旧属性在前、新属性在后”这一通用渐进增强范式。仓库中围绕容器查询、subgrid 等特性的独立规则如 skills/container-queries、skills/subgrid与本文互为参照可进一步按特性查询支持矩阵。常见浏览器差异速查规则文档归纳了高频差异点与对策问题受影响浏览器解决方案Flexbox gapSafari 14.1用 margin 兜底CSS Grid subgrid仅 Firefox支持进度落后使用嵌套 grid:has()选择器旧版 SafariJavaScript 回退平滑滚动Safariscroll-behaviorpolyfill日期输入控件Safari使用日期选择库表单校验 UI全部自定义校验 UIPolyfill 按需加载策略对必须覆盖的旧环境Polyfill 应按探测结果条件加载而不是全量打包// polyfills.ts条件加载 const polyfills: Promisevoid[] [] if (!(IntersectionObserver in window)) { polyfills.push(import(intersection-observer)) } if (!(ResizeObserver in window)) { polyfills.push( import(juggle/resize-observer).then((module) { window.ResizeObserver module.ResizeObserver }) ) } if (!Element.prototype.scrollIntoView) { polyfills.push(import(scroll-into-view-if-needed)) } await Promise.all(polyfills) }动态import()保证每个 polyfill 成为独立 chunk仅在不支持的浏览器中才会请求。这也解释了为什么仓库的性能工具类 apps/e2e/utils/performance.utils.ts 会对资源逐项统计其getResourceMetrics()通过performance.getEntriesByType(resource)汇总totalResources、totalSize、totalDuration与 initiatorType可用来验证“polyfill 未被误加载”这一类优化是否真实生效同一文件里measureMemoryUsage()读取performance.memory这是 Chrome 私有 API在非 Blink 引擎下返回null——本身就是跨浏览器能力差异的实例。仓库的工程化佐证fixtures、Page Object 与性能断言规则文档的示例之外仓库的 E2E 框架apps/e2e/README.md给出了把跨浏览器测试可持续维护的组织方式e2e/ ├── config/ # 集中式测试配置 test.config.ts ├── fixtures/ # 自定义 fixture 与辅助函数 ├── pages/ # Page Objectbase/home/counter ├── tests/ # spec 文件homepage/counter/accessibility/performance └── utils/ # 性能、可访问性等工具类apps/e2e/fixtures/test.fixture.ts 通过base.extendTestFixtures()把homePage、counterPage、accessibilityUtils、performanceUtils、testUtils注入为 fixtureexport const test base.extendTestFixtures({ homePage: async ({ page }, use) { const homePage new HomePage(page) await use(homePage) }, // counterPage / accessibilityUtils / performanceUtils / testUtils 同理 })fixture 的好处是惰性构造 自动注入只有声明了该参数的测试才会实例化对应工具类且 Playwright 的断言自动重试机制天然适配多引擎下的异步渲染差异。人工验收清单与工具选型自动化矩阵之外规则文档列出了 8 项手动验收维度布局— 无破损布局或溢出问题字体排印— 字体正确渲染表单— 输入、校验、提交全部可用导航— 链接、路由、历史记录正常工作媒体— 图片、视频、音频正常播放动画— CSS/JS 动画表现良好触控— 移动端手势可用iOS Safari 重点打印— 打印样式表渲染正确。工具选型表保留原文档口径工具用途成本Playwright自动化测试免费BrowserStack真机测试付费LambdaTest跨浏览器测试付费Sauce LabsCI 集成付费caniuse特性支持度查询免费验证方式与落地检查点规则文档的 Verification 部分要求自动化层面至少覆盖一条主路径与一条受影响的边缘用例并优先使用浏览器或 CI 工具验证修复手动层面在最终渲染结果或运行时行为上确认规则生效并复查共享抽象如公共组件、公共样式保证修复在所有浏览器下一致生效。对照本仓库可操作的验证路径是pnpm --filter web exec e2e:install安装三引擎浏览器与系统依赖pnpm --filter web exec e2e在本地按 apps/web/playwright.config.ts 的 chromium/firefox/webkit 矩阵执行冒烟用例CItrue pnpm --filter web exec e2e复现 CI 行为串行 worker、2 次重试、github reporter失败时用pnpm --filter web exec e2e:report查看 HTML 报告结合trace: retain-on-failure保留的 trace 文件定位引擎差异。最后重申规则“Support Notes”的边界提醒工具链、浏览器自动化行为与 CI 环境在不同平台之间存在差异团队应在实际交付与测试的环境组合中验证工作流当某些浏览器能力在部分支持矩阵中不可用如 CI 上无法装 Edge应当把降级方案显式记录下来——仓库注释掉 msedge 项目的做法正是这一原则的实例。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考