E2E 测试规范

---

name: e2e-testing

description: Playwright 与 Cypress E2E 测试规范，涵盖目录结构、Page Object、CI 集成、视口与设备配置。当用户提到 E2E、端到端测试、Playwright、Cypress、集成测试时自动激活。

version: 1.0.0

---

# E2E 测试规范

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

适用场景

工具选择

| 工具 | 适用 | 特点 |

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

| **Playwright** | 推荐，新项目优先 | 多浏览器、自动等待、并行、Trace、跨平台 |

| **Cypress** | 已有项目或团队熟悉 | 交互式调试、时间旅行、组件测试 |

目录结构

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 模式

// 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);
  }
}

测试编写原则

CI 集成

Playwright

# GitHub Actions 示例
- name: Playwright tests
  run: npx playwright test
  env:
    CI: true
- uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-report
    path: playwright-report/

Cypress

- name: Cypress tests
  run: npx cypress run
  env:
    CYPRESS_baseUrl: ${{ secrets.CYPRESS_BASE_URL }}

视口与设备

强约束