e2e-testing

端到端测试

概述

介绍使用 Playwright 进行端到端测试的架构和模式——如何构建测试套件、组织测试，以及如何运用经过验证的模式来处理身份验证、模拟、视觉回归、无障碍审查和 CI 并行执行。重点在于测试模式的原因和适用时机，而非 Playwright API 的具体细节。

适用场景： 设计测试套件架构、构建页面对象模型、规划 CI 分片策略、设置身份验证流程、使用标签和注释组织测试、实现视觉回归工作流、模拟网络请求、审查无障碍性。

不适用场景： 单元测试（使用 Vitest/Jest）、仅测试 API（使用集成测试）、隔离测试组件（使用组件测试运行器）。如需了解 Playwright API 详情、浏览器自动化、网页抓取或 Playwright 错误排查，请使用 playwright 技能。

快速参考

模式	API/工具	要点
基于角色的定位器	getByRole, getByText, getByLabel	优先于 CSS/XPath 选择器
页面对象模型	tests/pages/ 中的类	封装所有页面专属的定位器和操作
身份验证	storageState + setup 项目	只需验证一次，即可在测试间复用
视觉回归	expect(page).toHaveScreenshot()	遮罩动态内容，避免测试不稳定
无障碍审计	来自 @axe-core/playwright 的 AxeBuilder	在关键流程中使用 .withTags() + .analyze()
Trace 调试	trace: 'on-first-retry'	完整的 DOM 快照、网络日志和时间线
网络模拟	page.route()	无需依赖第三方服务即可运行稳定的测试
HAR 回放	page.routeFromHAR()	根据录制的流量创建高保真模拟
屏蔽图像	page.route('**/*.{png,jpg}', abort)	跳过图像以加快测试
CI 分片	--shard=1/4	将测试套件拆分到多台并行 CI 机器上
Blob 报告	--reporter=blob + merge-reports	将分片结果合并为单份报告
测试标签	{ tag: ['@smoke'] }	使用 --grep 按类别筛选测试
测试步骤	test.step('name', async () => {})	在 Trace Viewer 和报告中对操作分组
仅运行变更的测试	--only-changed=$GITHUB_BASE_REF	仅运行自基准分支以来发生变更的测试文件
原生无障碍检查	toHaveAccessibleName, toHaveRole	完整 axe-core 扫描的轻量替代方案
在报告中包含 Git 信息	reporter 选项 captureGitInfo	将测试报告关联到提交，便于调试 CI
Web 优先断言	expect(element).toBeVisible()	自动等待，而非使用 waitForTimeout
Fixture 组合	mergeTests() / mergeExpects()	将 3 个或更多 fixture 模块合并到一个 test 中
自动 Fixture	在 test.extend() 中设置 { auto: true }	为每项测试运行（日志记录、截图）
Fixture 选项	在 test.extend() 中设置 { option: true }	可通过配置或 test.use() 进行配置
数据驱动测试	生成 test() 调用的 for...of 循环	根据数组或 CSV 文件创建参数化测试
上下文模拟	browser.newContext() 选项	locale、timezone、colorScheme、offline、isMobile
在一项测试中使用两种角色	并发调用 browser.newContext()	为每个上下文分别设置 storageState

常见错误

错误	正确做法
使用 page.waitForTimeout() 等待元素可见	使用 expect(element).toBeVisible() 等优先等待的断言，让其自动等待
直接在测试文件中编写原始定位器	将所有选择器封装在 Page Object Model 类中
直接测试第三方 API（Stripe、Auth0）	使用 page.route() 模拟外部服务，确保测试稳定、快速
使用截图而非跟踪记录来调试 CI 故障	配置 trace: 'on-first-retry' 并使用 Playwright Trace Viewer
通过全局变量在测试之间共享状态	每个测试使用全新的 BrowserContext，实现完全隔离
在单个 CI 任务中运行所有测试	在多台并行机器上使用 Playwright 分片（--shard=1/N）
使用 CSS/XPath 选择器定位元素	使用基于角色的定位器，使其在重构后仍有效并确保可访问性
每个测试都通过 UI 登录	使用 storageState 配合 setup 项目，只需验证身份一次
使用 axe-playwright 中的 injectAxe/checkA11y	使用 @axe-core/playwright 中的 AxeBuilder 和 .analyze()
将 storageState JSON 文件提交到 git	将 playwright/.auth/ 添加到 .gitignore
在登出测试中依赖 storageState	登出会使服务端会话失效——每个登出测试都通过 UI 登录
假设 storageState 会持久化 sessionStorage	它只会保存 Cookie 和 localStorage——使用 addInitScript() 处理 sessionStorage
为不同地区/货币变体重复编写测试代码	使用 fixture 选项（{ option: true }），并按项目覆盖配置
创建 3 个及以上模块的 fixture，却不使用 mergeTests()	使用 mergeTests() 将 fixture 文件组合成一个 test 导出

任务委派

• 发现哪些用户流程缺少 E2E 覆盖：使用 Explore Agent
• 为应用构建完整的 Page Object Model 测试套件：使用 Task Agent
• 为大型测试套件规划 CI 分片策略：使用 Plan Agent

对于 Playwright API 详情、浏览器自动化、抓取、隐身模式、截图/PDF、Docker 部署或 Playwright 错误排查，请使用 playwright skill。

参考资料

• 基于角色的定位器、自动等待、链式调用、筛选和定位器策略
• Page Object Model 架构、fixture 集成和基础页面模式
• Fixture：作用域、组合、自动 fixture、选项和数据驱动测试
• 使用 storageState、setup 项目和多角色测试进行身份验证
• 网络模拟、路由拦截、HAR 回放和 WebSocket 模拟
• 使用 AxeBuilder、WCAG 标签和可复用 fixture 进行无障碍审计
• 视觉回归、快照测试、遮罩、容差阈值和基线管理
• CI 分片、并行执行、blob 报告和浏览器缓存
• 使用标签、注释、test.step 和项目配置组织测试