TypeScript cannot find toBeInTheDocument on expect()
Property 'toBeInTheDocument' does not exist on type 'Matchers<any>'Short answer
The jest-dom matchers and their types only exist after the package is imported once in a test setup file. That file must be registered in the Jest or Vitest config and be visible to tsconfig.json. Vitest needs the /vitest import, and Jest with injectGlobals off needs /jest-globals.
Fix it fast
1Find out which cause you have
Check that jest-dom is installed and find out whether any file imports it. If no file does, the matchers and types are never loaded.
npm ls @testing-library/jest-dom grep -rn "@testing-library/jest-dom" --include=*.ts --include=*.js --include=*.json --include=*.mjs . --exclude-dir=node_modules2Match what you see, then jump to its fix
- 1
The editor shows the error and no file in the project imports jest-domThe setup file is missing, or not registered with the test runnerFix - 2
Vitest project; the setup file imports '@testing-library/jest-dom' without a suffixVitest needs the /vitest entry pointFix - 3
Tests pass, but the editor and tsc still show the errortsconfig.json does not include the setup fileFix - 4
Tests import expect and test from '@jest/globals'Jest runs with injectGlobals turned offFix
- 1
What does the error look like?
Property 'toBeInTheDocument' does not exist on type 'Matchers<any>'TS2339 on expect(...).toBeInTheDocument() while the test itself runs
Cause 1 of 4
The setup file is missing, or not registered with the test runner
1Check
jest-dom adds its matchers to expect when it is imported. A package that is installed but never imported does nothing. Look for a setup file and for the config entry that points to it.
grep -n "setupFilesAfterEnv" jest.config.*
grep -n "setupFiles" vite.config.* vitest.config.*2Fix
Create a setup file with one import line and register it. For Jest the key is setupFilesAfterEnv, for Vitest it is setupFiles.
// jest-setup.ts
import '@testing-library/jest-dom'
// jest.config.js
module.exports = {
setupFilesAfterEnv: ['<rootDir>/jest-setup.ts'],
};3Verify
Run one test that uses the matcher.
npx jestConfirmed by github.com
Cause 2 of 4
Vitest needs the /vitest entry point
1Check
The package has a separate import path for Vitest. The plain import is the Jest one.
grep -rn "jest-dom" vitest-setup.* src/setupTests.* 2>/dev/null2Fix
Import the Vitest path in the setup file, and list that file in setupFiles.
// vitest-setup.ts
import '@testing-library/jest-dom/vitest'
// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: { setupFiles: ['./vitest-setup.ts'] },
})3Verify
Run the tests once.
npx vitest runConfirmed by github.com
Cause 3 of 4
tsconfig.json does not include the setup file
1Check
The editor and tsc only learn the extra matcher types from files they compile. A setup file named .js, or one outside include, is skipped. The README asks for a .ts setup file listed in include.
npx tsc --noEmit --listFiles | grep -i setup2Fix
Rename the setup file to .ts and add it to include. For Vitest, the README also adds the types to compilerOptions.
{
"compilerOptions": {
"types": ["vitest/globals", "@testing-library/jest-dom"]
},
"include": ["src", "./vitest-setup.ts"]
}3Verify
Type-check the project.
npx tsc --noEmitConfirmed by github.com
Cause 4 of 4
Jest runs with injectGlobals turned off
1Check
With injectGlobals set to false, Jest does not put expect on the global object, so the default import has nothing to extend.
grep -rn "injectGlobals" jest.config.* package.json2Fix
Import the jest-globals path in the setup file instead of the default one.
// jest-setup.ts
import '@testing-library/jest-dom/jest-globals'3Verify
Run the tests again.
npx jestConfirmed by github.com
How do I stop it coming back?
- Keep one setup file for test-wide imports and list it in both the runner config and tsconfig.json.
- Name the setup file with a .ts extension in TypeScript projects.
- When switching from Jest to Vitest, change the jest-dom import path in the same commit.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
TypeScript refuses JSX because the jsx option is not set
TS17004: Cannot use JSX unless the '--jsx' flag is provided.
TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option.
2 causes, each with a fixWeb apps
TypeScript rejects a component that returns an array or other non-Element
Its return type 'Element[]' is not a valid JSX element.
TypeScript before 5.1 required every component to return JSX.Element or null, so arrays, strings and Promises were rejected even though React renders them.
2 causes, each with a fixWeb apps
Cypress refuses to start with 'Your configFile is invalid'
Your configFile threw an error from: /path/to/cypress.config.ts
Cypress could not load cypress.config.js or .ts, or found something wrong in it.
5 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fix