Skip to main content

How to Resolve the "Error: Test environment jest-environment-jsdom cannot be found" Error in JavaScript

When upgrading Jest or setting up a new project, you may encounter the error: "Test environment jest-environment-jsdom cannot be found." This error is common and has a simple fix. It occurs because, starting with Jest version 28, the jest-environment-jsdom package is no longer bundled with Jest by default and must be installed separately.

This guide will walk you through a clear, step-by-step process to fix this error, from the initial installation to ensuring your configuration is correct.

The Core Problem: A Missing Dependency​

Prior to version 28, Jest shipped with the jsdom test environment included. To reduce the package size and make dependencies more explicit, the Jest team decided to separate it. Now, if your configuration specifies "jsdom" as the test environment, you are responsible for adding that package to your project.

Step 1: The Primary Solution: Install jest-environment-jsdom​

For 99% of cases, the solution is to simply install the missing package as a development dependency.

Open your terminal in your project's root directory and run the following command:

npm install jest-environment-jsdom --save-dev
note

If you use Yarn, the command is yarn add jest-environment-jsdom --dev

After the installation is complete, try running your tests again. This will solve the error for most projects.

Step 2: Verify Your Jest Configuration​

Your project needs to be explicitly told to use the jsdom environment. This allows you to run tests that require a browser-like environment (e.g., interacting with the DOM).

Ensure your Jest configuration file (jest.config.js) or your package.json contains the testEnvironment property set to "jsdom".

In jest.config.js:

module.exports = {
  testEnvironment: 'jsdom',
  // ... other configuration
};

In package.json:

{
  "jest": {
    "testEnvironment": "jsdom"
  }
}
note

If you are building a Node.js backend application and do not need a browser environment, you should set this value to "node".

You can also set this on a per-file basis using a docblock comment at the top of your test file, which will override the global configuration:

/**
 * @jest-environment jsdom
 */

test('uses jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Step 3: If the Error Persists: Check for Version Mismatches​

If you have installed the package but the error continues, the most likely cause is a version mismatch between jest and jest-environment-jsdom. These two packages are tightly coupled, and their major versions should always match.

The solution:

  1. Check your package.json: Look in your devDependencies and compare the versions. 
    "devDependencies": {
      "jest": "^29.3.1",
      "jest-environment-jsdom": "^28.1.0" // Mismatch! 29 vs 28
    }
  2. Install matching versions: Manually install versions that align. 
    npm install jest@29 --save-dev
    npm install jest-environment-jsdom@29 --save-dev

This ensures that the environment is compatible with your version of the Jest test runner.

The Last Resort: A Clean Reinstall​

If you are still facing issues, a corrupted node_modules folder or npm cache could be to blame. The final step is to perform a clean reinstallation.

# 1. Remove node_modules and the lock file
rm -rf node_modules
rm -f package-lock.json

# 2. (Optional but recommended) Clean the npm cache
npm cache clean --force

# 3. Reinstall all packages
npm install

After this, restart your IDE and your test server.

Conclusion​

The "Test environment jest-environment-jsdom cannot be found" error is a standard part of the modern Jest setup process.

  • The primary solution is to install the missing dependency: npm install jest-environment-jsdom --save-dev.
  • Ensure your Jest configuration specifies "testEnvironment": "jsdom".
  • If problems persist, make sure the major versions of your jest and jest-environment-jsdom packages match.

Table of Contents