TL;DR

Vitest v5 introduces significant breaking changes to test setup and reporting, including automatic mock clearing, updated reporter output locations to .vitest, and removal of webdriverio support.

Breaking

• toMatchScreenshot now requires a screenshotDirectory config. (Image comparison feature)
• @sinonjs/fake-timers updated, now supports mocking Temporal objects. (Date/time manipulation library)
• WebdriverIO support has been removed. (Browser automation framework)
• Mocks are now cleared before each test by default.
• Reporter output (JSON, JUnit, HTML) now defaults to the .vitest directory.

New

• vi.when() allows for more precise control over mock behavior. (Mocking utility)

Fixes Worth Knowing

• Improved stability with iframe communication and test name display.
• Corrected issues with per-project sequence configuration and setImmediate timing.
• Fixed coverage reporting offsets caused by unawaited module imports.

TL;DR

Vitest now correctly handles file system access in browser-based commands and resolves external module errors when using the dependency optimizer, improving reliability for web tests.

Fixes Worth Knowing

• Browser tests will no longer fail due to file system access issues.
• Tests using the dependency optimizer with encoded URIs will now resolve modules correctly.

TL;DR

Vitest now handles file system access more reliably in browser environments, preventing potential errors when running tests in those contexts.

Fixes Worth Knowing

Vitest resolves an issue where tests could fail due to file system access errors when running in a browser (web browser testing environment).

TL;DR

Vitest now supports mocking functions to throw errors with mockThrow and mockThrowOnce, and includes improved browser testing with BlazeDiff for visual comparisons and enhanced element finding.

New

• Mocking: Added mockThrow and mockThrowOnce for more control over mock behavior.
• Browser Testing: Switched to BlazeDiff (image comparison tool) and added findElement for more robust browser tests.
• Coverage: Added an option to only report coverage for changed files.

Fixes Worth Knowing

• Fixed issues with stack traces in assertions and dynamic imports.
• Improved handling of skipped tests when hideSkippedTests is enabled.
• Corrected issues with module mocking and resolving external dependencies.
• Fixed a bug where cancelling a test didn't immediately stop execution.

Before You Upgrade

If you are using browser testing, be aware that the visual comparison tool has changed to BlazeDiff. You may need to adjust your expectations for visual diff output.

TL;DR

Vitest now supports testing with Temporal objects, bringing it up to date with the latest JavaScript features.

New

• Temporal Support: Added initial support for testing with Temporal objects (date/time API).
• Vite 7 Support: Vitest is now compatible with Vite version 7 (build tool).
• Custom Matchers: You can now define type-safe custom matchers (assertion helpers) for more readable tests.

Fixes Worth Knowing

• Improved browser test stability by addressing race conditions and file resolution issues.
• Fixed an issue where typechecking could fail to start.
• Test results are now preserved between runs when using the cache.

Before You Upgrade

If you use WebdriverIO, be aware that iframe scaling has been disabled; Playwright and preview modes will continue to scale iframes.

TL;DR

Vitest now includes critical security patches, preventing arbitrary file access and remote code execution vulnerabilities when running tests.

Breaking

• Browser mode now restricts file access (prevents serving arbitrary files).
• Accessing malicious websites while the Vitest API server is running is now blocked (prevents remote code execution).

Fixes Worth Knowing

• Fixed an issue where certain files were incorrectly served, improving security.

Before You Upgrade

Update your Vitest installation immediately to mitigate potential security risks.

TL;DR

Vitest now includes critical security patches, addressing a remote code execution vulnerability when the API server is active.

Breaking

• API Server Security (remote code execution) - A vulnerability allowing malicious websites to execute code via the Vitest API server has been resolved; update immediately.

Fixes Worth Knowing

• Fixed an issue with mockResolvedValue in v1 (compatibility layer).

Before You Upgrade

• Restart your Vitest development server after upgrading to ensure the security patches are active.

TL;DR

Vitest now allows running individual tests or suites directly from the UI, improving workflow for focused debugging and development.

New

• UI Improvements: Run specific tests/suites from the Vitest UI.
• Expect Matchers: Added toHaveBeenCalledExactlyOnceWith, toHaveBeenCalledAfter, and toHaveBeenCalledBefore for more precise mock assertions (mocking frameworks).
• Test Context: Test contexts can now access values provided in the Vitest configuration.

Fixes Worth Knowing

• Improved source map support when using vi.mock.
• Correctly respects the cacheDir setting when the optimizer is enabled.
• React 19 support added.

Before You Upgrade

No specific upgrade steps are required.

TL;DR

Vitest now supports specifying projects to run with the --project flag, allowing for more targeted testing in monorepos (multiple projects).

New

• Project Selection: Use the --project flag to run tests within specific projects.
• Coverage Hints: Coverage reports now respect /* v8 ignore... comments to exclude code from coverage analysis.

Fixes Worth Knowing

• Corrected issues with file path filtering, ensuring tests are run as expected.
• Improved handling of vi.waitUntil (assertion utility) to avoid type errors.
• Fixed a bug where fixtures weren’t preserved with runif and skipif (test conditional execution).

Before You Upgrade

No specific upgrade steps are required.

TL;DR

Vitest now correctly handles custom test environments and global URL configurations, resolving issues with dependency loading and test fixture initialization.

Fixes Worth Knowing

• Fixed an issue where custom test environments (isolated test contexts) weren’t resolving external dependencies.
• Global URL configuration now respects environment variables.
• test.extend fixtures (test setup functions) are initialized only once per test suite, improving performance.

Before You Upgrade

No specific action is needed; these changes are backwards compatible.