file-starter/docs/architecture/testing-strategy.md

测试策略

版本信息

版本	日期	描述	作者
2.6	2025-10-15	完成遗留测试文件迁移到统一的tests目录结构	Winston
2.5	2025-10-14	更新测试文件位置到统一的tests目录结构	Claude
2.4	2025-09-20	更新测试策略与主架构文档版本一致	Winston

概述

本文档定义了D8D Starter项目的完整测试策略，基于现有的测试基础设施和最佳实践。测试策略遵循测试金字塔模型，确保代码质量、功能稳定性和系统可靠性。

测试金字塔策略

单元测试 (Unit Tests)

• 范围: 单个函数、类或组件
• 目标: 验证独立单元的correctness
• 位置: tests/unit/**/*.test.{ts,tsx}
• 框架: Vitest
• 覆盖率目标: ≥ 80%
• 执行频率: 每次代码变更

集成测试 (Integration Tests)

• 范围: 多个组件/服务协作
• 目标: 验证模块间集成和交互
• 位置: tests/integration/**/*.test.{ts,tsx}
• 框架: Vitest + Testing Library + hono/testing
• 覆盖率目标: ≥ 60%
• 执行频率: 每次API变更

E2E测试 (End-to-End Tests)

• 范围: 完整用户流程
• 目标: 验证端到端业务流程
• 位置: tests/e2e/**/*.test.{ts,tsx}
• 框架: Playwright
• 覆盖率目标: 关键用户流程100%
• 执行频率: 每日或每次重大变更

测试环境配置

开发环境

// vitest.config.ts - 开发环境配置
export default defineConfig({
  test: {
    projects: [
      // Node.js 环境项目 - 后端测试
      {
        test: {
          include: [
            'tests/unit/server/**/*.test.{ts,js}',
            'tests/integration/server/**/*.test.{ts,js}'
          ],
          // ... 其他配置
        }
      },
      // Happy DOM 环境项目 - 前端组件测试
      {
        test: {
          include: [
            'tests/unit/client/**/*.test.{ts,js,tsx,jsx}',
            'tests/integration/client/**/*.test.{ts,js,tsx,jsx}'
          ],
          // ... 其他配置
        }
      }
    ]
  }
});

CI/CD环境

# GitHub Actions 测试配置
name: Test Pipeline

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:api
      - run: npm run test:components

  integration-tests:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
    steps:
      - run: npm run test:integration

  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:e2e:chromium

测试覆盖率标准

各层覆盖率要求

测试类型	最低要求	目标要求	关键模块要求
单元测试	70%	80%	90%
集成测试	50%	60%	70%
E2E测试	关键流程100%	主要流程80%	-

关键模块定义

• 认证授权模块: 必须达到90%单元测试覆盖率
• 数据库操作模块: 必须达到85%单元测试覆盖率
• 核心业务逻辑: 必须达到80%集成测试覆盖率
• 用户管理功能: 必须100% E2E测试覆盖

测试数据管理

测试数据策略

// 测试数据工厂模式
export function createTestUser(overrides = {}): User {
  return {
    id: 1,
    username: 'testuser',
    email: 'test@example.com',
    createdAt: new Date(),
    ...overrides
  };
}

// 使用示例
const adminUser = createTestUser({ role: 'admin' });
const inactiveUser = createTestUser({ active: false });

数据库测试策略

• 单元测试: 使用内存数据库或完全mock
• 集成测试: 使用专用测试数据库，事务回滚
• E2E测试: 使用接近生产环境的数据库

数据清理策略

1. 事务回滚 (推荐)
2. 数据库清理 (每个测试后)
3. 测试数据隔离 (使用唯一标识符)

测试执行流程

本地开发测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行E2E测试
npm run test:e2e:chromium

# 生成覆盖率报告
npm run test:coverage

CI/CD流水线测试

1. 代码推送 → 触发测试流水线
2. 单元测试 → 快速反馈，必须通过
3. 集成测试 → 验证模块集成，必须通过
4. E2E测试 → 验证完整流程，建议通过
5. 覆盖率检查 → 满足最低要求
6. 测试报告 → 生成详细报告

质量门禁

测试通过标准

• ✅ 所有单元测试通过
• ✅ 所有集成测试通过
• ✅ 关键E2E测试通过
• ✅ 覆盖率满足最低要求
• ✅ 无性能回归
• ✅ 安全测试通过

失败处理流程

1. 测试失败 → 立即通知开发团队
2. 分析根本原因 → 确定是测试问题还是代码问题
3. 优先修复 → 阻塞性问题必须立即修复
4. 重新测试 → 修复后重新运行测试
5. 文档更新 → 更新测试策略和案例

安全测试策略

安全测试要求

• 输入验证测试: 所有API端点必须测试SQL注入、XSS等攻击
• 认证测试: 测试令牌验证、权限控制
• 数据保护: 测试敏感数据泄露风险
• 错误处理: 测试错误信息是否泄露敏感数据

安全测试工具

• OWASP ZAP: 自动化安全扫描
• npm audit: 依赖漏洞检查
• 自定义安全测试: 针对业务逻辑的安全测试

性能测试策略

性能测试要求

• API响应时间: < 100ms (p95)
• 数据库查询性能: < 50ms (p95)
• 并发用户数: 支持100+并发用户
• 资源使用: CPU < 70%, 内存 < 80%

性能测试工具

• k6: 负载测试
• autocannon: API性能测试
• Playwright: E2E性能监控

测试文档标准

测试代码规范

// 良好的测试示例
describe('UserService', () => {
  describe('createUser()', () => {
    it('应该创建新用户并返回用户对象', async () => {
      // Arrange
      const userData = { username: 'testuser', email: 'test@example.com' };

      // Act
      const result = await userService.createUser(userData);

      // Assert
      expect(result).toHaveProperty('id');
      expect(result.username).toBe('testuser');
      expect(result.email).toBe('test@example.com');
    });

    it('应该拒绝重复的用户名', async () => {
      // Arrange
      const existingUser = await createTestUser({ username: 'existing' });

      // Act & Assert
      await expect(
        userService.createUser({ username: 'existing', email: 'new@example.com' })
      ).rejects.toThrow('用户名已存在');
    });
  });
});

测试命名约定

• 文件名: [module].test.ts 或 [module].integration.test.ts
• 描述: 使用「应该...」格式描述测试行为
• 用例: 明确描述测试场景和预期结果

监控和报告

测试监控指标

• 测试通过率: > 95%
• 测试执行时间: < 10分钟（单元+集成）
• 测试稳定性: 无flaky tests
• 覆盖率趋势: 持续改进或保持

测试报告要求

• HTML报告: 详细的覆盖率报告
• JUnit报告: CI/CD集成
• 自定义报告: 业务指标测试报告
• 历史趋势: 测试质量趋势分析

附录

相关文档

• 集成测试最佳实践
• 编码标准
• API设计规范

工具版本

• Vitest: 3.2.4
• Testing Library: 16.3.0
• Playwright: 1.55.0
• hono/testing: 内置（Hono 4.8.5）

更新日志

日期	版本	描述
2025-10-15	2.6	完成遗留测试文件迁移到统一的tests目录结构
2025-10-14	2.5	重构测试文件结构，统一到tests目录
2025-09-20	2.4	更新版本与主架构文档一致
2025-09-19	1.0	初始版本，基于现有测试基础设施

---

文档状态: 正式版 下次评审: 2025-12-19