●Change8

v3.0.0

Breaking Changes
📦 vitestView on GitHub →
⚠ 10 breaking✨ 25 features⚡ 1 deprecations🔧 27 symbols

Summary

Vitest 3 introduces numerous new features, a stable API, and support for Vite 6, while also bringing several breaking changes such as updated spy behavior and stricter error matching that require migration steps.

⚠️ Breaking Changes

  • The behavior of `spy.mockReset` has changed; existing tests that rely on the previous reset semantics need to be updated to use the new reset logic.
  • Test hook functions now receive a context argument; update any custom hooks to accept and use this context.
  • Vitest now requires Vite 6; upgrade your Vite dependency to version 6 or later.
  • Coverage collection now always excludes test files; adjust any custom coverage include patterns that previously relied on test files being counted.
  • The `fake-timers` dependency has been upgraded to v14.0.0; ensure compatibility with the new version or pin to an earlier version if needed.
  • `expect` now checks more properties for error equality, which may cause stricter matching; revise error assertions to match the new criteria.
  • The `describe` function now supports a `{ shuffle: boolean }` option and inherits shuffle settings from parent suites; update suite definitions if you used custom shuffle handling.
  • Snapshot state is now reset for tests that use `retry` or `repeats`; modify any snapshot handling that assumed state persistence across retries.
  • `spyOn` now reuses an existing mock when the method is already spied on; adjust spy setup code to avoid unintended mock reuse.
  • The default `toFake` configuration is no longer exposed on the Vitest public API; remove any imports or references to `vitest.toFake`.

Migration Steps

  1. Update any code that calls `spy.mockReset` to align with the new reset semantics.
  2. Modify custom test hooks to accept the new context parameter.
  3. Review coverage configuration and remove any explicit inclusion of test files.
  4. Ensure that your project works with `fake-timers` v14.0.0 or pin the dependency to an earlier version if necessary.
  5. Adjust error assertions in `expect` statements to match the stricter property checks.
  6. If you used custom suite shuffling, update `describe` calls to use the new `{ shuffle: boolean }` option or rely on inheritance.
  7. Rewrite snapshot handling logic if you depended on snapshot state persisting across retries.
  8. Refactor spy setup to avoid unintentionally reusing mocks when using `spyOn` on already spied methods.
  9. Remove any imports or references to the default `toFake` configuration from your code.

✨ New Features

  • Support inline `diff` options and the `printBasicPrototype` flag for richer diff output.
  • Allow a custom note when calling `ctx.skip()` dynamically.
  • Enable inline workspace configuration directly in the Vitest config file.
  • Provide the current project to the global setup function.
  • Print the project name as a label in test output.
  • Expose version information from the `vitest/node` entry point and statically on the Vitest object.
  • `diff.printBasicPrototype` defaults to `false` for cleaner diff displays.
  • Prepare the Vitest API for stability across future releases.
  • Support Vite v6 in the mocker package.
  • Allow multi-browser configuration for parallel browser testing.
  • Add resolved project names to the reporter API.
  • Introduce a new reporter API for custom reporting.
  • Add `describe.for` for data‑driven suite generation.
  • Add `onBrowserInit` event to the Vitest API.
  • Support `actionTimeout` option in the Playwright provider.
  • Add clipboard API methods `userEvent.copy`, `userEvent.cut`, and `userEvent.paste`.
  • Implement `locator.nth()` for easier element selection.
  • CLI now supports excluding projects with `--project=!pattern`.
  • CLI can filter tests by line number using the `--line` option.
  • CLI supports location filters for suites.
  • Coverage `thresholds` now support a maximum uncovered items setting.
  • Add `toHaveBeenCalledExactlyOnceWith` matcher to `expect`.
  • Add `toHaveBeenCalledAfter` and `toHaveBeenCalledBefore` utility matchers.
  • Add `toSatisfy` asymmetric matcher.
  • Add `toBeOneOf` matcher for value set assertions.

🔧 Affected Symbols

spy.mockResettest hook context (e.g., beforeEach, afterEach)coverage configurationfake-timersexpect error equality logicrunner.describe (shuffle option)snapshot state handlingspyOnvitest.toFakevitest/node version exportdiff.printBasicPrototypedescribe.foronBrowserInit eventactionTimeout (Playwright provider)userEvent.copyuserEvent.cutuserEvent.pastelocator.nthCLI project exclusion flagCLI line number filterCLI suite location filterscoverage.thresholdsexpect.toHaveBeenCalledExactlyOnceWithexpect.toHaveBeenCalledAfterexpect.toHaveBeenCalledBeforeexpect.toSatisfyexpect.toBeOneOf

⚡ Deprecations

  • Using an object as the third argument to `suite` or `test` is deprecated; switch to the dedicated options argument instead.