skip to content

How would you decide whether to move a large Jest suite to Vitest 5 in a Vite and TypeScript app with one Node and one jsdom package, and how would you stage it?

level: principalimportance: should knowfreq 30%

answer

  1. what one pipeline saves
  2. renames are cheap, semantics are not
  3. count mocks, not files
  4. projects mirror the packages
  5. both runners green during the move

basics

~20 s

Move when the duplicated Jest transform and config cost more than the rewrite: Vitest reuses the Vite pipeline, but module-mock factories, globals and mock-reset semantics differ. Stage it package by package with test.projects, keeping both runners green until the port ends.

solid answer

~50 s

I'd start from what Jest costs us today. For a Vite and TypeScript app, Vitest's gain is one pipeline (tests reuse the Vite config, aliases and plugins, with no second transform to maintain), plus graph-aware watch mode and `test.projects` to run the Node and jsdom packages in one process. The cost is not the renames but the semantics that change under the same names: factories that must sit at the top level and return an object, `mockReset` restoring rather than blanking, `clearMocks` on by default in Vitest 5, `__mocks__` not auto-applied, no `done` callbacks, globals off. So I'd size the work by mock-heavy files, not file count. If it's worth it, I'd run both runners side by side, port the Node package first, use a temporary `globals: true` to shrink diffs, and re-baseline coverage thresholds instead of comparing numbers across providers.

code

typescript · 14 lines
typescript
import { defineConfig, mergeConfig } from 'vitest/config'
import viteConfig from './vite.config.ts'

export default mergeConfig(viteConfig, defineConfig({
  test: {
    globals: true,
    sequence: { hooks: 'list' },
    coverage: {
      provider: 'v8',
      include: ['src'],
      thresholds: { lines: 80 },
    },
  },
}))

go deeper

for a junior

Recall the mechanical renames: jest.fn to vi.fn, jest.mock to vi.mock, jest.requireActual to vi.importActual, and test APIs imported from vitest.

for a middle

Explain which behaviours change under the same names: factory return shape, mockReset, clearMocks default, root mocks and done callbacks.

for a senior

Plan the mechanics: a mergeConfig root config, node and jsdom projects, temporary compatibility switches, and the silent failures to hunt for first.

for a principal

Own the decision: measure duplication and mock density, decide whether the gain survives the app's build roadmap, stage the move with both runners green, and set the defaults the team keeps.

## What the team would gain For an app already built with Vite and TypeScript, the case for Vitest rests on removing duplication, not on speed claims: - **One pipeline.** Tests reuse the app's Vite config (aliases, plugins, `define`) instead of a parallel transform and module-mapping setup that has to track the build. - **No compile step to maintain.** TypeScript and ESM run as written, so there is no separate transformer configuration to upgrade alongside the compiler. - **Watch mode on the module graph.** `vitest` re-runs only the tests that import a changed file. - **One config for both packages.** `test.projects` gives the Node package and the jsdom package their own `environment` and `setupFiles` in one run, with `coverage` and `reporters` set once at the root. ## What the move costs The renames (`jest.fn` to `vi.fn`, `jest.requireActual` to `vi.importActual`, `jest.Mock` to the `Mock` type from `vitest`) are cheap and mechanical. The cost sits in behaviour that keeps a familiar name but changes meaning: | Area | Jest habit | Vitest 5 behaviour | |---|---|---| | Globals | always available | off by default; import from `vitest` or set `globals: true` | | Module factory | return value is the default export | must return an object; default under `default` | | Mock call placement | hoisted by Jest's transform | hoisted, must be top level; outer values via `vi.hoisted` | | Root `__mocks__` | applied automatically | used only when `vi.mock` names the module | | `mockReset` | empty function returning `undefined` | back to the original implementation | | Mock history | kept across tests unless `clearMocks` | cleared before every test | | `done` callback | supported | not supported; the first argument is the test context | | Hook order | in the order defined | after-hooks reversed (`sequence.hooks: 'stack'`) | | Name filter `-t` | space-joined names | `>`-joined names | | Coverage | Jest's own default provider | `v8` by default, or `istanbul` | The `done` row is the dangerous one. A callback-style test receives the context object, returns at once and passes; its assertion runs later and surfaces, at best, as an unhandled error attributed to another test. ## Deciding A lead weighs the move against what the current suite costs: 1. **How much configuration is duplicated?** Aliases, transforms and module mappers defined twice, and test breakages whenever the build changes, are the strongest signal for moving. 2. **How mock-heavy is the suite?** Count module factories, `mockReset` calls, root `__mocks__` files and assertions on calls made in `beforeAll`. That, not the file count, predicts the effort. 3. **What depends on Jest-only behaviour?** Done callbacks, legacy fake timers, `require`-based module mocking and custom Jest environments each need a rewrite. 4. **Will the app stay on Vite?** If the build is moving elsewhere, the main benefit leaves with it. Little duplication, heavy mocking and many Jest-only features can honestly add up to staying put. ## Staging the move 1. Add Vitest beside Jest, with each runner owning a disjoint set of files, and keep both in CI. 2. Create `vitest.config.ts` with `mergeConfig` over `vite.config.ts`, and define an `api` project on `node` and a `web` project on `jsdom`. 3. Port the Node package first; it avoids DOM and environment differences while the team learns the mock semantics. 4. Use temporary switches (`globals: true`, `sequence.hooks: 'list'`, even `clearMocks: false`) where they shrink the diff, and write down when each will be removed. 5. Move files in batches, and delete a package's Jest config once its last file has moved. Vitest 5 fails any test whose `.resolves` or `.rejects` assertion is not awaited, so expect each batch to surface a few of those; fix them rather than suppress them. 6. Re-baseline coverage thresholds after the first full Vitest run. The provider and the file-selection rules differ, so old and new numbers are not directly comparable. ## Defaults to set and enforce - Keep `clearMocks: true`, and decide on `mockReset` or `restoreMocks` explicitly. - Call `vitest run` in CI and in commit hooks, never bare `vitest`. - Reject callback-style tests in review; require `async` tests or returned promises. - Decide on globals once, for the whole repository, rather than per package.

  • Which Jest habits break silently, rather than loudly, after the move?
    A callback-style `done` test passes at once because Vitest hands it the test context and does not wait. A reset `vi.spyOn` spy calls the real method. A root `__mocks__` file is ignored unless `vi.mock` names the module, so the real module runs. A mocked module that a dependency in `node_modules` imports stays real unless that dependency is listed in `server.deps.inline`.
  • Would you turn on globals: true during the migration, and keep it afterwards?
    During the move it cuts the diff: ported files keep un-imported `describe`, `it` and `expect`, and some DOM helper libraries rely on globals for automatic cleanup. Afterwards it is a team choice. Explicit imports make each file self-describing and keep the global namespace clean, so many teams remove it once the last file has moved.

  • Vitest is a drop-in replacement, so renaming jest to vi finishes the job.
  • Root __mocks__ files apply automatically in Vitest, as they do in Jest.
  • Done-callback tests keep working in Vitest exactly as they did in Jest.
  • Setting globals: true removes every behavioural difference between the two runners.
  • The move has to be a big-bang switch because both runners cannot coexist.
  • Effort is best estimated from the number of test files in the suite.

Assumes Vitest 5; clearMocks on by default, inline projects inheriting the root config and the >-joined test-name filter are all 5.0 changes.