Jest 测试中 spyOn 被重复调用导致后续测试失败的解决方案

当在 jest 中对模块方法（如 `sequelize.query`）使用 `spyon` 时，若未彻底隔离模块状态，后续测试可能继承前序测试的 mock 状态，导致 `tohavebeencalledtimes(1)` 断言失败。根本解法是全局 mock 整个模块，确保每个测试拥有干净、独立的模拟环境。

在 Jest 单元测试中，spyOn 是一种轻量级的模拟方式，适用于临时拦截并验证方法调用行为。但它的局限性在于：它不重置模块本身的内部状态或已注册的 mock 实现，尤其当被 spy 的方法在测试之外（例如应用启动、中间件初始化、或 Sequelize 连接池建立过程中）被意外调用时，jest.spyOn().mockResolvedValueOnce() 的“调用计数”会因额外调用而失准——这正是你遇到“第二个测试总是失败（expect(query).toHaveBeenCalledTimes(1) 报告为 2）”的根本原因。

虽然你已在 afterEach 中调用了 jest.clearAllMocks() 和 jest.restoreAllMocks()，并配置了 clearMocks: true、restoreMocks: true 等选项，但这些机制无法清除模块顶层代码执行时触发的原始调用。例如，若 ../../sequelize 模块在 require("../../server") 时主动调用了 sequelize.query()（如执行迁移检查、健康检查 SQL 或默认初始化查询），该调用会在每个测试前的模块加载阶段发生——而 spyOn 会捕获它，使 mockResolvedValueOnce 的“一次”预期被提前消耗。

✅ 正确做法：在测试文件顶部使用 jest.mock() 全局模拟整个模块，从而完全接管其导出对象，避免任何真实调用泄漏：

const request = require("supertest");
const app = require("../../server");
// ⚠️ 关键：在引入 sequelize 前 mock，确保所有 require 都拿到模拟实例
jest.mock("../../sequelize"); 

const { sequelize } = require("../../sequelize"); // 此时 sequelize 是 mock 对象

describe("API routes tests", () => {
  afterEach(() => {
    jest.clearAllMocks(); // 仍建议保留，清理 mock 实现
  });

  describe("GET /api/user-activity-logs", () => {
    it("Test 1", async () => {
      const mockedResponse = [{ log: 1 }, { log: 2 }];
      // 直接 mock query 方法的行为（无需 spy）
      sequelize.query.mockResolvedValueOnce(mockedResponse);

      const response = await request(app)
        .get("/api/user-activity-logs")
        .query(defaultQueryParams);

      expect(sequelize.query).toHaveBeenCalledTimes(1);
      expect(response.status).toBe(200);
      expect(r
esponse.body).toHaveProperty("groupedLogs", mockedResponse);
    });

    it("Test 2", async () => {
      const mockedResponse = [{ log: 3 }, { log: 4 }];
      sequelize.query.mockResolvedValueOnce(mockedResponse); // 完全独立，无状态污染

      const response = await request(app)
        .get("/api/user-activity-logs")
        .query(defaultQueryParams);

      expect(sequelize.query).toHaveBeenCalledTimes(1); // ✅ 稳定通过
      expect(response.status).toBe(200);
      expect(response.body).toHaveProperty("groupedLogs", mockedResponse);
    });
  });
});

? 关键注意事项：

• jest.mock() 必须置于 require("../../sequelize") 之前，且为 top-level 调用（不能在 describe 或 it 内），否则 mock 不生效；
• 使用 mockResolvedValueOnce 时，确保每次测试都显式设置期望返回值，避免跨测试残留；
• 若需更精细控制（如部分方法真实执行、部分 mock），可结合 jest.requireActual() 构建混合 mock，但本场景推荐全模块 mock 以保障隔离性；
• 移除 jest.spyOn() + mockClear() 的冗余逻辑，改用直接调用 mockResolvedValueOnce 更简洁可靠。

总结：spyOn 适合“观察+轻量干预”，而模块级 jest.mock() 才是实现测试间强隔离的黄金标准。当你发现 mock 行为跨测试“污染”时，优先检查是否遗漏了全局模块 mock。