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/references/playwright-patterns.md | 320 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 320 insertions(+), 0 deletions(-)
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..e711368
--- /dev/null
+++ b/.claude/skills/tevin-write-e2etest/references/playwright-patterns.md
@@ -0,0 +1,320 @@
+# Playwright E2E 测试模式参考
+
+构建稳定、快速、可维护的 E2E 测试套件的 Playwright 模式集合。
+
+## 测试文件组织
+
+```
+test/
+├── 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
+```
+
+## 页面对象模型（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()
+ }
+}
+```
+
+## 测试结构
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ItemsPage } from '../../pages/ItemsPage'
+
+test.describe('商品搜索', () => {
+ let itemsPage: ItemsPage
+
+ test.beforeEach(async ({ page }) => {
+ itemsPage = new ItemsPage(page)
+ await itemsPage.goto()
+ })
+
+ test('根据关键词搜索', async ({ page }) => {
+ await itemsPage.search('测试商品')
+
+ const count = await itemsPage.getItemCount()
+ expect(count).toBeGreaterThan(0)
+
+ await expect(itemsPage.itemCards.first()).toContainText(/测试/i)
+ await page.screenshot({ path: 'artifacts/search-results.png' })
+ })
+
+ test('搜索无结果时显示空状态', async ({ page }) => {
+ await itemsPage.search('xyznonexistent123')
+
+ await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+ expect(await itemsPage.getItemCount()).toBe(0)
+ })
+})
+```
+
+## Playwright 配置
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+ testDir: './test/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:5173',
+ 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: 'pnpm dev',
+ url: 'http://localhost:5173',
+ reuseExistingServer: !process.env.CI,
+ timeout: 120000,
+ },
+})
+```
+
+## 不稳定测试模式
+
+### 隔离
+
+```typescript
+test('不稳定测试：复杂搜索', async ({ page }) => {
+ test.fixme(true, '不稳定 - Issue #123')
+ // 测试代码...
+})
+
+test('条件跳过', async ({ page }) => {
+ test.skip(process.env.CI, 'CI 环境不稳定 - Issue #123')
+ // 测试代码...
+})
+```
+
+### 识别不稳定性
+
+```bash
+npx playwright test test/search.spec.ts --repeat-each=10
+npx playwright test test/search.spec.ts --retries=3
+```
+
+### 常见原因及修复
+
+**竞态条件：**
+```typescript
+// 错误：假设元素已就绪
+await page.click('[data-testid="button"]')
+
+// 正确：使用自动等待的定位器
+await page.locator('[data-testid="button"]').click()
+```
+
+**网络时序：**
+```typescript
+// 错误：任意等待
+await page.waitForTimeout(5000)
+
+// 正确：等待特定条件
+await page.waitForResponse(resp => resp.url().includes('/api/data'))
+```
+
+**动画时序：**
+```typescript
+// 错误：动画过程中点击
+await page.click('[data-testid="menu-item"]')
+
+// 正确：等待稳定后再点击
+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
+await page.waitForLoadState('networkidle')
+await page.locator('[data-testid="menu-item"]').click()
+```
+
+## 产物管理
+
+### 截图
+
+```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' })
+```
+
+### 追踪
+
+```typescript
+await browser.startTracing(page, {
+ path: 'artifacts/trace.json',
+ screenshots: true,
+ snapshots: true,
+})
+// ... 测试操作 ...
+await browser.stopTracing()
+```
+
+### 视频
+
+```typescript
+// 在 playwright.config.ts 中配置
+use: {
+ video: 'retain-on-failure',
+ videosPath: 'artifacts/videos/'
+}
+```
+
+## CI/CD 集成
+
+```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: pnpm 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
+```
+
+## 测试报告模板
+
+```markdown
+# E2E 测试报告
+
+**日期:** YYYY-MM-DD HH:MM
+**耗时:** X分Y秒
+**状态:** 通过 / 失败
+
+## 概要
+- 总计: X | 通过: Y (Z%) | 失败: A | 不稳定: B | 跳过: C
+
+## 失败测试
+
+### 测试名称
+**文件:** `test/e2e/feature.spec.ts:45`
+**错误:** 预期元素可见
+**截图:** artifacts/failed.png
+**推荐修复:** [描述]
+
+## 产物
+- HTML 报告: playwright-report/index.html
+- 截图: artifacts/*.png
+- 视频: artifacts/videos/*.webm
+- 追踪: artifacts/*.zip
+```
+
+## Web3/钱包测试
+
+```typescript
+test('钱包连接', async ({ page, context }) => {
+ // Mock 钱包 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')
+})
+```
+
+## 金融/关键流程测试
+
+```typescript
+test('交易执行', async ({ page }) => {
+ // 生产环境跳过 — 真实资金
+ test.skip(process.env.NODE_ENV === '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')
+
+ // 验证预览
+ const preview = page.locator('[data-testid="trade-preview"]')
+ await expect(preview).toContainText('1.0')
+
+ // 确认并等待区块链响应
+ 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