配置Jest与jest-dom时遇TypeError: $toString is not a function

我在为TypeScript/React/Next.js网站配置Jest和@testing-library/jest-dom时，每次运行测试都会报错，已尝试重建项目、重装依赖、调整多种配置，耗时3天仍未解决。

错误信息 #

FAIL  __tests__/dist/button.test.js
  ● Test suite failed to run

    TypeError: $toString is not a function

    > 1 | import '@testing-library/jest-dom'
        | ^

      at isArguments (node_modules/is-arguments/index.js:12:9)
      at node_modules/is-arguments/index.js:28:9
      at Object.<anonymous> (node_modules/is-arguments/index.js:29:2)
      at Object.<anonymous> (node_modules/deep-equal/index.js:10:19)
      at Object.<anonymous> (node_modules/aria-query/lib/elementRoleMap.js:7:41)
      at Object.<anonymous> (node_modules/aria-query/lib/index.js:10:46)
      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/to-be-checked.js:8:18)
      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/matchers.js:203:20)
      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/extend-expect.js:3:42)
      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/index.js:3:1)
      at Object.<anonymous> (jest-setup.ts:1:1)

现有配置文件 #

tsconfig.json #

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "baseUrl": ".",
    "noFallthroughCasesInSwitch": true,
    "outDir": "./dist",
    "paths": {
      "@/*": ["./*"]
    },
  },
   "compileOnSave": true,
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "babel.config.js", "jest-setup.ts", "jest.config.ts"],
  "exclude": ["node_modules"]
}

jest.config.ts #

import type { Config } from "@jest/types";

const config: Config.InitialOptions = {
  preset: "ts-jest",
  testEnvironment: "node",
  extensionsToTreatAsEsm: ['.ts'],
  verbose: true,
  automock: true,
  transformIgnorePatterns: ['node_modules/', '^.+\\.module\\.(css|sass|scss)$'],
  moduleFileExtensions: ["js", "jsx", "ts", "tsx"],
  moduleDirectories: ["node_modules", "src"],
  moduleNameMapper: {
    "\\.(css|less|scss)$": "identity-obj-proxy"
  },
  transform: {
    '^.+\\.(ts|tsx)?$': 'ts-jest',
    '^.+\\.(js|jsx)$': 'babel-jest',
    
  },
  setupFilesAfterEnv: ['<rootDir>/jest-setup.ts'],
}

export default config;

jest-setup.ts #

import '@testing-library/jest-dom'

babel.config.js #

module.exports = {
  presets: [['@babel/preset-env', {targets: {node: 'current'}}]],
};

解决方法 #

1. 修正测试环境：将jest.config.ts中的testEnvironment从node改为jsdom——React组件测试需要浏览器DOM环境支持，node环境无法满足@testing-library/jest-dom的依赖需求。

2. 禁用自动Mock：关闭automock: true，改为automock: false。自动Mock会错误拦截@testing-library/jest-dom依赖的底层模块（如aria-query），导致函数调用异常。

3. 调整TypeScript编译配置：移除tsconfig.json中的noEmit: true，或创建单独的tsconfig.test.json并设置noEmit: false，同时在jest.config.ts中添加tsconfig: './tsconfig.test.json'。ts-jest需要编译输出才能正常处理测试文件。

4. 对齐依赖版本：确保Jest、ts-jest、@testing-library/jest-dom的版本与Next.js兼容。执行以下命令重装兼容版本：

npm uninstall jest ts-jest @testing-library/jest-dom
npm install --save-dev jest@29 ts-jest@29 @testing-library/jest-dom@6 @types/jest

5. 简化Transform配置：ts-jest可处理所有JS/TS文件，无需单独配置babel-jest。修改transform部分为：

transform: {
  '^.+\\.(ts|tsx|js|jsx)$': 'ts-jest',
},

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