运行Jest测试时遭遇语法错误与环境销毁后导入问题

问题现象 #

运行test/api/agents/index.test.ts时出现两个核心报错：

• SyntaxError: Unexpected token ':'：报错触发于Runtime.loadEsmModule，属于ESM模块加载格式冲突
• ReferenceError: 尝试在Jest环境销毁后导入文件：测试结束后仍有异步操作或模块加载未完成

解决方案 #

1. 重构Jest配置，消除ESM加载冲突 #

next-jest已内置Next.js项目的TS/ESM支持，手动配置ts-jest会引发格式解析冲突。修改jest.config.ts如下：

import type { Config } from "jest";
import nextJest from "next/jest";

const createJestConfig = nextJest({
  dir: "./",
});

const config: Config = {
  verbose: true,
  coverageProvider: "v8",
  testEnvironment: "node",
  moduleDirectories: ["node_modules", "<rootDir>"],
  testPathIgnorePatterns: ["/node_modules/", "/.next/", "/packages/"],
  fakeTimers: {
    enableGlobally: true,
  },
  moduleNameMapper: {
    "^@app/(.*)$": "<rootDir>/$1",
  },
  // 仅忽略emailer包的转换，其他node_modules包默认处理
  transformIgnorePatterns: ["/node_modules/(?!emailer)/"],
};

export default createJestConfig(config);

关键调整说明：

• 移除preset: "ts-jest"、transform、extensionsToTreatAsEsm配置，避免与next-jest的内置处理逻辑冲突
• 修正transformIgnorePatterns的写法，确保仅跳过特定第三方包的转换

2. 修复测试代码的异步与断言问题 #

环境销毁报错通常源于未正确等待异步操作、断言语法错误或mock数据不完整。修改测试代码如下：

import { NextApiResponse } from "next";
import { createMocks } from "node-mocks-http";
import { AppNextApiRequest } from "@app/types";
import { getAgents } from "@app/pages/api/agents";
import { respond } from "@app/utils/createa-api-handler";
import { expect, describe, it, jest } from "@jest/globals";

// 填充有效的session mock数据，避免业务逻辑报错
const session = {
  user: { id: "test-user-123" },
  // 根据业务需求补充其他必要字段
};

describe("/api/agents", () => {
  it("should get the list of agents.", async () => {
    const { req, res } = createMocks<AppNextApiRequest, NextApiResponse>({
      session,
      method: "GET",
      headers: {
        "Content-Type": "application/json",
      },
    });

    // 确保异步请求完全执行完成
    await respond(getAgents)(req, res);

    // 注意：_getStatusCode是方法，必须调用才能获取状态码
    expect(res._getStatusCode()).toBe(200);
  }, 6000);
});

关键调整说明：

• 补充完整的session mock数据，避免getAgents内部因依赖缺失抛出未处理错误
• 修正断言语法：res._getStatusCode是方法，需调用()才能获取值
• 确保respond返回的Promise被完整等待，避免测试提前结束

3. 额外检查项 #

• 确认@app/utils/createa-api-handler的拼写是否正确（疑似create-api-handler的笔误），避免模块导入失败
• 确保依赖版本匹配：next-jest版本需与Next.js主版本一致，jest与相关插件版本兼容

内容的提问来源于stack exchange，提问作者Muhammad Faizan