In Jest 30, what is the default testEnvironment, and what do you change so a React component test can use document?
answer
- server default, no DOM
- separate package since Jest 28
- config key or per-file docblock
- one environment per test file
basics
~10 sJest 30 defaults testEnvironment to node, so document and window do not exist. Install jest-environment-jsdom, then set testEnvironment: 'jsdom' in the config or add a @jest-environment jsdom docblock to that test file.
solid answer
~50 s`testEnvironment` defaults to `node`: each test file runs in a Node context with no DOM, so a component test that touches `document` fails with `ReferenceError: document is not defined`. For DOM tests you switch to `jsdom`, a simulated browser built on the jsdom library. Jest stopped bundling `jest-environment-jsdom` in Jest 28, so you install it yourself; if you set `jsdom` without it, Jest stops before any test with a validation error saying the environment cannot be found. You can set `testEnvironment: 'jsdom'` for the whole config, or keep `node` and opt single files in with a `/** @jest-environment jsdom */` docblock at the top of the file, which suits a package that mixes server and component tests. Jest creates a fresh environment for every test file, so globals one file creates are not visible in another.
code
javascript · 9 lines// jest.config.js
const {defineConfig} = require('jest');
module.exports = defineConfig({
testEnvironment: 'jsdom',
testEnvironmentOptions: {
url: 'https://app.test/',
},
});go deeper
Know that the default is node, why document is undefined there, and the two ways to switch a file or a whole config to jsdom.
Explain that every test file gets its own environment instance, that jsdom is a separately installed package, and what testEnvironmentOptions such as url control.
Diagnose environment-shaped failures: a missing environment package, a dependency resolving a browser build under jsdom, and a suite slowed by running server tests under jsdom.
Decide how a monorepo assigns environments, usually node by default with jsdom only where components render, and when layout-dependent checks must move to a real browser.
## What `testEnvironment` decides Every Jest test file runs inside a **test environment**: an object that builds the global scope the file sees and tears it down afterwards. Jest creates **one environment instance per test file**, calls its `setup` before the file runs and its `teardown` after it, so a global that one file creates is not visible to the next. The `testEnvironment` config key names the environment class to use, and `testEnvironmentOptions` passes options to it. Jest has two built-in environments: - `node`, provided by `jest-environment-node`, which comes with Jest. - `jsdom`, provided by `jest-environment-jsdom`, which you install separately. ## The default is `node` In Jest 30 the default is `node`. A test file gets Node's globals, such as `process`, `Buffer` and the timer functions, but there is no `window`, no `document` and no DOM classes. That is the right default for server code, utilities and anything that never renders, and it is what you want for an API package. The moment a test renders a React component or calls a DOM API, the default fails: ```plaintext ReferenceError: document is not defined ``` The error is not a bug in the component. It says the file is running in an environment that has no DOM. ## Switching to `jsdom` 1. **Install `jest-environment-jsdom`** as a dev dependency. It has not been bundled with Jest since Jest 28, and the Jest 30 release of it uses JSDOM v26. 2. **Choose the scope**: set `testEnvironment: 'jsdom'` in the config, or opt single files in with a docblock. 3. **Tune it if needed** with `testEnvironmentOptions`: `url` sets `window.location` (default `http://localhost`), `userAgent` sets the user agent, and `customExportConditions` controls how package `exports` maps are resolved. Jest turns the short name `jsdom` into `jest-environment-jsdom`, and for other names it also tries the `jest-environment-` prefix, so `testEnvironment` can name a package or a path to a custom environment. If step 1 is skipped, Jest stops before running anything: ```plaintext Test environment jest-environment-jsdom cannot be found. Make sure the testEnvironment configuration option points to an existing node module. As of Jest 28 "jest-environment-jsdom" is no longer shipped by default, make sure to install it separately. ``` ## Config key or docblock? | Where you set it | What it covers | Use it when | |---|---|---| | `testEnvironment` in the config | every test file of that config or project | the whole package renders components | | `/** @jest-environment jsdom */` at the top of a file | that one file | one package mixes server tests and DOM tests | | a different `testEnvironment` per entry in `projects` | each project | a monorepo with a web package and an API package | The docblock works at **file** granularity. There is no way to switch the environment for one `test` inside a file, because the environment is built before the file's code runs. For the same reason, a setup file cannot change it: `setupFiles` already runs inside the chosen environment. ## What `jsdom` gives you, and what it does not - **It gives** a DOM tree, `window`, `document`, events and the many web APIs jsdom implements in JavaScript, which is enough to render a component and query or click it. - **It does not lay out pages.** jsdom has no rendering engine, so sizes and positions are not computed; checks that depend on real layout or paint belong in a runner that drives a real browser. - **It resolves packages differently.** The jsdom environment uses the `browser` export condition, while the node environment uses `node` and `node-addons`. A dependency with an `exports` map can therefore load a different file under jsdom, sometimes an ESM-only browser build that then fails to load. `testEnvironmentOptions.customExportConditions` overrides the list. - **It is heavier than `node`.** Building a DOM for every file costs time, so keeping server-only files on `node` keeps a large suite faster. ## Mistakes interviewers listen for - Assuming Jest picks `jsdom` by itself when a test touches the DOM. It never switches on its own; the default stays `node`. - Installing the `jsdom` library and expecting that to be enough. Jest looks for the `jest-environment-jsdom` package. - Trying to create `window` in a setup file instead of choosing an environment. - Putting the whole monorepo on `jsdom` because one package needs it, which slows down every server test.
- Why might a dependency that loads fine in a node-environment test fail to load in a jsdom-environment test?The two environments resolve package `exports` maps with different conditions: jsdom uses `browser`, node uses `node` and `node-addons`. A package can map `browser` to an ESM-only build, which then fails to load from CommonJS test code. Override the list with `testEnvironmentOptions.customExportConditions`, or let that package be transformed.
- Can one test inside a file run under jsdom while the other tests in that file stay on node?No. The environment is created per test file, before any of the file's code runs, and the `@jest-environment` docblock applies to the whole file. Split the DOM tests into their own file, or move them into a project whose `testEnvironment` is `jsdom`.
- Jest defaults to jsdom, so document is always available in a test.
- Jest switches to jsdom on its own when a test touches the DOM.
- jest-environment-jsdom ships inside the jest package, so nothing needs installing.
- A @jest-environment docblock can switch the environment for a single test inside a file.
- Under the node environment all test files share one global object.