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

{
  "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

{
  "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

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

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: 提交

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?