## 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
```text
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