E2E 测试规范

适用于使用 Playwright 或 Cypress 进行端到端测试的前端项目。

适用场景

• - 编写或维护 E2E 测试
• 配置 Playwright / Cypress 项目
• 设计 Page Object 或测试结构
• 将 E2E 集成到 CI 流水线

工具选择

目录结构

Playwright

e2e/ # 或 tests/e2e/
├── playwright.config.ts # 配置（浏览器、baseURL、超时）
├── fixtures/ # 测试夹具（登录态、mock 数据）
│ └── auth.ts
├── pages/ # Page Object
│ ├── LoginPage.ts
│ ├── DashboardPage.ts
│ └── UserListPage.ts
├── specs/ # 测试用例
│ ├── auth/
│ │ └── login.spec.ts
│ ├── dashboard/
│ │ └── dashboard.spec.ts
│ └── users/
│ └── user-list.spec.ts
└── utils/ # 测试工具
└── test-helpers.ts

Cypress

cypress/
├── e2e/ # 测试用例
│ ├── auth/
│ │ └── login.cy.ts
│ └── dashboard/
│ └── dashboard.cy.ts
├── fixtures/ # 静态数据
│ └── users.json
├── support/
│ ├── commands.ts # 自定义命令
│ └── e2e.ts # 全局 before/after
└── pages/ # Page Object（可选）
└── LoginPage.ts

Page Object 模式

• - 每个页面/流程一个 Page 类，封装选择器和操作
• 测试用例只调用 Page 方法，不直接写选择器
• 选择器优先使用 data-testid，其次 role、label，避免依赖实现细节

typescript
// Playwright 示例
export class LoginPage {
constructor(private page: Page) {}

async goto() {
await this.page.goto(/login);
}

async login(email: string, password: string) {
await this.page.getByTestId(email-input).fill(email);
await this.page.getByTestId(password-input).fill(password);
await this.page.getByRole(button, { name: 登录 }).click();
}

async expectErrorMessage(text: string) {
await expect(this.page.getByTestId(error-message)).toContainText(text);
}
}

测试编写原则

• - 测试用例描述业务场景，而非实现细节
• 一个用例覆盖一个完整用户流程（如：登录 → 进入列表 → 筛选）
• 避免测试间依赖，每个用例可独立运行
• 使用 beforeEach 做前置（如登录），避免在用例中重复
• 敏感操作（删除、支付）使用 mock 或测试环境专用接口

CI 集成

Playwright

yaml

GitHub Actions 示例

• - name: Playwright tests

• - uses: actions/upload-artifact@v4

Cypress

yaml

• - name: Cypress tests

视口与设备

• - 关键流程至少覆盖：桌面（1920×1080）、平板（768×1024）、移动（375×667）
• 使用 Playwright 的 projects 或 Cypress 的 viewport 配置多视口
• 响应式回归测试可抽样关键断点，不必全量

强约束

• - 不要依赖固定等待（setTimeout），使用 waitFor、expect 等断言等待
• 不要在生产环境跑 E2E，使用 staging 或 mock 服务
• 避免在 E2E 中测试纯 UI 细节（如颜色、间距），交给单元测试或视觉回归
• 失败时保留截图、Trace、视频，便于排查