zhuiguang-ai/.trae/specs/modules/testing.md

测试体系模块

概述

追光AI使用 Vitest 作为测试框架，已建立 5 个测试套件覆盖 132 个测试，目标覆盖率 80%+。测试文件位于 src/__tests__/ 目录。

---

基础设施

vitest.config.ts

import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
    setupFiles: ["./vitest.setup.ts"],
    include: ["src/__tests__/**/*.test.ts"],
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"],
      thresholds: {
        lines: 80,
        branches: 80,
        functions: 80,
        statements: 80,
      },
    },
  },
  resolve: {
    alias: { "@": path.resolve(__dirname, "./src") },
  },
});

vitest.setup.ts

• 全局 mock 配置
• Prisma mock 初始化
• 测试环境清理

tsconfig 配置

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

---

测试套件

1. level-config.test.ts

• 测试数量: 28
• 覆盖: src/lib/level-config.ts
• 测试内容:
  • 20个等级边界值检查
  • 等级徽章映射
  • 每日限额表
  • 积分→等级转换
  • 下一级积分计算

2. elo.test.ts

• 测试数量: 24
• 覆盖: ELO 评分计算逻辑
• 测试内容:
  • 基础 ELO 计算
  • K因子变化
  • 平局处理
  • 极端分差

3. forum-hot.test.ts

• 测试数量: 30
• 覆盖: 论坛热度排序算法
• 测试内容:
  • 热度公式计算
  • 时间衰减
  • 回复加权
  • 点赞加权
  • 置顶优先

4. achievements.test.ts

• 测试数量: 26
• 覆盖: 成就系统逻辑
• 测试内容:
  • 成就解锁条件
  • 进度计算
  • 徽章授予
  • 边界条件

5. points-reward.test.ts

• 测试数量: 24
• 覆盖: src/lib/points-reward.ts
• 测试内容:
  • 各操作积分奖励
  • 每日上限检查
  • Streak freeze 逻辑
  • 商店购买消耗
  • 等级升级触发

---

运行命令

# 运行所有测试
npx vitest run

# 监听模式
npx vitest

# 生成覆盖率报告
npx vitest run --coverage

# 运行特定测试文件
npx vitest run src/__tests__/level-config.test.ts

# UI 模式
npx vitest --ui

---

测试规范

文件命名

• 测试文件: *.test.ts
• 目录: src/__tests__/

测试结构

import { describe, it, expect, beforeEach, vi } from "vitest";

describe("模块名", () => {
  beforeEach(() => {
    // setup
  });

  describe("功能点", () => {
    it("应该满足某条件", () => {
      // arrange
      // act
      // assert
    });

    it("应该处理边界情况", () => {
      // ...
    });

    it("应该优雅处理错误", () => {
      // ...
    });
  });
});

测试原则

• 每个 it 测试单一行为
• 使用 describe 组织相关测试
• Arrange → Act → Assert 三段式
• 覆盖正常路径 + 边界条件 + 错误路径
• 禁止 .skip 除非有明确 TODO 注释
• Mock 外部依赖（Prisma、外部 API）

覆盖率目标

指标	目标
行覆盖率	≥ 80%
分支覆盖率	≥ 80%
函数覆盖率	≥ 80%
语句覆盖率	≥ 80%