Test Driven Dev

OPC-Starter 测试驱动开发规范

快速命令

# 单元测试
cd app && npm run test

# E2E 全量
cd app && npm run test:e2e

# 认证专项（有浏览器窗口）
cd app && npm run test:e2e:auth

# 演示模式（打字机效果）
cd app && npm run test:e2e:demo

# UI 调试模式
cd app && npm run test:e2e:ui

# 查看报告
cd app && npm run test:e2e:report

---

核心原则

1. 新功能 → 先写测试 或功能完成后立即补充 2. 演示测试独立维护 → tests/e2e/demo/ 目录，带打字机效果 3. 可重复执行 → 注册测试用 Date.now() 生成唯一邮箱，beforeEach 清理状态 4. 测试状态更新 → 完成用例后更新 tests/TEST_PLAN.md

---

目录结构

app/tests/
├── e2e/
│   ├── auth/
│   │   ├── login.spec.ts       # 登录测试 (14 个)
│   │   └── register.spec.ts    # 注册测试 (17 个)
│   ├── demo/
│   │   └── demo-auth.spec.ts   # 演示测试 (5 个)
│   ├── dashboard.spec.ts       # fixme
│   ├── profile.spec.ts         # fixme
│   ├── persons.spec.ts         # fixme
│   └── settings.spec.ts        # fixme
└── support/
    ├── fixtures/auth.fixture.ts
    └── helpers/
        ├── test-helpers.ts
        └── demo-helpers.ts     # 打字机/高亮效果

---

新增功能测试 Checklist

新增页面

test('[P1] 应该能够访问页面', ...)        // 必须
test('[P1] 应该显示主要内容', ...)        // 必须
test('[P1] 核心交互测试', ...)            // 建议
test('[P2] 导航到其他页面', ...)          // 建议

新增表单

test('[P0] 成功提交', ...)                // 必须
test('[P1] 空字段被阻止', ...)            // 必须
test('[P1] 无效格式被阻止', ...)          // 必须
test('[P1] 显示错误提示', ...)            // 建议
// 同步在 demo/ 目录添加演示用例

新增演示用例模板

import { test, expect } from '@playwright/test';
import { fillFormWithEffect, clickWithEffect, highlightElement } from '../../support/helpers/demo-helpers';

test.use({ launchOptions: { slowMo: 50 }, video: 'on' });

test.describe('🎬 演示模式 - [功能名]', () => {
  test.beforeEach(async ({ page }) => {
    await page.context().clearCookies();
    await page.evaluate(() => { try { localStorage.clear(); } catch {} });
  });

  test('🎬 演示：[场景名]', async ({ page }) => {
    await page.goto('/path');
    await page.waitForLoadState('networkidle');
    
    await fillFormWithEffect(page, [
      { selector: '#field1', value: '值1' },
      { selector: '#field2', value: '值2' },
    ]);
    
    await highlightElement(page, 'button[type="submit"]', 500);
    await clickWithEffect(page, 'button[type="submit"]', { pause: 1000 });
  });
});

---

演示辅助函数速查

演示速度配置在 tests/support/helpers/demo-helpers.ts → DEMO_CONFIG

---

测试用例文件结构

// 1. 引入
import { test, expect } from '@playwright/test';

// 2. 测试数据
const TEST_USER = { email: 'test@example.com', password: '888888' };

// 3. 辅助函数
async function clearAuthState(page) { ... }

// 4. 测试套件 - 按优先级分组
test.describe('[P0] 核心流程', () => { ... });
test.describe('[P1] 验证逻辑', () => { ... });
test.describe('[P2] 用户体验', () => { ... });
test.describe('[P3] 边界情况', () => { ... });

---

运行器配置

Playwright 配置：app/playwright.config.ts 演示速度参数：tests/support/helpers/demo-helpers.ts 测试规划文档：tests/TEST_PLAN.md

详细说明见 references/testing-patterns.md

测试模式参考文档

1. 测试用例命名规范

[优先级] 描述

---

2. 测试套件分组模式

test.describe('[P0] 功能名 - 核心流程', () => {
  // P0 用例
});

test.describe('[P1] 功能名 - 表单验证', () => {
  // P1 用例
});

test.describe('[P1] 功能名 - 导航', () => {
  // 导航跳转相关
});

test.describe('[P2] 功能名 - 用户体验', () => {
  // P2 用例
});

test.describe('[P3] 功能名 - 边界情况', () => {
  // P3 用例
});

---

3. 状态清理模式

// beforeEach 标准清理（未导航时）
test.beforeEach(async ({ page }) => {
  await page.context().clearCookies();
  await page.evaluate(() => {
    try {
      localStorage.clear();
      sessionStorage.clear();
    } catch {
      // 忽略跨域错误
    }
  });
});

// 已有页面时的清理（先导航再清理）
test.beforeEach(async ({ page }) => {
  await page.goto('/login');
  await page.context().clearCookies();
  await page.evaluate(() => { try { localStorage.clear(); } catch {} });
});

---

4. 可重复执行保证

// 注册测试：使用唯一邮箱
const generateUniqueEmail = () => `test${Date.now()}@test.com`;

test('注册新用户', async ({ page }) => {
  const email = generateUniqueEmail(); // 每次不同
  await fillRegisterForm(page, '昵称', email, 'Password123', 'Password123');
  // ...
});

---

5. 等待策略

// 等待页面稳定
await page.waitForLoadState('networkidle');

// 等待元素可见
await expect(page.locator('#element')).toBeVisible({ timeout: 10000 });

// 等待 URL 变化
await expect(page).toHaveURL(/.*dashboard.*/, { timeout: 15000 });

// 等待文本出现
await expect(page.locator('text=成功')).toBeVisible({ timeout: 10000 });

---

6. fixme 模式

暂时无法运行的测试（如依赖测试用户）：

// 整组 fixme
test.describe.fixme('[P1] 需要真实用户', () => {
  // 激活条件：在 Supabase 创建 test@example.com
});

// 单个 fixme
test.fixme('[P0] 依赖真实登录', async ({ page }) => {
  // FIXME: 需要确认 test@example.com 用户存在
});

激活方式：移除 .fixme 即可启用。

---

7. 演示测试 vs 功能测试 区别

---

8. 测试规划文档维护

每次增加/完成测试后，更新 tests/TEST_PLAN.md 中的状态：