●Change8

Migrating to Vitest v4.0.0

Version v4.0.0 introduces 29 breaking changes. This guide details how to update your code.

Released: 10/22/2025

29
Breaking Changes
18
Migration Steps
27
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

basic reporterUserConfigViteUserConfiggetSourceMapErrorWithDiffTestErrorcoverage optionsinternal helpersenvironment exportstypecheckrunner typesNode typesvitest/nodeworkspace optionprojects optionenvironmentMatchGlobspoolMatchGlobsminWorkersmodule-runnerspy APIbrowser provider factoryexpect asymmetric matcherorder optiontinypoolreporter APIrunner mode todosnapshot CI behavior

Breaking Changes

●Issue #1

The 'basic' reporter has been removed; switch to another reporter such as 'verbose' or the new 'tree' reporter.

●Issue #2

Default exclude pattern has been simplified; update any custom exclude patterns accordingly.

●Issue #3

The deprecated getSourceMap API has been removed; use the new source map handling provided by vitest/node.

●Issue #4

ErrorWithDiff has been replaced by TestError; replace imports and usage of ErrorWithDiff with TestError.

●Issue #5

UserConfig type has been removed; use ViteUserConfig instead.

●Issue #6

Deprecated coverage options have been removed; import coverage utilities from vitest/node.

●Issue #7

Internal helpers and environment exports have been removed; rely on public APIs only.

●Issue #8

typecheck and runner types have been removed; update type imports to the new definitions.

●Issue #9

Node types are no longer exported from the main entry point; import them from vitest/node.

●Issue #10

Support for Vite 5 has been dropped; upgrade to Vite 6 or later.

●Issue #11

Deprecated types have been removed; clean up any references.

●Issue #12

environmentMatchGlobs and poolMatchGlobs options have been removed; configure environments and pools via the new projects API.

●Issue #13

The 'workspace' option is deprecated and removed; use the 'projects' option instead.

●Issue #14

`--standalone` flag is ignored when a CLI filename filter is used; adjust CLI usage if relying on it.

●Issue #15

The test runner now uses module-runner instead of vite-node; no action needed unless you depended on vite-node internals.

●Issue #16

Spying implementation has been rewritten; use the new spy API (e.g., vi.spyOn) for module mocking.

●Issue #17

All deprecated APIs have been removed; migrate to the current public API.

●Issue #18

`minWorkers` option has been removed and is now automatically set to 0 in non‑watch mode; remove the option from config.

●Issue #19

Verbose reporter now prints tests in a list and a new 'tree' reporter is introduced; switch if you need hierarchical output.

●Issue #20

Pretty‑format now includes shadow root contents; no breaking impact.

●Issue #21

The `order` option on test() API has been removed; remove usage.

●Issue #22

Pools have been rewritten without tinypool; no direct impact unless you imported tinypool.

●Issue #23

Browser mode now requires a provider factory instead of a string; update browser provider configuration.

●Issue #24

`expect` now passes current equality testers to asymmetric matchers; no breaking change but be aware of matcher behavior.

●Issue #25

Projects are now limited to config files named 'vitest.config' or 'vite.config'; rename files if needed.

●Issue #26

Reporter deprecated APIs have been removed; update custom reporters to the new API.

●Issue #27

Runner now sets mode to `todo` when test/describe receives no function; adjust tests that relied on previous behavior.

●Issue #28

Snapshot tests now fail on CI when snapshots are obsolete; update CI expectations or fix snapshots.

●Issue #29

Spying on classes is now supported; use the new class spy syntax.

Migration Steps

  1. 1
    Replace usage of the removed 'basic' reporter with 'verbose' or the new 'tree' reporter.
  2. 2
    Update configuration to use ViteUserConfig instead of the removed UserConfig type.
  3. 3
    Import coverage utilities from vitest/node rather than deprecated coverage options.
  4. 4
    Replace getSourceMap calls with the new source‑map handling in vitest/node.
  5. 5
    Swap ErrorWithDiff imports for TestError.
  6. 6
    Remove any imports of internal helpers, environment exports, typecheck, and runner types.
  7. 7
    Import Node types from vitest/node instead of the main entry point.
  8. 8
    Upgrade the project to Vite 6 or newer, as Vite 5 support has been removed.
  9. 9
    Remove the deprecated 'workspace' option and configure multiple projects using the 'projects' option.
  10. 10
    Adjust CLI usage if relying on `--standalone` with filename filters, as it is now ignored.
  11. 11
    If custom code depended on vite-node internals, migrate to the new module‑runner.
  12. 12
    Adopt the new spy API (vi.spyOn, vi.mockObject with spy option) for module mocking.
  13. 13
    Delete the `minWorkers` setting from the config; it is now managed automatically.
  14. 14
    Update any custom reporters to conform to the new reporter API.
  15. 15
    Rename configuration files to end with 'vitest.config' or 'vite.config' for project detection.
  16. 16
    Configure browser providers using a provider factory function rather than a string.
  17. 17
    Remove usage of the `order` option on test() calls.
  18. 18
    If tinypool was imported directly, replace it with the new pool implementation.

Release Summary

Vitest 4.0 introduces a new module‑runner, a tree reporter, and many breaking changes that remove deprecated APIs and drop Vite 5 support. Upgrade by switching to ViteUserConfig, updating reporters, and adjusting configuration options as outlined in the migration guide.

Need More Details?

View the full release notes and all changes for Vitest v4.0.0.

View Full Changelog