vitest happy-dom vs jsdom: which to pick

TL;DR

Pick happy-dom when you want speed and your tests only touch common DOM APIs. Pick jsdom when you need fuller browser API coverage (like full getComputedStyle behavior or layout-adjacent APIs). Most unit suites run fine on happy-dom and finish noticeably faster; switch to jsdom only when a test fails because an API is missing or behaves differently. You can even mix them: run the fast environment by default and jsdom for the few files that need it.

The query

vitest happy-dom vs jsdom: which to pick

Use this when

• Setting up a new vitest project and choosing the DOM environment
• Tests pass in one environment but fail in the other
• You want to speed up a slow DOM test suite
• Deciding whether per-file environment overrides are worth it

Not for

• Browser E2E testing (use playwright, cypress, or similar)
• React Testing Library render questions unrelated to the environment
• Node-only tests with no DOM at all (use environment: 'node')

Steps

1. List the browser APIs your tests actually use (DOM traversal, events, localStorage, matchMedia, layout reads) and note which ones are exotic. Expected output: a short list of APIs; anything beyond basic DOM/events is a jsdom candidate.
2. Start with happy-dom (environment: 'happy-dom') since it is the faster default. Expected output: suite runs green and completes faster than under jsdom.
3. If a test fails on a missing or divergent API, confirm the same test passes under jsdom by setting // @vitest-environment jsdom at the top of that file. Expected output: the file passes under jsdom, proving the failure is environment-specific, not a code bug.
4. Keep per-file overrides only for files that need them; leave the fast default for everything else. Expected output: vitest --project (or the normal run) is green with the default environment plus a handful of jsdom-annotated files.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RnW7EwCPudYWsjxvKY53Fg