skip to content

In Vitest 5, how do you run some tests in the node environment and others in jsdom or happy-dom, per file or per package?

level: middleimportance: should knowfreq 45%

answer

  1. default environment is node
  2. a comment at the top of the file
  3. DOM packages installed separately
  4. projects, each with its own environment
  5. inline projects inherit the root

basics

~20 s

Vitest 5 defaults to the node environment. One file opts into jsdom or happy-dom with a // @vitest-environment comment at its top; a whole package gets its own environment as an entry in test.projects, which replaced test.workspace.

solid answer

~40 s

Vitest runs every file in the `node` environment unless told otherwise. `jsdom` and `happy-dom` add a simulated `window` and `document`; neither ships with Vitest, so each is a dev dependency, and happy-dom is documented as faster but missing some APIs. To switch one file, put `// @vitest-environment jsdom` at its top (Vitest also reads `@jest-environment`). To switch a whole package, define it as a project in `test.projects` with its own `include` and `environment`. In Vitest 5 an inline project inherits the root config by default (plugins, aliases and `setupFiles`, with arrays concatenated) while `coverage` and `reporters` stay root-only. The older `test.workspace` option was removed in Vitest 4 and now stops the run at startup.

code

typescript · 26 lines
typescript
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['./test/setup.shared.ts'],
    coverage: { provider: 'v8' },
    projects: [
      {
        test: {
          name: 'api',
          include: ['packages/api/**/*.test.ts'],
          environment: 'node',
        },
      },
      {
        test: {
          name: 'web',
          include: ['packages/web/**/*.test.{ts,tsx}'],
          environment: 'jsdom',
          // appended after the inherited ./test/setup.shared.ts
          setupFiles: ['./packages/web/test/setup.dom.ts'],
        },
      },
    ],
  },
})

go deeper

for a junior

Recall that node is the default environment, that jsdom and happy-dom simulate a DOM, and that one file can switch with a // @vitest-environment comment.

for a middle

Explain when a control comment is enough and when a package needs its own project, and how inline projects inherit the root config, with arrays concatenated.

for a senior

Show the upgrade traps: test.workspace failing at startup, inline projects suddenly inheriting root plugins and setup files in Vitest 5, and root-only options such as coverage.

for a principal

Weigh one config with projects against separate per-package configs: shared defaults and one coverage report, against packages that must be able to diverge freely.

## What an environment is in Vitest A Vitest **environment** decides which globals a test file runs with. Every environment runs inside Node.js; a simulated-DOM environment adds browser-like objects such as `window` and `document` on top of it. The `environment` option sets one for a whole config, and its default is **`node`**. Vitest's browser mode, which runs tests inside a real browser engine, is a separate feature set up as its own project; it is not another value of `environment`. ## The built-in environments | Value | What a test gets | Extra dev dependency | |---|---|---| | `node` | Node.js globals only; no `window` or `document` | none | | `jsdom` | A simulated DOM and browser APIs | `jsdom` | | `happy-dom` | A simulated DOM, documented as faster than jsdom but lacking some APIs | `happy-dom` | There is also an `edge-runtime` value for code written for edge functions, and a custom environment can come from a `vitest-environment-<name>` package or a file path. Neither DOM package ships with Vitest. Vitest prompts to install a missing one in an interactive run; a CI run fails until the package is listed as a dev dependency. ## Choosing per file When most files need one environment and a few need another, keep the config default and mark the exceptions: 1. Put a control comment at the top of the file: `// @vitest-environment jsdom`, or the same tag inside a `/** ... */` docblock. 2. Vitest also honours a `@jest-environment` tag, so ported files keep working unchanged. 3. Options for the environment itself go in `environmentOptions`. This suits one package with a handful of DOM files. It scales badly when an entire package is DOM code and every file has to carry the comment. ## Choosing per package with test.projects `test.projects` defines several **projects** inside one Vitest process, each with its own options, typically `include`, `environment` and `setupFiles`. An entry can be an inline object, a config file, or a glob such as `'packages/*'` that turns every matching folder into a project. For a repository with one Node package and one jsdom package, two inline projects named `api` and `web` are enough. How the options combine: - **Inline projects inherit the root config by default in Vitest 5**, because `extends` now defaults to `true`: `plugins`, `resolve.alias`, `pool` and test options all flow down. Set `extends: false` to start clean, or point `extends` at another config file. - Arrays are **concatenated**, not replaced: a root `setupFiles` entry runs before the project's own. - `name` and `projects` are never inherited, and the root `globalSetup` is not re-run for each project. Project names must be unique. - Projects referenced as **config files or directories inherit nothing** from the root. Combine a shared file yourself with `mergeConfig` and `defineProject`. - `--project web` runs a single project. The flag can repeat and accepts `*` wildcards and `!` exclusions. The root config file is not a project of its own unless it is listed. In CI, a job per package can call `vitest run --project api` and `vitest run --project web`, or a single job can run every project in one process; either way, project names appear as labels in the reporter output, so a failure shows which package it came from. ## Options that stay at the root Some options describe the whole run and cannot differ per project: `coverage`, `reporters`, `resolveSnapshotPath` and `attachmentsDir`. Set them once in the root config; `defineProject` makes TypeScript reject them inside a project file. ## Upgrading from test.workspace Older setups split packages with `test.workspace` or a separate workspace file. That name was deprecated in favour of `projects`, which works the same way, and it was **removed in Vitest 4**. A config that still sets it stops at startup with "The `test.workspace` option was removed in Vitest 4. Please, migrate to `test.projects` instead." Its entries carry over to `test.projects` as they are. When moving from Vitest 4 to 5, re-check inline projects that relied on inheriting nothing. They now pick up the root plugins and the root `setupFiles`, so a project can suddenly run a setup file or a plugin it never had. `extends: false` restores the old behaviour for one project.

  • What changed for inline projects in Vitest 5, and how do you opt out?
    `extends` now defaults to `true`, so every inline project inherits the root config, including Vite options like `plugins` and `resolve.alias`. Arrays merge rather than override: a root `setupFiles` entry runs before the project's own. Set `extends: false` on a project to inherit nothing. Projects referenced as files or directories are unaffected; they still inherit nothing.
  • Why is coverage configured once in the root config rather than per project?
    Coverage is collected for the whole Vitest process, so `coverage` is a root-only option, like `reporters`. A project config cannot set it, and `defineProject` turns the attempt into a TypeScript error. Coverage `include` and thresholds therefore live in the root config and cover every project's files in one report.

  • Vitest runs every test in jsdom unless you pick the node environment.
  • jsdom ships inside Vitest, so environment: 'jsdom' needs no extra install.
  • test.workspace still works in Vitest 5 as an alias for test.projects.
  • An inline project in Vitest 5 starts empty and inherits nothing from the root.
  • Browser mode is just another value you can give the environment option.
  • Each project can set its own coverage provider and reporters.

Assumes Vitest 5: inline projects inherit the root config by default since 5.0, and test.workspace has been removed since Vitest 4.