cypress

Cypress（E2E + 组件测试）

概述

Cypress 可运行浏览器自动化测试，提供一流的网络控制、时间旅行调试和完善的本地开发工作流。可用于关键路径 E2E 测试；当浏览器级渲染很重要时，也可用于组件测试。

快速开始

安装并打开

npm i -D cypress
npx cypress open

最小测试规范

// cypress/e2e/health.cy.ts
describe("health", () => {
  it("loads", () => {
    cy.visit("/");
    cy.contains("Hello").should("be.visible");
  });
});

核心模式

1) 稳定的选择器

优先使用 data-testid（或 data-cy）属性作为选择器。关键交互应避免使用脆弱的 CSS 链式选择器和仅基于文本的选择器。

<button data-testid="save-user">Save</button>

cy.get('[data-testid="save-user"]').click();

2) 确定性等待（避免固定休眠）

等待应用中可见的条件或网络别名，而不是使用 cy.wait(1000)。

cy.intercept("GET", "/api/users/*").as("getUser");
cy.visit("/users/1");
cy.wait("@getUser");
cy.get('[data-testid="user-email"]').should("not.be.empty");

3) 使用 cy.intercept 控制网络

模拟响应，以实现确定性测试并提高速度。将少量“真实后端”冒烟测试单独运行。

cy.intercept("GET", "/api/users/1", {
  statusCode: 200,
  body: { id: "1", email: "[email protected]" },
}).as("getUser");

4) 身份验证策略

优先使用 cy.session 缓存登录状态，以提升速度和稳定性。

// cypress/support/commands.ts
Cypress.Commands.add("login", () => {
  cy.session("user", () => {
    cy.request("POST", "/api/auth/login", {
      email: "[email protected]",
      password: "password",
    });
  });
});

// e2e spec
beforeEach(() => {
  cy.login();
});

组件测试

运行组件测试，在隔离环境中验证 UI 行为，同时保留浏览器渲染。

npx cypress open --component

// cypress/component/Button.cy.tsx
import React from "react";
import Button from "../../src/Button";

describe("<Button />", () => {
  it("clicks", () => {
    cy.mount(<Button onClick={cy.stub().as("onClick")}>Save</Button>);
    cy.contains("Save").click();
    cy.get("@onClick").should("have.been.calledOnce");
  });
});

CI 模式

工件（视频/屏幕截图）

保存失败运行的工件；视频可设为可选，以减少存储空间占用。

// cypress.config.ts
import { defineConfig } from "cypress";

export default defineConfig({
  video: false,
  screenshotOnRunFailure: true,
  retries: { runMode: 2, openMode: 0 },
});

并行化（Cypress Cloud）

当运行时间成为反馈周期的主要瓶颈时，可通过 Cypress Cloud 并行运行耗时较长的 E2E 测试套件。

反模式

• 使用 cy.wait(1000) 作为同步机制。
• 通过深层 CSS 路径选择元素。
• 在同一个测试规范中混用大量网络模拟和“真实后端”断言。
• 依赖测试顺序；使用 cy.session 和每项测试的设置来隔离状态。

故障排除

症状：点击不稳定或找不到元素

处理方法：

• 为元素添加 data-testid 标记。
• 交互前断言元素可见（should("be.visible")）。
• 等待用于渲染该元素的数据所对应的网络别名。

症状：测试仅在 CI 中失败

处理方法：

• 增加运行模式下的重试次数，并在失败时记录屏幕截图。
• 确认视口和 baseUrl 配置与 CI 环境一致。
• 消除对仅在本地存在的种子数据的依赖；通过 API 调用创建数据。

资源

• Cypress 文档：https://docs.cypress.io/
• 最佳实践：https://docs.cypress.io/guides/references/best-practices