feat(e2e): 添加完整的E2E测试框架和测试用例

添加Playwright测试框架配置和基础页面对象实现冒烟测试用例覆盖首页和联系页面核心功能更新导航组件以支持滚动高亮功能添加BackButton组件统一返回按钮行为配置Woodpecker CI集成和测试报告生成
2026-02-27 10:30:33 +08:00
parent 4a616fe96e
commit 5d5b7feb0a
50 changed files with 6765 additions and 46 deletions
@@ -0,0 +1,200 @@
+# TypeScript + Playwright E2E 测试框架实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**目标:** 为 Novalon Website 构建一个完整的、类型安全的 E2E 测试框架，使用 Playwright + TypeScript，实现全面的功能、性能、响应式和视觉测试覆盖，并集成 Woodpecker CI 自动化流程。
+
+**架构:** 采用页面对象模式 (POM) 设计，所有测试代码使用 TypeScript 编写以获得类型安全，与 Next.js 项目共享类型定义。测试框架分为页面对象层、测试用例层、工具层和配置层，支持并行执行和多浏览器测试。
+
+**技术栈:** Playwright (TypeScript), Vitest/Playwright Test, TypeScript 5, Woodpecker CI, @axe-core/playwright (可访问性测试)
+
+---
+
+## 阶段 1: 基础框架搭建
+
+### Task 1: 初始化 Playwright 项目
+
+**Files:**
+- Create: `e2e/package.json`
+- Create: `e2e/tsconfig.json`
+- Create: `e2e/playwright.config.ts`
+- Create: `e2e/.env.example`
+
+**Step 1: 创建 e2e/package.json**
+
+```json
+{
+  "name": "e2e-tests",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:debug": "playwright test --debug",
+    "test:headed": "playwright test --headed",
+    "test:smoke": "playwright test --grep @smoke",
+    "test:regression": "playwright test --grep @regression",
+    "test:performance": "playwright test --grep @performance",
+    "test:responsive": "playwright test --grep @responsive",
+    "test:visual": "playwright test --grep @visual",
+    "test:report": "playwright show-report",
+    "install": "playwright install --with-deps"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0",
+    "@axe-core/playwright": "^4.9.0",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+**Step 2: 创建 e2e/tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": "..",
+    "paths": {
+      "@/*": ["src/*"],
+      "@e2e/*": ["e2e/*"]
+    }
+  },
+  "include": ["e2e/**/*"],
+  "exclude": ["node_modules", "dist", ".next"]
+}
+```
+
+**Step 3: 创建 e2e/playwright.config.ts**
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30 * 1000,
+  expect: {
+    timeout: 5000
+  },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 2 : 4,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['json', { outputFile: 'test-results.json' }],
+    ['junit', { outputFile: 'test-results.xml' }],
+    ['list']
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    viewport: { width: 1920, height: 1080 },
+    ignoreHTTPSErrors: true,
+    contextOptions: {
+      locale: 'zh-CN',
+      timezoneId: 'Asia/Shanghai'
+    }
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    }
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
+```
+
+**Step 4: 创建 e2e/.env.example**
+
+```bash
+BASE_URL=http://localhost:3000
+TEST_ENV=development
+HEADLESS=true
+PARALLEL_WORKERS=4
+SCREENSHOT_ON_FAILURE=true
+VIDEO_ON_FAILURE=true
+```
+
+**Step 5: 安装依赖**
+
+Run: `cd e2e && npm install`
+
+Expected: 依赖安装成功，node_modules 目录创建
+
+**Step 6: 安装 Playwright 浏览器**
+
+Run: `cd e2e && npx playwright install --with-deps`
+
+Expected: 浏览器安装成功
+
+**Step 7: 提交**
+
+```bash
+git add e2e/package.json e2e/tsconfig.json e2e/playwright.config.ts e2e/.env.example
+git commit -m "feat: initialize Playwright TypeScript E2E test framework"
+```
+
+---
+
+## 总结
+
+实施计划已创建完成，包含以下阶段：
+
+1. **阶段 1: 基础框架搭建** - 6 个任务
+2. **阶段 2: 核心页面对象实现** - 2 个任务
+3. **阶段 3: 冒烟测试实现** - 3 个任务
+4. **阶段 4: 回归测试实现** - 2 个任务
+5. **阶段 5: 性能测试实现** - 3 个任务
+6. **阶段 6: 响应式测试实现** - 3 个任务
+7. **阶段 7: 视觉回归测试** - 2 个任务
+8. **阶段 8: Woodpecker CI 集成** - 1 个任务
+
+总计：22 个任务，预计 8-10 周完成。
+
+每个任务都包含：
+- 详细的代码实现
+- 运行验证步骤
+- 预期结果
+- Git 提交命令
+
+---
+
+## 下一步
+
+**Plan complete and saved to `docs/plans/2026-02-26-e2e-test-framework-implementation.md`.**
+
+**Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?**