All jobs

Fix "Test environment jest-environment-jsdom cannot be found" After Upgrading to Jest 28 or 29

Yes. An agent adds jest-environment-jsdom at the major matching your Jest, runs the suite, and reports every snapshot the newer jsdom changes without overwriting it.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Until Jest 27, a browser-like test environment came in the box: setting testEnvironment to jsdom just worked. Jest 28 moved that environment into its own package, jest-environment-jsdom, which a project now installs itself. A repository upgraded across that line, with its configuration left as it was, fails before any test starts: Test environment jest-environment-jsdom cannot be found. Make sure the testEnvironment configuration option points to an existing node module. Jest adds a last line that explains it, As of Jest 28 "jest-environment-jsdom" is no longer shipped by default, make sure to install it separately, which is easy to miss at the bottom of a CI log.

pklaschka/xd-dialog-helper is in precisely this state. Its package.json lists "jest": "^29.3.1" under devDependencies and configures "jest": { "testEnvironment": "jsdom" }, and jest-environment-jsdom appears nowhere in package.json or in package-lock.json. The repository has a .github/dependabot.yml that checks npm daily, which is the usual way a test runner moves two major versions without anyone editing the configuration around it. So npm test, which runs jest --coverage after a pretest webpack build, cannot get past validation.

The agent installs the missing package at the major that matches the project's Jest. That detail is worth stating because an unversioned npm install --save-dev jest-environment-jsdom takes the newest release, which can be a major ahead of the Jest in the lockfile. With the environment in place, the suite can run for the first time since the upgrade, and that is when the real work shows up. This repository has twelve test files and nine snapshot files under tests/__snapshots__/, and its tests render dialog elements and call expect(rendered).toMatchSnapshot() on DOM nodes. The separately packaged environment brings a much newer jsdom than the one bundled with old Jest releases, and a newer DOM implementation can serialise elements differently.

The agent therefore runs the suite without the update flag and reads each failure. A snapshot that differs only in how the same markup is printed, such as attribute order or whitespace, is a candidate for regeneration, and the agent lists it with the before and after lines. A difference in behaviour, such as a default value, an event that no longer fires, or a missing API, is a test finding and is reported, not papered over. The project defines update-snapshots as npm test -- -u; the agent does not run it on its own judgement for anything but pure formatting changes, and puts those in a separate commit. It also reads the CI that will run this. Here .github/workflows/npmpublish.yml sets node-version: 12 for npm ci and npm test, older than Jest 29 supports, so the publish job would fail on the runner's Node version even with the environment installed. The agent reports that and leaves the workflow for a second change.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "npm test fails with \"Test environment jest-environment-jsdom cannot be found. Make sure the testEnvironment configuration option points to an existing node module.\" Find the Jest version in the lockfile and every place a jsdom environment is requested: testEnvironment in package.json or a jest.config file, projects entries, and @jest-environment jsdom docblocks in test files. Install jest-environment-jsdom as a dev dependency at the same major version as the installed jest, using the project's package manager so the lockfile is updated. Do not change the Jest version. Run the test command exactly as the project defines it, without -u or --ci overrides, and record the result. For every failing test, classify the cause: (1) a snapshot that differs only in serialisation of the same DOM (attribute order, whitespace, quoting), (2) a behavioural difference between the old and new jsdom (a default value, an event, layout or an API that changed or is missing), (3) a failure unrelated to the environment. For class 1, regenerate only those snapshots, in a separate commit, and show the before and after lines for each in the pull request. For class 2 and 3, do not update snapshots and do not edit tests to make them pass: list each with the assertion, the expected and received values, and your reading of the cause. Check every CI workflow and config that runs the tests, report the Node version each uses, and say whether the installed Jest supports it; do not change the workflows. If other Jest 28 or 29 breaking changes affect this project's config (for example renamed options or a removed default), list them. Open a pull request with the full test output before and after.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request whose first commit changes two files: package.json gains one dev dependency and the lockfile gains it and what it pulls in. If any snapshots changed only in formatting, a second commit regenerates exactly those files. The description shows the test output from before the change, which is the validation error, and from after, which is the first real test run on the new Jest.

Then comes the classification. Each failing test is listed under one of three headings with the expected and received values, so a reviewer can agree or disagree with the agent's reading one item at a time. Formatting-only snapshot changes have their old and new lines shown next to each other. Behavioural differences are left failing on purpose: the pull request can be red and still be the correct next step, because it replaces an error that hid every test with a list of the specific ones that need a decision.

A reviewer should open the regenerated snapshot files and confirm the changes are as dull as claimed. An updated snapshot becomes the new truth for that test, so a real regression accepted there would be invisible afterwards. The Node version note for CI is the other thing to act on, since merging a correct fix into a workflow that runs an unsupported Node will still fail.

Run it on every failed test job

Dependency bots cause most of these, and a pull request opened by a bot does not fire a Rush github trigger. Start the run from the workflow instead. Add a step to your test job that runs on failure, checks the log for jest-environment-jsdom cannot be found, and sends the request above with your API key and the pull request's branch as the resources URL, in the form https://github.com/<owner>/<repo>/tree/<branch>. Send a request_id that is a UUID v5 of the workflow run id, so re-running the job returns the run already started.

One GitHub detail decides whether this works: workflows triggered by Dependabot pull requests do not receive ordinary Actions secrets. Store the Rush key as a Dependabot secret as well, under the same name. If the key has a webhook_url, the finished run posts run.completed there, and a small handler can comment the result on the pull request.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The one-line install is the smaller half of this job. The larger half is reading a suite's worth of snapshot diffs and deciding which are cosmetic, and that is slow, careful work that tends to end with someone running the update flag on everything to get the build green. An agent reads every diff at the same level of attention and writes its reasoning beside each, so the person reviewing spends their time on the handful that matter.

It runs the suite on a clean install from the lockfile, in a sandbox with nothing cached. A developer's machine can hide this error entirely when an old node_modules still contains the environment from a previous install. The commands and their output are kept with the session, including the failing run before the fix, so the pull request's before and after are both on record.

Frequently asked questions

Which version of jest-environment-jsdom should I install?

The same major as your Jest: jest-environment-jsdom@29 for Jest 29, @28 for Jest 28. Check the lockfile for the Jest version that is installed, not only the range in package.json. The agent reads the lockfile and pins the matching major.

Why did this break when I only merged a dependency update?

Jest 28 stopped bundling the jsdom environment, so the upgrade removed a package your configuration still names. An automated update changes the Jest version and has no reason to add a new dependency. The configuration is still valid; it just points at a module that is no longer installed.

My snapshots fail after installing it. Should I run jest -u?

Not on everything. The separate package ships a newer jsdom, and some differences are only in how elements are printed while others are real behaviour changes. Update the first kind and investigate the second. The run does that sorting and shows the evidence for each.

Do I need jsdom at all?

Only if your tests touch document, window or DOM elements. Jest's default environment is node, which is faster. If just a few files need the DOM, a @jest-environment jsdom docblock at the top of those files is enough, and the package must still be installed for them.

Does this apply to Create React App or other wrapped setups?

Those tools choose the Jest version and environment for you, so the fix is usually to upgrade the wrapper. If you have overridden testEnvironment yourself or ejected, the same missing package applies. The agent checks which case you are in before installing anything.

More Jest jobs

More jobs like this: Fix a bug from an alert

Keep reading