From 9f6212d61eba53eb4da504876f5a01b93a80fc1c Mon Sep 17 00:00:00 2001
From: Tevin <tingquanren@163.com>
Date: Thu, 09 Apr 2026 18:19:50 +0800
Subject: [PATCH] docs(skill): 将 playwright-patterns.md 翻译为中文
---
.claude/skills/tevin-write-e2etest/SKILL.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 94 insertions(+), 0 deletions(-)
diff --git a/.claude/skills/tevin-write-e2etest/SKILL.md b/.claude/skills/tevin-write-e2etest/SKILL.md
new file mode 100644
index 0000000..1468dcb
--- /dev/null
+++ b/.claude/skills/tevin-write-e2etest/SKILL.md
@@ -0,0 +1,94 @@
+---
+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)` 逻辑。
+
+```typescript
+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()` 用例。
+
+```typescript
+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
+// ❌ 错误
+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();
+});
+```
+
+## 七、代码生成后自检清单
+
+- [ ] 是否包含 `waitForTimeout`？（有则替换）
+- [ ] 是否使用了脆弱的 CSS 定位器？（有则替换）
+- [ ] 是否遗漏了异常分支的测试用例？
+- [ ] 移动端/PC 端是否被正确分离？
+
+## 参考资料
+
+详细代码模板（如 Page Object Model 完整实现、Playwright 配置示例、CI 集成等）请查阅：
+
+- `.claude/skills/tevin-write-e2etest/references/playwright-patterns.md`
--
Gitblit v1.9.1