Vitest中用jest-dom扩展匹配器时，expect.extend报TypeError错误

问题根源 #

你遇到的错误和编辑器提示问题，核心原因是**@testing-library/jest-dom v6+版本变更了导出方式**，而你参考的旧文章使用的是v5及以下版本的默认导入语法，导致导入的matchers为undefined，进而触发TypeError: Cannot convert undefined or null to object。

解决方案 #

1. 修正导入语法 #

将setup文件中的默认导入改为命名导入：

// 你的setup文件（比如src/test/setup.ts）
import * as matchers from '@testing-library/jest-dom/matchers'
import { expect } from 'vitest'

expect.extend(matchers)

2. 确保Vitest正确加载setup文件 #

在vite.config.ts中配置setup文件路径，并启用DOM测试环境（jest-dom依赖DOM环境）：

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['./src/test/setup.ts'], // 替换为你的setup文件实际路径
    environment: 'jsdom',
    globals: true // 可选，若想全局使用expect等测试API可开启
  },
})

3. 修复编辑器类型提示错误 #

在tsconfig.json中添加相关类型声明，让编辑器识别jest-dom的匹配器：

{
  "compilerOptions": {
    "types": ["vitest", "@testing-library/jest-dom"]
  }
}

额外说明 #

如果坚持使用@testing-library/jest-dom v5版本，默认导入语法是有效的，但v6版本做了导出重构，推荐升级到最新版本并使用上述命名导入方式，以获得更好的兼容性和类型支持。

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