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?
answer
- what one pipeline saves
- renames are cheap, semantics are not
- count mocks, not files
- projects mirror the packages
- both runners green during the move
basics
~20 sMove 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 sI'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 linesimport { 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
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.
Explain which behaviours change under the same names: factory return shape, mockReset, clearMocks default, root mocks and done callbacks.
Plan the mechanics: a mergeConfig root config, node and jsdom projects, temporary compatibility switches, and the silent failures to hunt for first.
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.