Choosing the Right Vitest Environment: Node, JSDOM, or Happy-DOM

The Cost of Browser Simulation

Selecting the wrong test environment in Vitest often leads to one of two failures: tests that crash because window is undefined, or CI pipelines that time out due to excessive memory consumption. The goal is to use the leanest environment possible that still satisfies the requirements of the code under test.

Environment Comparison

Vitest allows you to define the environment globally or on a per-file basis. The choice depends on whether your code interacts with the Document Object Model (DOM) and how strictly you need to adhere to W3C specifications.

Environment	Primary Use Case	Performance	API Fidelity
node	Pure logic, API routes, utility functions	Fastest	None (No DOM)
happy-dom	Fast UI component tests, simple DOM manipulation	Fast	Partial
jsdom	Complex UI, accessibility tests, legacy browser APIs	Slower	High

Trade-offs and Constraints

Node: This is the default. It has the lowest overhead because it does not simulate a browser. If your test attempts to access document.querySelector, it will throw a ReferenceError. Use this for 90% of your business logic to keep your test suite lean.

Happy-DOM: Designed for speed. It implements the most commonly used browser APIs but skips edge cases to reduce memory usage. It is ideal for large suites of React or Vue components where you only need to verify that elements are rendered or clicked.

JSDOM: A full-scale JavaScript implementation of the web standards. It is significantly heavier than Happy-DOM and can lead to memory leaks in very large test suites if the DOM is not properly cleaned between tests. Use JSDOM only when Happy-DOM fails to support a specific API your code relies on (e.g., complex range selections or advanced accessibility tree calculations).

Implementation and Configuration

To use a browser simulation, you must first install the corresponding package as a development dependency:

# For JSDOM
npm install -D jsdom

# For Happy-DOM
npm install -D happy-dom

Global Configuration

Set the default environment in vitest.config.ts. This applies to all tests unless overridden.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // Options: 'node', 'jsdom', 'happy-dom'
    environment: 'happy-dom',
  },
});

Per-File Overrides

In hybrid projects, you likely have some tests that need a browser and some that don't. Use a docblock at the top of the file to change the environment for that specific test suite. This prevents the overhead of loading a DOM for pure logic tests.

// @vitest-environment node

import { expect, test } from 'vitest';
import { calculateTotal } from './math-utils';

test('calculates total correctly', () => {
  expect(calculateTotal([10, 20])).toBe(30);
});

Validation and Diagnostics

To verify the environment is active, run a test that attempts to access a browser-specific global. Run this command from your terminal with the necessary permissions to execute the test runner:

npx vitest run

Verification Test Case:

test('environment check', () => {
  // This will fail in 'node' but pass in 'jsdom' or 'happy-dom'
  expect(window.location).toBeDefined();
});

Risk Warning: If you switch from jsdom to happy-dom, check your tests for undefined errors related to specific DOM APIs. Happy-DOM may not implement every single method available in a real browser or JSDOM.

Rollback Strategy

If you encounter unexpected failures after changing the environment, revert the environment property in vitest.config.ts to its previous value and remove the newly installed package via npm uninstall.