Maaz Zindani

Loading the index…

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

Jest test fails with window is not defined

ErrorReferenceError: window is not defined

Short answer

Jest runs tests in a node environment by default, and node has no window or document. Set testEnvironment to jsdom in the Jest config, install the jest-environment-jsdom package (it is no longer bundled since Jest 28), or use a docblock to switch only the files that need a browser.

  • Applies to Jest 29, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which environment Jest is using for the failing file.

    grep -rn "testEnvironment\|@jest-environment" jest.config.* package.json src/
  2. 2Match what you see, then jump to its fix

    1. 1window or document is not defined in a test that renders or touches the DOMThe default node environment is in useFix
    2. 2You set testEnvironment to jsdom, but Jest cannot use it, on Jest 28 or newerjest-environment-jsdom is not installedFix
    3. 3Server-side tests pass in node, and only the component tests failOnly some test files need the browserFix

What does the error look like?

  • ReferenceError: window is not defined
  • ReferenceError: document is not defined

Cause 1 of 3

The default node environment is in use

1Check

The default testEnvironment is node. No browser globals exist unless you ask for jsdom.

npx jest --showConfig | grep testEnvironment

2Fix

Set testEnvironment to jsdom for the project.

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
};

3Verify

Run the failing test again.

npx jest path/to/failing.test.js

Confirmed by jestjs.io

Did this fix it?

Cause 2 of 3

jest-environment-jsdom is not installed

1Check

From Jest 28 the jsdom environment is no longer part of the default install. It must be added explicitly.

npm ls jest jest-environment-jsdom

2Fix

Install it. Use a version that matches your Jest version.

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

3Verify

The package is listed next to jest, with the same major version.

npm ls jest jest-environment-jsdom

Confirmed by jestjs.io

Did this fix it?

Cause 3 of 3

Only some test files need the browser

1Check

Changing the whole project may slow the node tests or hide mistakes in server code.

grep -rln "document\.\|window\." src/ --include=*.test.*

2Fix

Put a docblock at the top of each file that needs the DOM.

/**
 * @jest-environment jsdom
 */
test('uses the DOM', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

3Verify

Run that file and the node-only files.

npx jest

Confirmed by jestjs.io

Did this fix it?

How do I stop it coming back?

  • Decide the test environment per project when you create the Jest config, and write it down in the config.
  • Keep DOM code and server code in separate test folders, so each can have its own environment.
  • Pin jest and jest-environment-jsdom to the same major version.

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.