Vitest review: what it is, pros, cons and setup

Vitest starts a Vite server in its main process and loads every test file and its imports through Vite’s module runner, which applies the same plugins, aliases and transforms as the application build. TypeScript, JSX, CSS imports and framework single-file components therefore work without a second configuration, and changes to vite.config apply to tests as well. A separate vitest.config file can extend or override it. Because transformed modules are cached by the server, watch mode re-runs only the tests affected by a change, using Vite’s module graph to work out which ones.

Test files run in a pool of workers. The default pool is forks, child processes, chosen for stability; threads, vmThreads and vmForks are alternatives that trade isolation or compatibility for speed. Each file is isolated by default, so module state does not leak between files, and tests within a file run one after another unless marked concurrent. On large machines the single Vite server in the main process can become the bottleneck, which is why the documentation suggests sharding across processes even on one machine.

The environment option chooses node, jsdom or happy-dom for each test file or project, which suits logic and simple component tests. Browser Mode goes further: tests run inside a real browser driven by a provider package, @vitest/browser-playwright or the community-maintained @vitest/browser-webdriverio, with locators and interactions sent through the provider. That gives real layout, events and rendering, and since 4.0 the mode is stable. Version 5 adds a trace view that records each interaction as a DOM snapshot to step through after a failure.

vi.mock replaces a module for the test file. Vitest hoists vi.mock calls above the imports, so the mock is in place before the code under test loads it, and in version 5 those calls must be at the top level of the file or Vitest throws. vi.fn and vi.spyOn create mock functions, vi.mocked adds types, and vi.when, new in version 5, sets return values per argument list. Unlike Jest, there is no automatic loading of __mocks__ folders without a vi.mock call, and importing the real module inside a factory is asynchronous, through vi.importActual.

Keep test settings in vitest.config.ts, using defineConfig from vitest/config, or in the test block of vite.config. Split suites by environment with projects: fast unit tests in node, component tests in jsdom or the browser. Coverage is configured at the root and, since version 4, reports only files that tests load unless you set coverage.include, so set it to your source folder or untested files vanish from the report. The V8 provider is the default choice and since version 4 remaps coverage through the AST, which the release post describes as matching Istanbul’s accuracy.

Put vi.mock at the top level of the file; Vitest hoists it above imports, and version 5 throws if it is nested inside a test or a function. A factory must return the module’s exports explicitly, including default if the module has one. To keep part of the real module, await vi.importActual inside the factory. Use vi.mocked for typed access to mocked functions, and vi.when for per-argument behaviour instead of branching implementations. clearMocks now defaults to true, so call history resets before every test while implementations stay in place.

The documented pattern is a matrix of shard jobs, each running with the blob reporter, followed by one job that downloads every blob and merges them. Blobs land in .vitest/blob in version 5, and the upload step must include hidden files because the folder name starts with a dot. Shards split test files, not individual tests, so keep file sizes roughly even. The GitHub Actions reporter is added automatically when Vitest detects it is running in Actions, so failures are annotated on the pull request without extra configuration.

Start by replacing jest with vi and importing from vitest, or set globals: true to keep the global style. Then work through the differences the official migration guide lists. mockReset restores the original implementation in Vitest, where Jest leaves an empty function. Module mock factories must return explicit exports, and __mocks__ folders load only when vi.mock is called. jest.requireActual becomes an awaited vi.importActual. The done callback is not supported, so convert callback tests to async functions. Test names are joined with a greater-than sign, which changes -t patterns, and JEST_WORKER_ID becomes VITEST_POOL_ID. Snapshot headers differ, so regenerate snapshots once and review the diff.

Upgrade Node to 22.12 or later and Vite to 6.4 or later first. Then expect four kinds of failure. Tests that relied on call history carrying between tests break because clearMocks defaults to true. vi.mock calls inside functions now throw. Unawaited resolves, rejects and toMatchFileSnapshot assertions fail instead of warning, and expect.poll rejects on timeout. Benchmarks need rewriting, because bench is now a fixture inside test rather than a top-level import. Also check custom matcher typings, which take the return type as their first parameter, and any tooling that read reports from the old locations now that everything is written under .vitest. Teams on version 3 should read the version 4 migration guide first.