Jest cannot find the jsdom test environment after an upgrade
Test environment jest-environment-jsdom cannot be found.Short answer
Since Jest 28 the jsdom environment is a separate package, so a config that says testEnvironment jsdom fails until you install jest-environment-jsdom as a dev dependency. If your tests do not touch document or window, drop the setting and let Jest use its default Node environment.
Fix it fast
1Find out which cause you have
Find out where the environment is requested: the Jest config, or a docblock at the top of one test file.
grep -rn "testEnvironment" jest.config.* package.json grep -rn "@jest-environment" src test 2>/dev/null2Match what you see, then jump to its fix
- 1
The error appears right after moving from Jest 27 or older, with testEnvironment set to jsdomThe package was never installedFix - 2
Only some files fail, and they start with a comment containing @jest-environment jsdomA test file asks for jsdom through a docblockFix - 3
Tests only call functions, a server or a database layer and never touch document or windowThe tests do not need a browser-like environmentFix
- 1
What does the error look like?
Test environment jest-environment-jsdom cannot be found.Config line in play: testEnvironment: 'jsdom'
Cause 1 of 3
The package was never installed
1Check
Jest 28 removed jest-environment-jsdom from the default install. List what your project has.
npm ls jest-environment-jsdom2Fix
Install it as a dev dependency, using the same major version as Jest.
npm install --save-dev jest-environment-jsdom3Verify
Run one test file that uses document.
npx jest --runTestsByPath src/example.test.tsConfirmed by jestjs.io
Cause 2 of 3
A test file asks for jsdom through a docblock
1Check
The docblock selects the jsdom environment for that file, so it needs the same package even when the global config says node.
grep -rln "@jest-environment jsdom" src test 2>/dev/null2Fix
Install the package as in the first cause, or remove the docblock from files that do not need a DOM.
/**
* @jest-environment node
*/3Verify
Run the whole suite.
npx jestConfirmed by jestjs.io
Cause 3 of 3
The tests do not need a browser-like environment
1Check
Jest's default environment is Node.js. A leftover testEnvironment line from a template is often the only reason jsdom is requested.
grep -n "testEnvironment" jest.config.* package.json2Fix
Delete the testEnvironment line, or set it to node.
// jest.config.js
module.exports = {
testEnvironment: 'node',
};3Verify
Run Jest again.
npx jestConfirmed by jestjs.io
How do I stop it coming back?
- Add jest-environment-jsdom to devDependencies in the same commit that sets testEnvironment to jsdom.
- Read the Jest migration notes before raising the major version of Jest.
- Choose the environment per file with a docblock only when a few files need a DOM.
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
Back end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix