After a Jest suite moves to Vitest 5, why do call counts reset between tests and mockReset stop blanking mocks, and what breaks?
answer
- two defaults that changed meaning
- cleared before every test
- reset back to the creation implementation
- history goes, behaviour stays
- resetMocks versus mockReset
basics
~20 sVitest 5 turns clearMocks on by default, wiping call history before every test, and its mockReset returns a mock to the implementation it was created with, where Jest's installs an empty function. Cross-test call assertions and reset-then-undefined expectations break.
solid answer
~40 sTwo things differ. First, `clearMocks` defaults to `true` in Vitest 5, so `vi.clearAllMocks()` runs before every test; Jest, and Vitest 4, left it off. Calls recorded at module scope, in a setup file or in `beforeAll` are gone before the asserting test runs, and counts no longer accumulate across tests. Second, Vitest's `mockReset` restores the original implementation: `vi.fn(impl)` goes back to `impl`, and a reset `vi.spyOn` spy calls the real method again, where Jest's reset returns `undefined`. A test expecting `undefined` fails, or quietly runs the real dependency. Note that clearing keeps implementations, so a `mockReturnValue` set in one test still applies in the next. The config key is `mockReset`, not Jest's `resetMocks`, which Vitest ignores. Set `clearMocks: false` while porting if needed, and choose `mockReset` or `restoreMocks` deliberately.
code
typescript · 25 linesimport { expect, test, vi } from 'vitest'
const greeter = { greet: (name: string) => `Hello ${name}` }
const format = vi.fn((name: string) => name.trim())
const spy = vi.spyOn(greeter, 'greet')
test('first test stubs both mocks', () => {
format.mockReturnValue('stub')
spy.mockReturnValue('stubbed greeting')
expect(format(' Ada ')).toBe('stub')
})
test('clearMocks (on by default) wiped history, not implementations', () => {
expect(format).toHaveBeenCalledTimes(0)
expect(format(' Ada ')).toBe('stub')
expect(greeter.greet('Ada')).toBe('stubbed greeting')
})
test('mockReset goes back to the original implementation', () => {
format.mockReset()
spy.mockReset()
expect(format(' Ada ')).toBe('Ada')
expect(greeter.greet('Ada')).toBe('Hello Ada')
expect(greeter.greet).toBe(spy)
})go deeper
Recall the three methods: mockClear empties history, mockReset also resets behaviour, mockRestore also puts a spied method back. Know that Vitest 5 clears history before every test.
Explain how Vitest's mockReset differs from Jest's, why a reset spy calls the real method, and why clearing history does not undo a mockReturnValue.
Diagnose a ported suite: assertions on beforeAll calls failing, reset spies hitting real dependencies, a resetMocks key silently ignored, and choose the fix for each.
Choose the suite-wide defaults: clearMocks on, plus mockReset or restoreMocks, weighing isolation against the cost of re-stubbing behaviour in every test.
## Three levels of mock cleanup A Vitest mock, made with `vi.fn()` or `vi.spyOn()`, carries two kinds of state: **history** (`mock.calls`, `mock.results`, `mock.instances`) and **behaviour** (the implementation, plus any `mockReturnValue` or `...Once` overrides). Three methods clean up different amounts: | Method | History | Behaviour | Spied method on the object | |---|---|---|---| | `mockClear()` | cleared | kept | still the spy | | `mockReset()` | cleared | back to the original implementation | still the spy | | `mockRestore()` | cleared | back to the original implementation | original descriptor put back | Each has an all-mocks helper (`vi.clearAllMocks`, `vi.resetAllMocks`, `vi.restoreAllMocks`) and a config flag that calls it before every test: `clearMocks`, `mockReset` and `restoreMocks`. One asymmetry: `vi.restoreAllMocks` only puts spied originals back. Unlike `mockRestore` on a single mock, it neither clears history nor resets `vi.fn` implementations. ## Difference one: mockReset restores rather than blanks Jest's `mockReset` replaces the implementation with an empty function that returns `undefined`. Vitest's returns the mock to the implementation it was **created with**: - `vi.fn(impl)`, once reset, runs `impl` again. - `vi.fn()`, once reset, returns `undefined`, because there was no implementation to go back to. - A `vi.spyOn(obj, 'method')` spy, once reset, **calls through to the real method** while still recording calls. A ported test that resets a spy and expects `undefined` therefore fails, or, worse, quietly runs the real dependency: a network call or a file write the test was written to avoid. ## Difference two: clearMocks is on by default in Vitest 5 Before every test, Vitest 5 calls `vi.clearAllMocks()`. Jest leaves its `clearMocks` option off by default, and so did Vitest 4. The tests that break are the ones that record calls outside the test that asserts on them: 1. A call made at module scope or in a setup file is cleared before the first test runs. 2. A call made in `beforeAll` is cleared before each test, because the clear runs per test. 3. A test that expects counts to accumulate across tests sees only its own calls. The fix is to make the call inside the asserting test or in `beforeEach`, which runs after the clear, or to set `clearMocks: false` while the suite is being ported. The option's documentation also warns that with concurrent tests, one test's clear wipes history that other running tests still need. ## What clearMocks does not do Clearing removes history only. An implementation or `mockReturnValue` set in one test **still applies in the next**, so `clearMocks` on its own does not isolate behaviour between tests. The options: - set behaviour in `beforeEach` for every test that depends on it; - enable `mockReset: true`, so each mock returns to its original implementation before every test; - enable `restoreMocks: true`, so spied methods get their originals back before every test. ## Names and objects that differ The Jest config key `resetMocks` does nothing in a Vitest config; the Vitest key is `mockReset`. `clearMocks` and `restoreMocks` keep their names but not all of their semantics. Vitest also keeps a **persistent** `mock.mock` object: a reference captured before `mockClear` still points at the live state, where Jest replaces the object, so code that cached it behaves differently. ## Reading the failures after a port The symptoms are recognisable once you know the two changes: - **expected "vi.fn()" to be called 1 times, but got 0 times** on a mock exercised in `beforeAll` or at module scope: `clearMocks` wiped the call before the test ran. - **A count lower than the old one** in a test that relied on calls from earlier tests: history no longer accumulates across tests. - **A real network call, file write or log line** from code that was meant to be stubbed: a spy was reset and now calls through to the original method. - **A value from an earlier test** returned by a stub: clearing kept the implementation, and nothing reset it. Each one usually points to a fix in the test, not to a bug in the code under test. ## A porting checklist - Search for `mockReset` and `resetAllMocks` calls whose tests expect `undefined` afterwards, and for spies that must never reach the real method. - Search for assertions on calls made in `beforeAll`, in setup files or at module scope. - Rename `resetMocks` to `mockReset` in the migrated config. - Decide the defaults once in the root config: keep `clearMocks` on, and choose `mockReset` or `restoreMocks` deliberately rather than by habit.
- A spy stubbed with mockReturnValue in one test still returns that value in the next, although clearMocks is on. Why?`clearMocks` calls `vi.clearAllMocks()`, which runs `mockClear` on every mock: it empties `mock.calls` and `mock.results` but keeps implementations and return-value overrides. To isolate behaviour, set it in `beforeEach`, or enable `mockReset: true` so each mock returns to its original implementation before every test, or `restoreMocks: true` to put spied methods back.
- How do you keep the Vitest 4 behaviour while a large suite is upgraded?Set `clearMocks: false` in the root `test` config. That restores history carrying across tests while you fix the tests that relied on it, usually by moving calls from `beforeAll` or module scope into `beforeEach` or the test itself. Then remove the override so the safer default applies.
- What does restoreMocks: true do in Vitest, and what does it leave alone?It calls `vi.restoreAllMocks()` before each test, which puts back the original descriptors of methods spied with `vi.spyOn`. It does not clear call history, does not reset `vi.fn` implementations, and does not touch mocks created by module automocking.
- Vitest's mockReset leaves a mock returning undefined, exactly like Jest's.
- clearMocks also removes implementations set with mockReturnValue.
- Vitest 5 keeps call history across tests unless you enable clearMocks.
- Jest's resetMocks config key works unchanged in a Vitest config.
- vi.restoreAllMocks clears call history and resets every vi.fn.
Assumes Vitest 5; clearMocks defaults to true since 5.0, while Vitest 4 and Jest leave it off.