Testing New Added 10 September 2026

Vitest: ReferenceError: document is not defined

Vitest runs in Node by default, where there is no DOM. The component test needs a browser like environment declared, either for the whole project or per file. Unlike Jest, Vitest does not bundle jsdom, so the package has to be installed as well as configured.

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

Quick fix

# jsdom is a separate install
npm i -D jsdom          # or happy-dom, which is faster and less complete

// vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
  test: { environment: "jsdom", globals: true, setupFiles: ["./vitest.setup.ts"] }
});

// Per file, when most of the suite is pure Node
// @vitest-environment jsdom

// Only some directories need a DOM
test: {
  environmentMatchGlobs: [["src/components/**", "jsdom"], ["src/server/**", "node"]]
}

# Confirm which environment a file ran in
npx vitest run --reporter=verbose src/components/Button.test.tsx

How to diagnose Testing errors

Test errors divide into infrastructure problems (the framework cannot find or load your tests, fixtures or modules) and flakiness, which is the more expensive category. End-to-end timeouts are almost always a race between the test and the application, and the durable fix is to wait for a condition (an element, a network response, a state change) rather than for a duration.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

Run a single failing test in isolation. If it passes alone but fails in the suite, you have shared state or test ordering dependence.
For Cypress and Playwright timeouts, use the trace viewer or video to see what the page actually showed. The element usually exists but is covered, detached, or not yet interactive.
Replace fixed waits with condition-based waits. waitForSelector and auto-retrying assertions eliminate an entire class of flakiness.
For collection and module-resolution errors, check the framework's rootDir/testPaths configuration and the presence of __init__.py or conftest.py where the framework expects it.
Review snapshot diffs rather than updating them reflexively. A changed snapshot is sometimes a real regression.

Tools worth reaching for

playwright show-trace
pytest -x -vv --tb=long
jest --runInBand
cypress open
test retry analytics

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

vitest.dev

Related Testing errors

See all 18 Testing errors →

Browse other categories

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.