claude-code-hub/tests/DIAGNOSIS-FINAL.md

API 测试失败最终诊断报告

问题总结

经过深入调查，API 测试失败的根本原因是：生成的测试代码试图在 Vitest 单元测试环境中运行需要完整 Next.js 运行时环境的 Server Actions。

核心矛盾

测试代码的设计

// tests/api/users-actions.test.ts
const { response, data } = await callActionsRoute({
  method: 'POST',
  pathname: '/api/actions/users/addUser',
  authToken: ADMIN_TOKEN
});

这个测试通过 callActionsRoute 直接调用 Next.js 的 Server Actions 处理器，而不是启动真实服务器后通过 HTTP 请求测试。

问题所在

Server Actions 代码中广泛使用了 Next.js 特定 API：

1. cookies() from 'next/headers'

   • 需要 Next.js 请求上下文（requestAsyncStorage）
   • 测试环境无法提供该上下文

2. getTranslations() from 'next-intl/server'

   • 需要 Next.js 的 i18n 配置和运行时
   • 测试环境无国际化上下文

3. revalidatePath() from 'next/cache'

   • 需要 Next.js 的静态生成存储（staticGenerationStore）
   • 测试环境无缓存管理上下文

4. getLocale() from 'next-intl/server'

   • 需要国际化配置
   • 测试环境无 locale 上下文

尝试的修复方案及结果

方案 1：Mock Next.js API ❌ 失败

尝试：创建 tests/mocks/nextjs.ts Mock 所有 Next.js 特定函数

问题：

• Mock 定义不完整（缺少 getLocale、revalidatePath等）
• 即使定义了，Next.js 内部还会检查 AsyncLocalStorage 上下文
• Mock 越来越复杂，需要 Mock 大量内部实现

结论：治标不治本，维护成本高

根本解决方案

测试 /api/actions/* REST API 端点 的正确方式是：

方案 A：集成测试（推荐用于 API 端点测试）

方法：启动真实的 Next.js 开发服务器，通过 HTTP 请求测试

优点：

• ✅ 完全真实的环境
• ✅ 测试覆盖完整的请求链路（包括中间件、认证、响应格式等）
• ✅ 不需要 Mock 任何东西

实现：

// tests/api/integration/users-actions.test.ts
import { beforeAll, afterAll, describe, expect, test } from "vitest";

let serverProcess: ChildProcess;
const API_BASE_URL = "http://localhost:3000";

beforeAll(async () => {
  // 启动 Next.js 开发服务器
  serverProcess = spawn("npm", ["run", "dev"], {
    env: { ...process.env, PORT: "3000" }
  });

  // 等待服务器准备就绪
  await waitForServer(API_BASE_URL);
});

afterAll(() => {
  serverProcess.kill();
});

describe("User API Tests", () => {
  test("should create user", async () => {
    const response = await fetch(`${API_BASE_URL}/api/actions/users/addUser`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Cookie": `auth-token=${process.env.ADMIN_TOKEN}`
      },
      body: JSON.stringify({
        name: "Test User",
        rpm: 60,
        dailyQuota: 10
      })
    });

    const data = await response.json();
    expect(response.ok).toBe(true);
    expect(data.ok).toBe(true);
  });
});

方案 B：单元测试（推荐用于纯逻辑函数）

方法：只测试不依赖 Next.js 运行时的纯业务逻辑

适用范围：

• Repository 层函数（数据库查询）
• Utility 函数（工具函数）
• Service 层逻辑（业务逻辑）

示例：

// tests/unit/repository/users.test.ts
import { describe, expect, test } from "vitest";
import { findUserById, createUser } from "@/repository/user";

describe("User Repository", () => {
  test("should find user by ID", async () => {
    const user = await findUserById(1);
    expect(user).toBeDefined();
    expect(user?.id).toBe(1);
  });
});

当前测试的处理建议

短期（立即）：

删除或跳过当前失败的 API 测试

// tests/api/users-actions.test.ts
describe.skip("用户管理 - API测试（待重构为集成测试）", () => {
  // ... 所有测试
});

原因：

• 当前测试设计不可行
• Mock 方案维护成本太高
• 不应阻塞项目进度

中期（1-2周）：

编写集成测试替代

1. 创建 tests/api/integration/ 目录
2. 使用方案 A 编写集成测试
3. 在 CI/CD 中配置测试环境（启动服务器）

长期（重构）：

优化代码架构

1. 将 Next.js 特定 API 调用封装到服务层
2. 通过依赖注入提供 Mock 接口
3. 使 Server Actions 更易于测试

示例重构：

// Before: 直接调用 Next.js API
export async function addUser(data: CreateUserData) {
  const session = await getSession(); // Next.js specific
  const t = await getTranslations(); // Next.js specific

  // ... business logic

  revalidatePath("/dashboard"); // Next.js specific
}

// After: 依赖注入
export async function addUser(
  data: CreateUserData,
  context: ActionContext // 包含 session, translator, cache
) {
  const { session, t, cache } = context;

  // ... business logic

  cache.revalidate("/dashboard");
}

测试策略建议

优先级 1：单元测试（快速、稳定）

• ✅ Repository 层（数据库操作）
• ✅ Utility 函数（纯函数）
• ✅ Service 逻辑（业务规则）

优先级 2：集成测试（全面、真实）

• ✅ REST API 端点（/api/actions/*）
• ✅ 认证流程
• ✅ 权限控制

优先级 3：E2E 测试（可选）

• 🔲 完整用户流程
• 🔲 UI 交互

技术债务记录

1. 过度依赖 Next.js 特定 API

   • 影响：测试困难、架构耦合
   • 解决：封装 + 依赖注入

2. 缺少集成测试基础设施

   • 影响：无法测试 API 端点
   • 解决：配置测试服务器启动脚本

3. 测试文档缺失

   • 影响：团队不清楚如何编写测试
   • 解决：编写测试指南文档

推荐行动计划

立即执行（今天）：

1. ✅ 跳过当前失败的 API 测试（describe.skip）
2. ✅ 删除不可行的 Mock 文件（tests/mocks/nextjs.ts）
3. ✅ 创建本诊断文档归档

本周执行：

1. 🔲 编写单元测试示例（Repository 层）
2. 🔲 设计集成测试架构（服务器启动方案）

下周执行：

1. 🔲 实现集成测试框架
2. 🔲 重写 API 测试为集成测试
3. 🔲 编写测试指南文档

---

结论：当前的测试失败不是 Bug，而是测试设计与技术架构不匹配导致的。建议采用集成测试方案重写 API 测试。

状态：已诊断 ✅ 下一步：跳过当前测试 + 规划集成测试框架