docs(skill): 将 playwright-patterns.md 翻译为中文

Tevin

2 days ago 9f6212d61eba53eb4da504876f5a01b93a80fc1c

 .claude/skills/tevin-write-e2etest/SKILL.md

@@ -1,93 +1,94 @@
---
name: tevin-write-e2etest
description: 为项目编写 Playwright E2E 测试脚本的技能。适用于实现组件或功能的端到端测试，避免使用 MCP，改用传统的测试脚本方式。
license: MIT
compatibility: 项目使用 @playwright/test、React、Vite、TypeScript
metadata:
  author: tevin
  version: "1.0"
description: 指导如何编写高质量、可维护的 Playwright E2E 测试。涵盖测试策略、定位器规范、多端适配、流程分支覆盖、数据管理、Mock 方案等工程化实践。
---

使用 `@playwright/test` 编写 E2E 测试，不使用 MCP。
# 编写 Playwright E2E 测试规范

## 项目测试规范
## 一、核心原则（铁律）

**测试目录**: `test/e2e/`
**路由模式**: hash 路由，`#/preview/pages/<path>`
**开发服务器**: `pnpm dev` (http://localhost:5173)
- **测试即文档**：每个 `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)` 逻辑。

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

test.describe('功能名称', () => {
  test.beforeEach(async ({ page }) => {
    // 访问包含该功能的页面
    await page.goto('http://localhost:5173/#/preview/pages/xxx/Page.tsx');
  });
['桌面端 Chrome', '移动端 iPhone 12'].forEach((deviceName) => {
  test.describe(`功能 - ${deviceName}`, () => {
    test.use({
      ...(deviceName === '移动端 iPhone 12'
        ? devices['iPhone 12']
        : { viewport: { width: 1280, height: 720 } }
      )
    });

  test('测试场景描述', async ({ page }) => {
    // 使用 page.waitForSelector 或 expect 等待元素
    await expect(page.locator('text=预期文本')).toBeVisible();
  });

  test('交互功能测试', async ({ page }) => {
    // 点击操作
    await page.click('text=可点击文本');
    // 验证结果
    await expect(page.locator('text=结果文本')).toBeVisible();
    test('测试场景', async ({ page }) => { ... });
  });
});
```

## 编写步骤
## 四、流程分支与交互路径覆盖

1. **确认测试页面路径**
   - 组件示例页面: `http://localhost:5173/#/preview/pages/<component>/<Page>.tsx`
   - 如果不确定，先运行 `pnpm dev` 访问确认
对于包含多种用户操作结果的组件（如表单提交成功、校验失败），**必须**为每个分支生成独立的 `test()` 用例。

2. **分析页面功能**
   - 识别页面的主要元素（菜单、表单、按钮等）
   - 确定需要测试的用户交互流程

3. **编写测试用例**
   - 每个 `test` 块描述一个独立场景
   - 使用 `test.beforeEach` 统一初始化
   - 用 `expect` 断言而非 `console.log` 验证

4. **运行测试**
   - 确保开发服务器已启动: `pnpm dev`
   - 运行测试: `pnpm exec playwright test test/e2e/<spec>.ts`

## 最佳实践

- **使用稳定选择器**: 优先使用 `text=` 定位文本，避免脆弱的 CSS 选择器
- **显式等待**: 使用 `expect(locator).toBeVisible()` 而非 `page.waitForTimeout()`
- **独立测试**: 每个测试应能独立运行，不依赖其他测试的状态
- **清晰命名**: 测试名称应描述预期行为，如 `should display menu items`

## 常见模式

**菜单导航测试**:
```typescript
test('菜单点击跳转', async ({ page }) => {
  await page.click('text=菜单项');
  await expect(page.locator('text=目标页面内容')).toBeVisible();
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`）

```typescript
test('表单提交', async ({ page }) => {
  await page.fill('input[placeholder="输入框"]', '测试值');
  await page.click('button:has-text("提交")');
  await expect(page.locator('text=成功消息')).toBeVisible();
// ❌ 错误
page.locator('#app > div:nth-child(3) > button')

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

## 六、网络模拟与异常处理

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

## 注意事项
## 七、代码生成后自检清单

- 不要使用 Playwright MCP (`@playwright/mcp` 已从项目移除)
- 测试文件后缀为 `.spec.ts`
- 首次运行需要安装浏览器: `pnpm exec playwright install`
- [ ] 是否包含 `waitForTimeout`？（有则替换）
- [ ] 是否使用了脆弱的 CSS 定位器？（有则替换）
- [ ] 是否遗漏了异常分支的测试用例？
- [ ] 移动端/PC 端是否被正确分离？

## 参考资料

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

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