ReferenceError: document is not defined

What does the full error look like?

A test that calls document.createElement, or reads window.location, fails in the node environment. Vitest reports each test separately, and the first line of each is the ReferenceError. With the environment set to jsdom or happy-dom, the same two tests passed in our run.

FAIL  a.test.ts > dom
ReferenceError: document is not defined
 ❯ a.test.ts:3:14
      3|   const el = document.createElement('div')

FAIL  a.test.ts > win
ReferenceError: window is not defined
 ❯ a.test.ts:7:10

Should I use jsdom or happy-dom?

The Vitest environment docs describe both as emulating a browser: jsdom through the jsdom package, and happy-dom as considered faster than jsdom but missing some APIs. The Next.js guide for Vitest installs jsdom and sets environment: 'jsdom'. Both made the two tests above pass. If a component test later fails on a missing browser API, that is the point to switch, not before.

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

// vitest.config.ts
import { defineConfig } from "vitest/config"
export default defineConfig({ test: { environment: "jsdom" } })

I set the environment in vite.config.ts and it is still node

The Vitest config docs say that when a vitest.config file exists it has the higher priority and overrides vite.config, so all options in vite.config are ignored. In our run, a vite.config.ts with test.environment set to jsdom was ignored once a vitest.config.ts without it was added, and the same two tests failed with the same error. Put the option in the file Vitest actually reads.

Checklist

How to fix it, then check the fix

1. 01
   Find which config file Vitest reads and whether it sets an environment:

   ls vitest.config.* vite.config.* 2>/dev/null
   grep -rn "environment" vitest.config.* vite.config.* 2>/dev/null

2. 02If both files exist, set the option in vitest.config, or delete it and keep one file. The one named vitest.config wins.
3. 03
   Install the DOM package you chose as a dev dependency, so CI has it:

   npm install -D jsdom

4. 04For only a few DOM tests, leave the project on node and add // @vitest-environment jsdom as the first line of each of those files.
5. 05
   Run the failing file again. It should list the tests as passed, not a ReferenceError:

   npx vitest run path/to/file.test.ts

Related

Related guides

• VitestWhy are my .env values undefined in Vitest, locally or in GitHub Actions?Guide
• LovableHow do I test a Lovable app before launch?Guide
• SupabaseHow do I test Supabase RLS policies?Guide

Sources

Official docs behind this checklist

• Vitest, Test environment (guide)
• Vitest, environment option
• Vitest, Configuring Vitest (config file priority)
• Next.js, Testing: Vitest

FAQ

FAQ for builders before launch