●Change8

Migrating to Vitest v3.0.0

Version v3.0.0 introduces 10 breaking changes. This guide details how to update your code.

Released: 1/16/2025

10
Breaking Changes
9
Migration Steps
27
Affected Symbols

⚠️ Check Your Code

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

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

Breaking Changes

●Issue #1

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.

●Issue #2

Test hook functions now receive a context argument; update any custom hooks to accept and use this context.

●Issue #3

Vitest now requires Vite 6; upgrade your Vite dependency to version 6 or later.

●Issue #4

Coverage collection now always excludes test files; adjust any custom coverage include patterns that previously relied on test files being counted.

●Issue #5

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.

●Issue #6

`expect` now checks more properties for error equality, which may cause stricter matching; revise error assertions to match the new criteria.

●Issue #7

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.

●Issue #8

Snapshot state is now reset for tests that use `retry` or `repeats`; modify any snapshot handling that assumed state persistence across retries.

●Issue #9

`spyOn` now reuses an existing mock when the method is already spied on; adjust spy setup code to avoid unintended mock reuse.

●Issue #10

The default `toFake` configuration is no longer exposed on the Vitest public API; remove any imports or references to `vitest.toFake`.

Migration Steps

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

Release 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.

Need More Details?

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

View Full Changelog