Cypress 前端 E2E 测试框架技术调研

Cypress 是面向现代 Web 应用的端到端测试框架，以优秀的开发者体验、实时重载、时间旅行调试和直观的 DOM 快照著称。它运行在浏览器同进程（与传统 WebDriver 不同），长期是 React/Vue 团队 E2E 的热门选择；近年 Playwright 在跨浏览器和并行方面竞争加剧，但 Cypress 在 DX 和生态上仍具强大吸引力。

一、 基本信息

二、 技术定位与简介

Cypress 提供：

• E2E 测试：完整用户流程自动化。
• Component Testing：在真实浏览器中测 React/Vue/Angular 组件。
• 时间旅行调试：每一步 DOM 快照可回溯。
• 自动等待与重试：断言前自动等待条件满足。
• 网络存根：cy.intercept 拦截和 Mock 请求。
• Cypress Cloud：并行、录制、分析（商业）。

架构特点：测试代码运行在浏览器内的 Node 环境（通过代理），可直接访问应用 DOM，调试体验极佳。

三、 快速上手安装说明

1. 安装

pnpm add -D cypress
npx cypress open

2. cypress.config.ts

import { defineConfig } from 'cypress'
 
export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'tests/e2e/**/*.cy.ts',
    supportFile: 'tests/e2e/support/e2e.ts',
    setupNodeEvents(on, config) {
      // plugins
      return config
    },
  },
})

3. 第一个 E2E 测试

describe('Login', () => {
  it('logs in successfully', () => {
    cy.visit('/login')
    cy.get('[data-cy=email]').type('[email protected]')
    cy.get('[data-cy=password]').type('password')
    cy.get('[data-cy=submit]').click()
    cy.contains('Welcome').should('be.visible')
  })
})

4. 网络 Mock

cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Alice' }],
}).as('getUsers')
 
cy.visit('/users')
cy.wait('@getUsers')
cy.contains('Alice').should('be.visible')

5. 运行

npx cypress run
npx cypress open

四、 核心特性

1. 时间旅行调试

Cypress Runner 显示每步 DOM 状态。

2. 自动等待

命令自动重试直到超时。

3. cy.intercept

强大的请求/响应拦截与 Mock。

4. 组件测试

cypress mount 测隔离组件（React/Vue）。

5. 自定义命令

Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login')
  cy.get('[data-cy=email]').type(email)
  cy.get('[data-cy=password]').type(password)
  cy.get('[data-cy=submit]').click()
})

6. 截图与视频

失败自动截图，CI 可录屏。

7. Cypress Cloud

并行化、测试分组、flake 检测（付费）。

8. 插件生态

cypress-real-events、cypress-axe 等。

五、 适用场景

1. 黄金适用场景

• 前端团队主导 E2E，重视调试 DX。
• React/Vue SPA 关键流程。
• 需要 cy.intercept 精细网络控制。
• 组件测试与 E2E 统一工具。
• 已有 Cypress 投资的企业。

2. 局限适用场景

• 多浏览器矩阵（Playwright 更强）。
• 多标签页/多域名复杂场景（历史局限，逐步改善）。
• 非浏览器环境 API 测试（Playwright request 或 Vitest）。
• 全新项目可评估 Playwright vs Cypress。

六、 技术亮点

1. 开发者体验

Runner 实时预览是行业标杆之一。

2. 调试效率

时间旅行减少「为什么失败」的排查时间。

3. intercept API

直观 Mock 网络，适合前端 E2E。

4. 组件测试统一

E2E 与组件测同一工具链。

5. 社区与插件

丰富博客、课程、插件。

七、 核心概念与架构

digraph Cypress_Architecture {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  Node [label="Node.js\n(Test Runner)", fillcolor="#bae6fd"]
  Browser [label="Browser\n(App + Cypress)"]
  Proxy [label="Network Proxy"]
  App [label="Application Under Test"]
 
  Node -> Browser
  Browser -> Proxy
  Proxy -> App
}

八、 技术局限与边界

1. 浏览器支持：以 Chromium 系为主，Firefox/WebKit 支持历史弱于 Playwright。
2. iframe/多标签：曾有限制，需查当前版本能力。
3. 并行：本地并行需 Cypress Cloud 或第三方方案。
4. 跨域：特殊场景需配置 chromeWebSecurity。
5. 速度：大套件可能慢于 Playwright 并行。
6. 非真正的多浏览器驱动：架构与 Playwright 不同。

九、 生态地图

十、 生态集成

十一、 开发与工程化

1. data-cy 属性

<button data-cy="submit">Submit</button>

稳定选择器，与 Testing Library testid 类似。

2. 本项目 E2E 目录

apps/tests/e2e/，镜像源码结构。

3. 环境变量

cypress.env.json 或 CYPRESS_* 注入测试账号。

十二、 性能与安全

• CI 使用 cypress run --browser chrome --headless。
• 控制 video 和 screenshot 存储成本。
• 测试凭证用 secrets，不提交仓库。
• cy.intercept 勿泄露生产 API 结构到公开仓库。

十三、 技术对比

十四、 最佳实践

1. 使用 data-cy 或语义选择器，避免脆弱 CSS。
2. cy.intercept 稳定 API 响应，减少 flaky。
3. 自定义命令封装登录等重复流程。
4. 避免不必要 cy.wait(毫秒)，用断言自动等待。
5. 关键路径 E2E，细节逻辑交给 Vitest。
6. 评估 Cypress Cloud 是否值得并行投资。
7. 新项目对比 Playwright 后选型，勿盲目跟风。
8. 组件测试覆盖交互逻辑，非纯样式。
9. 定期清理过时 intercept 和 fixture。
10. 营销页遵循项目规范：build + 关键 Cypress/Playwright 路径。

十五、 学习与社区资源

• 官方文档：https://docs.cypress.io/
• Best Practices：https://docs.cypress.io/guides/references/best-practices
• GitHub：https://github.com/cypress-io/cypress
• Real World App：官方示例项目