novalon-website/docs/plans/2026-02-26-e2e-test-framework-implementation.md

# 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?**