Vitest "environment jsdom not found" in CI

Setting environment: "jsdom" or "happy-dom" tells Vitest which DOM to simulate, but the environment package itself is a separate install. If it is missing from the CI dependency tree, Vitest cannot load it.

What this error means

Vitest fails at startup with "Cannot find package 'jsdom'" or "environment happy-dom was not found" when tests need a browser-like DOM.

Vitest

Error: Cannot find package 'jsdom' imported from
/home/runner/work/app/app/node_modules/vitest/dist/environments.js
The environment "jsdom" was not found. Make sure it is installed.

Common causes

The environment package is not installed

The config requests jsdom or happy-dom, but the corresponding npm package is not in devDependencies, so CI has nothing to load.

It was installed only as a peer expectation

A testing-library setup assumed jsdom but never declared it, so a clean npm ci in CI does not install it.

How to fix it

Install the environment package

Add jsdom (or happy-dom) to devDependencies.
Run npm ci so the CI tree includes it.
Keep the config environment value matching the installed package.

Terminal

npm install -D jsdom
# or: npm install -D happy-dom

Set the environment in config

Declare the environment globally, or per file with a docblock, so DOM tests use it.

vitest.config.ts

export default defineConfig({
  test: { environment: 'jsdom' },
})

How to prevent it

Declare jsdom/happy-dom in devDependencies, not implicitly.
Keep the config environment in sync with the installed package.
Run npm ci from a clean tree in CI to catch missing deps early.