Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Vitest ignores environment: 'jsdom' and still runs tests in Node

Errortypeof window is 'undefined' inside a test

Short answer

Vitest runs in a Node.js environment unless a setting says otherwise. When jsdom is set but ignored, one of three things wins over your config: a vitest.config file that shadows vite.config, a --environment flag on the command line, or a docblock at the top of the test file.

  • Applies to Vitest 4, Vite 7, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the environment from inside a failing test. If it says undefined, Vitest is using the Node environment, and the causes below tell you which setting won.

    // add to the failing test file
    import { test } from 'vitest'
    test('env', () => { console.log(typeof window) })
  2. 2Match what you see, then jump to its fix

    1. 1The test block is in vite.config.ts, but a vitest.config.ts also exists in the project rootA vitest.config file shadows vite.configFix
    2. 2Only some test files lack window, or a CI script behaves differently from your editorA control comment or command line flag overrides the configFix
    3. 3environment sits next to plugins instead of inside testThe option is in the wrong place in the configFix

What does the error look like?

  • typeof window is 'undefined' inside a test
  • document or window is missing although test.environment is 'jsdom'
  • The same config works in one test file and not in another

Cause 1 of 3

A vitest.config file shadows vite.config

1Check

Vitest looks for a vitest.config file first and a vite.config file second. If both exist, the first one wins and the second is ignored.

ls vite.config.* vitest.config.*

2Fix

Move the test block into vitest.config.ts, or merge the two files with mergeConfig so the Vite settings and the test settings live in one config.

// vitest.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config'

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

3Verify

Run the one test again and check that typeof window is no longer undefined.

npx vitest run

Confirmed by vitest.dev

Did this fix it?

Cause 2 of 3

A control comment or command line flag overrides the config

1Check

A comment at the top of a file that starts with @vitest-environment sets the environment for that file only. The CLI flag --environment does the same for the whole run. Search for both.

grep -rn "@vitest-environment\|@jest-environment" src
grep -n "environment" package.json

2Fix

Remove the stray comment or flag, or change it to jsdom. Keep jsdom in the config so every file gets it, and use a comment only for the files that need a different one.

// top of a test file that needs jsdom
// @vitest-environment jsdom

3Verify

Run the whole suite, not just one file.

npx vitest run

Confirmed by vitest.dev

Did this fix it?

Cause 3 of 3

The option is in the wrong place in the config

1Check

Open the config. The environment option belongs inside the test object, and the config must come from vitest/config, or carry the triple-slash reference when it imports defineConfig from vite.

sed -n '1,30p' vite.config.ts

2Fix

Put environment inside test, and add the reference line when defineConfig is imported from vite.

/// <reference types="vitest/config" />
import { defineConfig } from 'vite'

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

3Verify

Run Vitest and confirm window exists in the test.

npx vitest run

Confirmed by vitest.dev

Did this fix it?

How do I stop it coming back?

  • Keep test settings in one config file, so there is never a second file that silently wins.
  • Set the environment once in the config and use a control comment only as a deliberate exception.
  • Run vitest from the project root, because the config is searched for in the root.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.