From c37a8fd359ff758f9bfb1cc8b91050612a3ae065 Mon Sep 17 00:00:00 2001
From: Tevin <tingquanren@163.com>
Date: Thu, 09 Apr 2026 18:13:15 +0800
Subject: [PATCH] refactor(skill): 重构 tevin-write-e2etest 技能结构
---
.claude/skills/tevin-write-e2etest/SKILL.md | 135 ++++++++--------
.claude/skills/tevin-write-e2etest/references/playwright-patterns.md | 326 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 394 insertions(+), 67 deletions(-)
diff --git a/.claude/skills/tevin-write-e2etest/SKILL.md b/.claude/skills/tevin-write-e2etest/SKILL.md
index 9dc9241..1468dcb 100644
--- a/.claude/skills/tevin-write-e2etest/SKILL.md
+++ b/.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`
diff --git a/.claude/skills/tevin-write-e2etest/references/playwright-patterns.md b/.claude/skills/tevin-write-e2etest/references/playwright-patterns.md
new file mode 100644
index 0000000..0563199
--- /dev/null
+++ b/.claude/skills/tevin-write-e2etest/references/playwright-patterns.md
@@ -0,0 +1,326 @@
+---
+name: e2e-testing
+description: Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies.
+origin: ECC
+---
+
+# E2E Testing Patterns
+
+Comprehensive Playwright patterns for building stable, fast, and maintainable E2E test suites.
+
+## Test File Organization
+
+```
+tests/
+├── e2e/
+│ ├── auth/
+│ │ ├── login.spec.ts
+│ │ ├── logout.spec.ts
+│ │ └── register.spec.ts
+│ ├── features/
+│ │ ├── browse.spec.ts
+│ │ ├── search.spec.ts
+│ │ └── create.spec.ts
+│ └── api/
+│ └── endpoints.spec.ts
+├── fixtures/
+│ ├── auth.ts
+│ └── data.ts
+└── playwright.config.ts
+```
+
+## Page Object Model (POM)
+
+```typescript
+import { Page, Locator } from '@playwright/test'
+
+export class ItemsPage {
+ readonly page: Page
+ readonly searchInput: Locator
+ readonly itemCards: Locator
+ readonly createButton: Locator
+
+ constructor(page: Page) {
+ this.page = page
+ this.searchInput = page.locator('[data-testid="search-input"]')
+ this.itemCards = page.locator('[data-testid="item-card"]')
+ this.createButton = page.locator('[data-testid="create-btn"]')
+ }
+
+ async goto() {
+ await this.page.goto('/items')
+ await this.page.waitForLoadState('networkidle')
+ }
+
+ async search(query: string) {
+ await this.searchInput.fill(query)
+ await this.page.waitForResponse(resp => resp.url().includes('/api/search'))
+ await this.page.waitForLoadState('networkidle')
+ }
+
+ async getItemCount() {
+ return await this.itemCards.count()
+ }
+}
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ItemsPage } from '../../pages/ItemsPage'
+
+test.describe('Item Search', () => {
+ let itemsPage: ItemsPage
+
+ test.beforeEach(async ({ page }) => {
+ itemsPage = new ItemsPage(page)
+ await itemsPage.goto()
+ })
+
+ test('should search by keyword', async ({ page }) => {
+ await itemsPage.search('test')
+
+ const count = await itemsPage.getItemCount()
+ expect(count).toBeGreaterThan(0)
+
+ await expect(itemsPage.itemCards.first()).toContainText(/test/i)
+ await page.screenshot({ path: 'artifacts/search-results.png' })
+ })
+
+ test('should handle no results', async ({ page }) => {
+ await itemsPage.search('xyznonexistent123')
+
+ await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+ expect(await itemsPage.getItemCount()).toBe(0)
+ })
+})
+```
+
+## Playwright Configuration
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+ testDir: './tests/e2e',
+ fullyParallel: true,
+ forbidOnly: !!process.env.CI,
+ retries: process.env.CI ? 2 : 0,
+ workers: process.env.CI ? 1 : undefined,
+ reporter: [
+ ['html', { outputFolder: 'playwright-report' }],
+ ['junit', { outputFile: 'playwright-results.xml' }],
+ ['json', { outputFile: 'playwright-results.json' }]
+ ],
+ use: {
+ baseURL: process.env.BASE_URL || 'http://localhost:3000',
+ trace: 'on-first-retry',
+ screenshot: 'only-on-failure',
+ video: 'retain-on-failure',
+ actionTimeout: 10000,
+ navigationTimeout: 30000,
+ },
+ projects: [
+ { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+ { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+ { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+ { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+ ],
+ webServer: {
+ command: 'npm run dev',
+ url: 'http://localhost:3000',
+ reuseExistingServer: !process.env.CI,
+ timeout: 120000,
+ },
+})
+```
+
+## Flaky Test Patterns
+
+### Quarantine
+
+```typescript
+test('flaky: complex search', async ({ page }) => {
+ test.fixme(true, 'Flaky - Issue #123')
+ // test code...
+})
+
+test('conditional skip', async ({ page }) => {
+ test.skip(process.env.CI, 'Flaky in CI - Issue #123')
+ // test code...
+})
+```
+
+### Identify Flakiness
+
+```bash
+npx playwright test tests/search.spec.ts --repeat-each=10
+npx playwright test tests/search.spec.ts --retries=3
+```
+
+### Common Causes & Fixes
+
+**Race conditions:**
+```typescript
+// Bad: assumes element is ready
+await page.click('[data-testid="button"]')
+
+// Good: auto-wait locator
+await page.locator('[data-testid="button"]').click()
+```
+
+**Network timing:**
+```typescript
+// Bad: arbitrary timeout
+await page.waitForTimeout(5000)
+
+// Good: wait for specific condition
+await page.waitForResponse(resp => resp.url().includes('/api/data'))
+```
+
+**Animation timing:**
+```typescript
+// Bad: click during animation
+await page.click('[data-testid="menu-item"]')
+
+// Good: wait for stability
+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
+await page.waitForLoadState('networkidle')
+await page.locator('[data-testid="menu-item"]').click()
+```
+
+## Artifact Management
+
+### Screenshots
+
+```typescript
+await page.screenshot({ path: 'artifacts/after-login.png' })
+await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
+await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })
+```
+
+### Traces
+
+```typescript
+await browser.startTracing(page, {
+ path: 'artifacts/trace.json',
+ screenshots: true,
+ snapshots: true,
+})
+// ... test actions ...
+await browser.stopTracing()
+```
+
+### Video
+
+```typescript
+// In playwright.config.ts
+use: {
+ video: 'retain-on-failure',
+ videosPath: 'artifacts/videos/'
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ - run: npm ci
+ - run: npx playwright install --with-deps
+ - run: npx playwright test
+ env:
+ BASE_URL: ${{ vars.STAGING_URL }}
+ - uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: playwright-report
+ path: playwright-report/
+ retention-days: 30
+```
+
+## Test Report Template
+
+```markdown
+# E2E Test Report
+
+**Date:** YYYY-MM-DD HH:MM
+**Duration:** Xm Ys
+**Status:** PASSING / FAILING
+
+## Summary
+- Total: X | Passed: Y (Z%) | Failed: A | Flaky: B | Skipped: C
+
+## Failed Tests
+
+### test-name
+**File:** `tests/e2e/feature.spec.ts:45`
+**Error:** Expected element to be visible
+**Screenshot:** artifacts/failed.png
+**Recommended Fix:** [description]
+
+## Artifacts
+- HTML Report: playwright-report/index.html
+- Screenshots: artifacts/*.png
+- Videos: artifacts/videos/*.webm
+- Traces: artifacts/*.zip
+```
+
+## Wallet / Web3 Testing
+
+```typescript
+test('wallet connection', async ({ page, context }) => {
+ // Mock wallet provider
+ await context.addInitScript(() => {
+ window.ethereum = {
+ isMetaMask: true,
+ request: async ({ method }) => {
+ if (method === 'eth_requestAccounts')
+ return ['0x1234567890123456789012345678901234567890']
+ if (method === 'eth_chainId') return '0x1'
+ }
+ }
+ })
+
+ await page.goto('/')
+ await page.locator('[data-testid="connect-wallet"]').click()
+ await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
+})
+```
+
+## Financial / Critical Flow Testing
+
+```typescript
+test('trade execution', async ({ page }) => {
+ // Skip on production — real money
+ test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
+
+ await page.goto('/markets/test-market')
+ await page.locator('[data-testid="position-yes"]').click()
+ await page.locator('[data-testid="trade-amount"]').fill('1.0')
+
+ // Verify preview
+ const preview = page.locator('[data-testid="trade-preview"]')
+ await expect(preview).toContainText('1.0')
+
+ // Confirm and wait for blockchain
+ await page.locator('[data-testid="confirm-trade"]').click()
+ await page.waitForResponse(
+ resp => resp.url().includes('/api/trade') && resp.status() === 200,
+ { timeout: 30000 }
+ )
+
+ await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
+})
+```
--
Gitblit v1.9.1