---
name: tevin-write-e2etest

description: 指导如何编写高质量、可维护的 Playwright E2E 测试。涵盖测试策略、定位器规范、多端适配、流程分支覆盖、数据管理、Mock 方案等工程化实践。

编写 Playwright E2E 测试规范

一、核心原则（铁律）

• 测试即文档：每个 test() 的描述必须使用清晰的中文（如 test('用户输入错误密码时应提示登录失败')）。
• 独立性：每个测试用例必须能够独立运行，**严禁**依赖前一个用例的浏览器状态。
• 无硬等待：**绝对禁止**使用 page.waitForTimeout()。必须使用 Playwright 自带的智能等待。
• 原子性：一个测试用例只验证一个核心业务流程或一个操作分支。

二、项目测试环境

• 测试目录: test/e2e/
• 路由模式: hash 路由，http://localhost:5173/#/preview/pages/<path>
• 开发服务器: pnpm dev (http://localhost:5173)
• 运行命令: pnpm exec playwright test test/e2e/<spec>.ts

三、多端适配策略

当需求涉及 PC 和移动端两种展示交互时，**不得**在单个测试内写 if (isMobile) 逻辑。

import { test, devices } from '@playwright/test';

['桌面端 Chrome', '移动端 iPhone 12'].forEach((deviceName) => {
  test.describe(`功能 - ${deviceName}`, () => {
    test.use({
      ...(deviceName === '移动端 iPhone 12'
        ? devices['iPhone 12']
        : { viewport: { width: 1280, height: 720 } }
      )
    });

    test('测试场景', async ({ page }) => { ... });
  });
});

四、流程分支与交互路径覆盖

对于包含多种用户操作结果的组件（如表单提交成功、校验失败），**必须**为每个分支生成独立的 test() 用例。

test.describe('用户操作流程', () => {
  test('操作成功，跳转至结果页', async ({ page }) => { ... });
  test('输入错误，显示错误提示', async ({ page }) => { ... });
  test('网络异常，显示网络错误提示', async ({ page }) => {
    // 使用 page.route 模拟网络错误
  });
});

五、定位器选择规范（强制）

优先级：getByTestId > getByRole > getByText > getByLabel

严禁使用：复杂 CSS 层级选择器（如 div > ul > li:nth-child(2) > button）

// ❌ 错误
page.locator('#app > div:nth-child(3) > button')

// ✅ 正确
page.getByTestId('module-action-btn')

六、网络模拟与异常处理

test('请求失败应提示错误', async ({ page }) => {
  await page.route('**/api/data', route => route.fulfill({
    status: 500,
    body: JSON.stringify({ message: '服务器错误' })
  }));
  await expect(page.getByText('服务器错误')).toBeVisible();
});

七、代码生成后自检清单

• [ ] 是否包含 waitForTimeout？（有则替换）
• [ ] 是否使用了脆弱的 CSS 定位器？（有则替换）
• [ ] 是否遗漏了异常分支的测试用例？
• [ ] 移动端/PC 端是否被正确分离？

参考资料

详细代码模板（如 Page Object Model 完整实现、Playwright 配置示例、CI 集成等）请查阅：

• .claude/skills/tevin-write-e2etest/references/playwright-patterns.md