如何全局引入@testing-library/jest-dom 解决setupTest.js配置不生效问题

复制了CRA里的setupTests.js却不生效，根本原因是非CRA创建的项目，不会自动将setup文件纳入测试框架的自动加载流程——你写的文件根本没被执行，自然没法扩展全局expect的能力。
CRA能开箱即用，本质是它在内部预配置了测试框架的加载规则，把src/setupTests.js挂载到了测试流程的指定执行节点，用户只要往这个文件里写导入语句就能生效。

生效的核心前提 #

要实现所有测试文件免单独导入、直接使用jest-dom的匹配器，需要满足两个要求：

• 测试框架会在每个测试文件执行前，自动加载你指定的setup文件
• 加载setup文件的时序，必须在测试框架全局expect对象初始化完成之后，否则扩展逻辑无法正确挂载

分场景配置步骤 #

场景：Jest作为测试框架 #

• 先找到项目里的Jest配置入口，常见位置是jest.config.js、jest.config.ts，或是package.json内的jest配置字段
• 配置核心项setupFilesAfterEnv：注意不要和setupFiles混淆——setupFiles是在Jest测试环境初始化前加载，此时全局expect还未生成，加载jest-dom完全无效；setupFilesAfterEnv是在Jest核心API（包括全局expect）初始化完成后加载，是正确的加载时序
• 配置示例：

// jest.config.js
module.exports = {
  // 保留项目原有所有配置...
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts']
}

• 在配置指向的setup文件内写入导入语句即可，不需要在每个.spec.ts里重复导入：

// src/setupTests.ts
import '@testing-library/jest-dom';

场景：Vitest作为测试框架 #

Vitest的全局加载逻辑和Jest一致，仅配置写法不同：

• 打开vitest.config.ts，在test配置块下添加setupFiles项，指向你的setup文件
• 配置示例：

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    // 保留项目原有测试配置...
    setupFiles: ['./src/setupTests.ts']
  }
})

• 和Jest场景逻辑一致，setup文件内导入@testing-library/jest-dom即可全局生效

高频不生效问题排查 #

• 路径不匹配：配置中填写的setup文件路径和实际文件的存放位置不一致，测试框架找不到目标文件
• 时序配错：把setup文件挂到了Jest的setupFiles而非setupFilesAfterEnv下，导致扩展逻辑加载太早，无法挂载到全局expect
• 版本不兼容：@testing-library/jest-dom的版本和测试框架版本不匹配，例如Jest 27及以上版本需要搭配@testing-library/jest-dom@5.x及以上版本
• TS类型识别问题：如果TypeScript提示toBeInTheDocument等匹配器不存在，只要setup文件被正确加载，对应类型会自动注入；若仍报错，可在tsconfig.json的types字段中显式添加@testing-library/jest-dom

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