Vitest Upgrade Guide: Performance Boosts and Stricter Defaults

1. Performance Optimization as the Core Focus

The latest releases of mainstream testing frameworks are not about flashy new APIs; they are fundamentally about solving the “slow execution” problem. In benchmark tests, most scenarios show an 8% to 25% speed improvement, spanning from small five-file utility packages to monolithic applications with around 1,280 modules. In Virtual Machine (VM) pool scenarios, performance gains reach up to 53%. Officially, the average improvement sits around 18% (including browser mode), with VM pools seeing the most dramatic gains.

This round of speed optimizations relies on several key engineering changes:

Shared Service Instances. In inline projects mode, multiple projects share the same build server instance. This prevents the repetitive overhead of starting instances and parsing configurations for each project. The payoff is especially noticeable in monorepos containing numerous subpackages.

On-Disk Module Caching. With module caching persisted to disk, compiled modules can be reused across different processes and runs, drastically reducing cold start times. In CI environments, the cache hit rate directly dictates pipeline wait times.

Reduced Main-Thread/Worker Communication. Test case scheduling, result reporting, and coverage collection inherently create round-trips between the main process and workers. The new version minimizes these round-trips by batching operations where possible and converting others to non-blocking asynchronous tasks.

VM Pool Code Reuse. This is where the largest speedup occurs. VM pools are a heavy abstraction introduced for isolation. The new version allows VMs within the same pool to reuse already compiled code, significantly reducing the overhead associated with this isolation.

Additionally, the vitest doctor diagnostic tool was introduced. It reruns the same test suite with different configurations and directly suggests faster alternatives. Browser mode now includes a built-in Trace View, where interactions and assertions are captured as DOM snapshots for step-by-step replay. Furthermore, vi.when allows the same spy to return different values based on specific arguments.

2. Stricter Defaults: Where the Pitfalls Hide

While performance improvements are an obvious win, the stricter default values are the real trap for developers. Pay close attention to the following changes:

Mock Clearing Enabled by Default. The clearMocks option now defaults to true. This means mock call records are automatically cleared after each test case. In most cases, this exposes tests that were inherently flawed—specifically, those relying on the mock history of a previous test. The danger is that local tests might still pass on older versions, but CI will suddenly fail upon upgrading, without explicitly stating that mock history leaked between tests.

Unawaited Async Assertions Now Fail. Previously, failing to await an asynchronous assertion only generated a warning. Now, it results in a direct failure. This catches a massive number of hidden bugs where tests pass but assertions are left as dangling promises that were never actually evaluated.

Non-Top-Level Hoist Mocks Throw Errors. Writing vi.mock outside the top level will now throw an error instead of being silently tolerated. This forces developers to place mock declarations in the correct location.

toThrow('') Matches Any Error. When an empty string is passed as an argument, the semantics change from “matching an empty message” to “matching any error.” This is a semantic trap that requires you to review all assertions using empty string parameters.

3. Upgrade Prerequisites and Migration Checklist

The upgrade threshold is relatively high and requires item-by-item verification:

• Build Tool Version: Requires Vite ≥ 6.4
• Node Version: Requires Node ≥ 22.12
• Package Managers: Yarn users must manually install Vite (it is now a peer dependency)
• Artifact Paths: Reports, attachments, and blobs are now consolidated into the .vitest/ directory. CI pipeline artifact retrieval paths must be updated accordingly.

The ecosystem is still catching up. Some third-party pool implementations remain pinned to older peer dependencies, and a forced upgrade might result in zero test cases running. If your repository relies heavily on this framework, ensure your build tools and Node versions are aligned before scanning your mock clearing and async assertions. Do not just skim the changelog titles.

Recommended Upgrade Steps

# 1. Check current versions and dependency constraints
npm ls vitest vite
# 2. Upgrade Node to 22.12 or higher
nvm install 22.12
nvm use 22.12
# 3. Upgrade the build tool to 6.4 or higher
npm install vite@^6.4
# 4. Upgrade the testing framework
npm install vitest@^5
# 5. Run the diagnostic tool for configuration suggestions
npx vitest doctor

At the code level, focus on scanning for the following types of issues:

// Issue 1: Relying on uncleared mock history
beforeEach(() => {
  // Old versions required manual clearing; the new version clears by default
  // vi.clearAllMocks()  // Can be omitted
});
// Issue 2: Unawaited async assertions
test('async assertion', async () => {
  // Incorrect: dangling assertion
  expect(fetchData()).resolves.toBe('data');
  // Correct: await the assertion
  await expect(fetchData()).resolves.toBe('data');
});
// Issue 3: Incorrect hoist mock placement
// Incorrect: placed inside a describe block
describe('suite', () => {
  vi.mock('./module');  // Will throw an error
});
// Correct: placed at the top level
vi.mock('./module');
describe('suite', () => {});

4. Tooling Ecosystem Updates

Beyond the core testing framework, the surrounding tooling ecosystem is evolving simultaneously. Certain browser automation projects now allow AI Agents to attach to real local browser sessions, while still requiring human approval for critical clicks. This direction contrasts with giving an Agent unrestricted sandbox superpowers: sacrificing a bit of automation in exchange for controllability and login state reuse. This serves as a solid reference implementation for those working on browser automation or toolchain integration, but it should not be connected directly to production accounts without an approval mechanism.

Additionally, open-source CLI tools are targeting the “documentation and code mismatch” problem. The approach is to have the CLI repeatedly scan, modify, and verify documentation quality, rather than generating a massive block of text in one go. These tools are highly valuable for maintaining documentation consistency in large-scale projects.

Another notable trend is a return to the fundamentals of cross-origin issues, breaking them down to “browser same-origin policy + server-side approval.” This corrects the common frontend misconception that CORS is simply a backend mechanism to block bad actors. The practical takeaway for daily debugging is clear: when a preflight fails, first check if the Origin, methods, and headers are allowed. Do not blindly add proxies on the frontend without updating response headers. Furthermore, never use wildcards for credentialed requests in production environments.

5. Conclusion

The core philosophy of the new testing framework version is to maximize speed first, then quietly tighten default behaviors. The performance improvements are the obvious benefit, but the breaking changes introduced by stricter defaults represent the true cost of the upgrade. Before upgrading, teams should complete three essential tasks:

1. Align Dependency Versions: Verify the build tool, Node version, and package manager one by one.
2. Scan Test Code: Check for mock clearing, asynchronous assertions, hoist placement, and empty string parameters.
3. Update CI Configurations: Migrate artifact paths from old directories to .vitest/.

Do not blindly upgrade just by reading the changelog title. Run through the checklist above to truly benefit from the speed improvements, rather than being overwhelmed by sudden red tests.