Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript cannot find toBeInTheDocument on expect()

ErrorProperty '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.

  • Applies to jest-dom, Jest, Vitest, TypeScript 5.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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_modules
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2Vitest project; the setup file imports '@testing-library/jest-dom' without a suffixVitest needs the /vitest entry pointFix
    3. 3Tests pass, but the editor and tsc still show the errortsconfig.json does not include the setup fileFix
    4. 4Tests import expect and test from '@jest/globals'Jest runs with injectGlobals turned offFix

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 jest

Confirmed by github.com

Did this fix it?

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/null

2Fix

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 run

Confirmed by github.com

Did this fix it?

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 setup

2Fix

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 --noEmit

Confirmed by github.com

Did this fix it?

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.json

2Fix

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 jest

Confirmed by github.com

Did this fix it?

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:

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.