●Change8

v4.0.0

Breaking Changes
📦 vitestView on GitHub →
⚠ 29 breaking✨ 15 features🔧 27 symbols

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.

⚠️ Breaking Changes

  • The 'basic' reporter has been removed; switch to another reporter such as 'verbose' or the new 'tree' reporter.
  • Default exclude pattern has been simplified; update any custom exclude patterns accordingly.
  • The deprecated getSourceMap API has been removed; use the new source map handling provided by vitest/node.
  • ErrorWithDiff has been replaced by TestError; replace imports and usage of ErrorWithDiff with TestError.
  • UserConfig type has been removed; use ViteUserConfig instead.
  • Deprecated coverage options have been removed; import coverage utilities from vitest/node.
  • Internal helpers and environment exports have been removed; rely on public APIs only.
  • typecheck and runner types have been removed; update type imports to the new definitions.
  • Node types are no longer exported from the main entry point; import them from vitest/node.
  • Support for Vite 5 has been dropped; upgrade to Vite 6 or later.
  • Deprecated types have been removed; clean up any references.
  • environmentMatchGlobs and poolMatchGlobs options have been removed; configure environments and pools via the new projects API.
  • The 'workspace' option is deprecated and removed; use the 'projects' option instead.
  • `--standalone` flag is ignored when a CLI filename filter is used; adjust CLI usage if relying on it.
  • The test runner now uses module-runner instead of vite-node; no action needed unless you depended on vite-node internals.
  • Spying implementation has been rewritten; use the new spy API (e.g., vi.spyOn) for module mocking.
  • All deprecated APIs have been removed; migrate to the current public API.
  • `minWorkers` option has been removed and is now automatically set to 0 in non‑watch mode; remove the option from config.
  • Verbose reporter now prints tests in a list and a new 'tree' reporter is introduced; switch if you need hierarchical output.
  • Pretty‑format now includes shadow root contents; no breaking impact.
  • The `order` option on test() API has been removed; remove usage.
  • Pools have been rewritten without tinypool; no direct impact unless you imported tinypool.
  • Browser mode now requires a provider factory instead of a string; update browser provider configuration.
  • `expect` now passes current equality testers to asymmetric matchers; no breaking change but be aware of matcher behavior.
  • Projects are now limited to config files named 'vitest.config' or 'vite.config'; rename files if needed.
  • Reporter deprecated APIs have been removed; update custom reporters to the new API.
  • Runner now sets mode to `todo` when test/describe receives no function; adjust tests that relied on previous behavior.
  • Snapshot tests now fail on CI when snapshots are obsolete; update CI expectations or fix snapshots.
  • Spying on classes is now supported; use the new class spy syntax.

Migration Steps

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

✨ New Features

  • Entity parameter added to onConsoleLog callback.
  • onUnhandledError callback added.
  • spy option added to vi.mockObject.
  • Coverage packages no longer use vite-node.
  • Dashboard numbers are now clickable.
  • Test path is displayed when filtering.
  • Separate packages introduced for browser mode providers.
  • Type‑safe extra context hooks added to TestAPI.
  • New `tree` reporter for hierarchical output.
  • Support for spying on classes.
  • Projects now only accept files named 'vitest.config' or 'vite.config'.
  • Browser mode requires a provider factory instead of a string.
  • Expect now passes current equality testers to asymmetric matchers.
  • Snapshot tests fail on CI when snapshots are obsolete.
  • Module‑runner is now the default runner.

🔧 Affected Symbols

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