E2E Testing Patterns

核心用法

本技能提供构建高可靠、高性能端到端（E2E）测试套件的全套模式，涵盖 Playwright 与 Cypress 两大主流框架。核心方法包括：

测试分层策略：严格遵循测试金字塔，E2E 测试仅覆盖关键用户路径（如登录→仪表盘→操作→登出、结账流程、跨浏览器兼容性），将单元级逻辑、API 契约和边界场景留给更快的单元/集成测试。

Playwright 核心模式：

• Page Object Model：封装页面逻辑，使测试读起来像用户故事
• Fixtures 自动数据管理：测试前后自动创建/清理测试数据，确保测试独立
• 智能等待机制：彻底摒弃固定超时，采用 waitForLoadState、waitForURL 及自动重试的断言
• 网络模拟：隔离外部服务依赖，模拟延迟和错误响应

Cypress 核心模式：

• 自定义 Commands 封装重复操作（如 cy.login()）
• cy.intercept() 实现 API 拦截与等待

关键稳定性保障：

• 选择器优先级：角色+名称 > 标签 > data-testid > 文本内容，严禁使用 CSS 类和 DOM 结构
• 视觉回归测试：使用 Playwright 的截图对比捕获 UI 变化
• 可访问性测试：集成 axe-core 自动检测无障碍违规

显著优点

1. 消除测试不稳定（Flakiness）：提供系统性诊断清单，从固定超时、竞态条件到数据污染逐一击破
2. 框架双覆盖：同时支持 Playwright（跨浏览器原生、自动等待、追踪 viewer）和 Cypress（实时重载、丰富生态），适应不同技术栈
3. CI/CD 原生设计：配置示例涵盖并行执行、失败重试、产物上传、GitHub Actions 完整流水线
4. 调试体验优秀：Playwright 的 trace viewer、Cypress 的时间旅行、逐步调试模式大幅降低定位成本
5. 企业级安全实践：强调测试数据隔离、清理保障、敏感信息不入测试代码

潜在局限

• 学习曲线：Page Object Model 和 Fixtures 模式对初学者有概念负担
• 维护成本：E2E 测试本身运行慢（秒级），过多测试会拖慢反馈，需严格筛选覆盖范围
• 环境依赖：仍需真实浏览器环境，Docker 配置和资源消耗高于纯单元测试
• 视觉回归噪声：UI 微调可能导致截图对比失败，需配合阈值调优和人工审查

适合人群

• 前端/全栈工程师建立或重构 E2E 测试体系
• QA 自动化工程师消除现有测试套件的不稳定性
• DevOps 工程师将浏览器测试集成到 CI/CD 流水线
• 技术负责人制定团队测试策略与分层规范

常规风险

• 过度测试风险：若将边界场景、组件状态纳入 E2E，将导致套件臃肿、反馈迟缓
• 选择器脆弱性：团队若未统一规范，仍可能使用 CSS 类导致频繁修复中断
• 数据泄漏风险：测试用户未清理可能污染生产数据分析或触发真实业务通知
• 外部服务依赖：未充分模拟第三方 API 时，供应商故障将阻塞部署流水线

核心用法

本 Skill 提供构建可靠 E2E 测试套件的全套模式，支持 Playwright 和 Cypress 两大主流框架：

测试金字塔定位

E2E 测试应覆盖关键用户旅程（登录→仪表盘→操作→退出、结账流程、注册引导），而非替代单元测试。遵循"如果业务崩溃级严重则 E2E 测试，否则用更快测试"原则。

五大核心原则

| 原则 | 实践方式 |

|------|---------|

| 测试行为非实现 | 断言用户可见结果，而非 DOM 结构 |

| 测试独立 | 每个测试自创建/清理数据，支持并行 |

| 确定性等待 | 用 `waitForSelector` 替代固定 `setTimeout` |

| 稳定选择器 | 优先级：role+name > label > data-testid，禁用 CSS 类 |

| 快速反馈 | Mock 外部服务、并行化、分片执行 |

Playwright 关键模式

• 页面对象模型 (POM)：封装页面逻辑，测试可读如用户故事
• Fixtures 自动数据：test.extend 实现 setup/teardown 自动化
• 智能等待：Playwright 断言自带 auto-wait，或用 waitForResponse 等待 API
• 网络 Mock：page.route() 隔离第三方依赖，模拟延迟/错误场景
• 视觉回归：toHaveScreenshot() 捕获 UI 变化
• 可访问性：集成 @axe-core/playwright 扫描 WCAG 违规

Cypress 关键模式

• 自定义命令：Cypress.Commands.add 封装登录等重复操作
• 路由拦截：cy.intercept() + cy.wait('@alias') 精确控制 API 时序

显著优点

1. 抗抖动设计系统化：从选择器策略（禁用 CSS 类/DOM 结构）到等待模式（条件而非超时）再到数据隔离，提供端到端的 flaky test 解决方案
2. 生产级 CI/CD 集成：提供 GitHub Actions 完整配置，含 artifact 上传失败报告、依赖自动安装、服务启动等待等实战细节
3. 双框架覆盖：同时覆盖 Playwright（现代、多浏览器原生并行）和 Cypress（生态成熟、实时重载）两大技术栈
4. 可访问性内建：将 a11y 测试作为一等公民，而非事后补丁
5. 调试体验优秀：trace viewer、screenshot/video 自动捕获、test.step 分段报告，降低失败定位成本

潜在局限性

1. 无真实项目脚手架：仅提供代码片段，需开发者自行搭建项目结构、配置 TypeScript、处理测试数据工厂
2. 框架版本锁定风险：示例基于特定 API 版本，Playwright/Cypress 快速迭代可能导致语法漂移
3. 移动端覆盖有限：虽有 "iPhone 13" 设备配置，但缺乏真实移动手势（滑动、长按、软键盘处理）深度模式
4. 性能测试缺失：未涉及 E2E 测试作为性能基准（Lighthouse CI 集成、加载时间断言）
5. 跨浏览器云服务商：未覆盖 BrowserStack/Sauce Labs 等企业级云测试平台集成

适合人群

| 场景 | 匹配度 |

|------|--------|

| 初次搭建 E2E 测试基础设施的前端团队 | ⭐⭐⭐⭐⭐ |

| 被 flaky tests 困扰、需系统性重构的现有项目 | ⭐⭐⭐⭐⭐ |

| 需要统一 Playwright/Cypress 选型决策的技术负责人 | ⭐⭐⭐⭐⭐ |

| 寻求视觉回归或 a11y 测试集成方案的团队 | ⭐⭐⭐⭐☆ |

| 需要开箱即用的完整项目模板（非片段）的开发者 | ⭐⭐⭐☆☆ |

常规风险

1. 过度测试风险：文档强调"关键路径"，但新手可能误将 E2E 用于本属单元测试的场景，导致套件缓慢臃肿
2. 选择器维护成本：即使使用 data-testid，大规模应用需建立团队约定并配套 lint 规则，否则易退化
3. Mock 与真实环境差距：网络拦截虽提升速度，但可能掩盖真实 API 的 race condition 或 CORS 问题
4. 视觉回归噪声：未提供像素阈值调优、动态内容（时间戳、用户名）掩码策略，易产生误报
5. CI 资源消耗：多浏览器 × 并行 worker × 视频录制可能快速耗尽 CI 分钟配额，需成本意识

最佳实践速查

• 选择器：role+name > label > data-testid > text，禁用 CSS 类/DOM 结构
• 等待：expect(locator).toBeVisible() 替代任何固定超时
• 数据：每个测试独立创建用户，fixture 自动清理
• 调试失败：--headed、--debug、trace viewer、page.pause()
• 绝不：共享测试状态、跳过抖动测试、硬编码选择器中的动态数据