Vitest搭配@testing-library/jest-dom时toBeInTheDocument匹配器类型错误

核心问题分析 #

TypeScript无法识别toBeInTheDocument匹配器，本质是Vitest的类型系统未正确继承@testing-library/jest-dom提供的匹配器类型——测试运行时逻辑正常，但类型检查阶段的关联未打通。

针对性解决方法 #

1. 修正全局类型扩展文件 #

你当前的types.d.ts写法存在偏差，Vitest需要通过扩展Assertion接口来整合第三方匹配器类型，修改文件内容如下：

/// <reference types="vitest" />
import type '@testing-library/jest-dom';

declare module 'vitest' {
  interface Assertion<T = any> extends jest.Matchers<void, T> {}
}

2. 确保TypeScript正确识别类型文件 #

如果types.d.ts不在TS默认扫描路径中，需在tsconfig.json中补充include配置，同时优化types字段：

{
  "compilerOptions": {
    "types": ["vitest/globals", "@testing-library/jest-dom"]
  },
  "include": ["src/**/*", "types.d.ts", "vitest.setup.ts"]
}

注：使用vitest/globals替代vitest，更贴合你开启globals: true的配置逻辑。

3. 检查依赖版本兼容性 #

确保@testing-library/jest-dom版本与Vitest、TypeScript兼容，推荐安装最新稳定版：

npm install --save-dev @testing-library/jest-dom@latest

Vitest v1.x+要求@testing-library/jest-dom至少为v5.16+版本，否则易出现类型不兼容问题。

4. 强制重启TypeScript服务器 #

修改配置后，必须重启编辑器的TypeScript服务器（VSCode可按Ctrl+Shift+P，输入TypeScript: Restart TS Server），确保新配置完全生效。

验证操作 #

执行类型检查命令确认问题解决：

npx tsc --noEmit

若无报错，则类型配置已正常生效。

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