feat!: clear mocks by default before each test (#10613)

sheremet-va · web-flow · commit 0f6463bf2f10 · 2026-06-30T08:17:08.000+02:00
diff --git a/docs/config/clearmocks.md b/docs/config/clearmocks.md
@@ -6,7 +6,7 @@ outline: deep
 # clearMocks
 
 - **Type:** `boolean`
-- **Default:** `false`
+- **Default:** `true`
 
 Should Vitest automatically call [`vi.clearAllMocks()`](/api/vi#vi-clearallmocks) before each test.
 
@@ -17,7 +17,7 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
-    clearMocks: true,
+    clearMocks: false,
   },
 })
 ```
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -13,6 +13,45 @@ outline: deep
 Vitest 5.0 is currently in beta. This section tracks breaking changes as they are merged and may change before the stable release.
 :::
 
+### `clearMocks` is Enabled by Default
+
+[`clearMocks`](/config/#clearmocks) now defaults to `true`. Vitest calls [`vi.clearAllMocks()`](/api/vi#vi-clearallmocks) before every test, resetting the `mock.calls`, `mock.instances`, `mock.contexts` and `mock.results` of every mock. Mock implementations are left intact, so this only affects the recorded history.
+
+In practice this means a mock no longer carries calls from one test into the next:
+
+```ts
+import { expect, test, vi } from 'vitest'
+
+const fn = vi.fn()
+
+test('first', () => {
+  fn()
+  expect(fn).toHaveBeenCalledTimes(1)
+})
+
+test('second', () => {
+  fn()
+  // v4: the call from "first" was kept, so this was 2 // [!code --]
+  expect(fn).toHaveBeenCalledTimes(2) // [!code --]
+  // v5: history is cleared before each test, so only this test's call counts // [!code ++]
+  expect(fn).toHaveBeenCalledTimes(1) // [!code ++]
+})
+```
+
+Tests that record calls outside of the test body (for example in a setup file, at the top level of a module, or in a `beforeAll` hook) are the most affected, because that history is cleared before the test that asserts on it runs.
+
+To keep the previous behavior, set `clearMocks` back to `false`:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    clearMocks: false, // [!code ++]
+  },
+})
+```
+
 ### Benchmarking API Rewrite
 
 The benchmarking API has been rewritten. `bench` is no longer a top-level import from `vitest`; it is a [test-context fixture](/guide/test-context#bench) accessed from inside a regular `test()`. See the [Benchmarking guide](/guide/benchmarking) for the new API.
diff --git a/packages/vitest/src/defaults.ts b/packages/vitest/src/defaults.ts
@@ -108,7 +108,7 @@ export const configDefaults: Readonly<{
   watch: !isCI && process.stdin.isTTY && !isAgent,
   globals: false,
   environment: 'node',
-  clearMocks: false,
+  clearMocks: true,
   restoreMocks: false,
   mockReset: false,
   unstubGlobals: false,
diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts
@@ -496,7 +496,7 @@ export interface InlineConfig {
 
   /**
    * Will call `.mockClear()` on all spies before each test
-   * @default false
+   * @default true
    */
   clearMocks?: boolean
 
diff --git a/test/e2e/fixtures/no-module-runner/test/suite.test.ts b/test/e2e/fixtures/no-module-runner/test/suite.test.ts
@@ -1,5 +1,5 @@
 import { assert, describe, expect, it } from 'vitest'
-import { getSetupStates, initJsSetup, initTsSetup } from '../src/setups.ts'
+import { getSetupStates } from '../src/setups.ts'
 
 describe('suite name', () => {
   it('foo', () => {
@@ -8,9 +8,6 @@ describe('suite name', () => {
 
   it('setups work', () => {
     // TODO: a separate CLI test that confirms --maxWorkers=1 --no-isolate runs the setup file for every test file
-    expect(initJsSetup).toHaveBeenCalled()
-    expect(initTsSetup).toHaveBeenCalled()
-
     expect(getSetupStates()).toEqual({
       jsSetup: true,
       tsSetup: true,
diff --git a/test/e2e/test/no-module-runner.test.ts b/test/e2e/test/no-module-runner.test.ts
@@ -147,7 +147,7 @@ describe.runIf(module.registerHooks)('supported', () => {
           expect(greet).toHaveBeenCalledOnce()
         })
       `,
-    }, { watch: true })
+    }, { watch: true, clearMocks: false })
 
     await vitest.waitForStdout('1 passed')
 
diff --git a/test/unit/test/mocked-no-mocks.test.ts b/test/unit/test/mocked-no-mocks.test.ts
@@ -16,6 +16,6 @@ test('mocking several modules work', () => {
   mockedB()
 
   // mockedA is not called because mockedB is restored to be undefined
-  expect(mockedA).toHaveBeenCalledTimes(1)
+  expect(mockedA).toHaveBeenCalledTimes(0)
   expect(mockedB).toHaveBeenCalledTimes(1)
 })
diff --git a/test/unit/test/test-extend.test.ts b/test/unit/test/test-extend.test.ts
@@ -202,7 +202,7 @@ describe('test.extend()', () => {
   describe('fixture call times', () => {
     const apiFn = vi.fn(() => true)
     const serviceFn = vi.fn(() => true)
-    const teardownFn = vi.fn()
+    let teardownCount = 0
 
     interface APIFixture {
       api: boolean
@@ -213,12 +213,12 @@ describe('test.extend()', () => {
       api: async ({}, use) => {
         await use(apiFn())
         apiFn.mockClear()
-        teardownFn()
+        teardownCount++
       },
       service: async ({}, use) => {
         await use(serviceFn())
         serviceFn.mockClear()
-        teardownFn()
+        teardownCount++
       },
     })
 
@@ -251,7 +251,7 @@ describe('test.extend()', () => {
     afterAll(() => {
       expect(serviceFn).toBeCalledTimes(0)
       expect(apiFn).toBeCalledTimes(0)
-      expect(teardownFn).toBeCalledTimes(4)
+      expect(teardownCount).toBe(4)
     })
   })
 
@@ -261,20 +261,22 @@ describe('test.extend()', () => {
       bar: number
     }
 
-    const fooFn = vi.fn(() => 0)
-    const fooCleanup = vi.fn()
+    let fooFnCount = 0
+    let fooCleanupCount = 0
 
-    const barFn = vi.fn(() => 0)
-    const barCleanup = vi.fn()
+    let barFnCount = 0
+    let barCleanupCount = 0
 
     const nestedTest = test.extend<Fixture>({
       async foo({}, use) {
-        await use(fooFn())
-        fooCleanup()
+        fooFnCount++
+        await use(0)
+        fooCleanupCount++
       },
       async bar({}, use) {
-        await use(barFn())
-        barCleanup()
+        barFnCount++
+        await use(0)
+        barCleanupCount++
       },
     })
 
@@ -284,8 +286,8 @@ describe('test.extend()', () => {
 
     nestedTest('should only initialize foo', ({ foo }) => {
       expect(foo).toBe(0)
-      expect(fooFn).toBeCalledTimes(1)
-      expect(barFn).toBeCalledTimes(0)
+      expect(fooFnCount).toBe(1)
+      expect(barFnCount).toBe(0)
     })
 
     describe('level 2, using both foo and bar together', () => {
@@ -297,8 +299,8 @@ describe('test.extend()', () => {
       nestedTest('should initialize foo and bar', ({ foo, bar }) => {
         expect(foo).toBe(0)
         expect(bar).toBe(0)
-        expect(fooFn).toBeCalledTimes(2)
-        expect(barFn).toBeCalledTimes(1)
+        expect(fooFnCount).toBe(2)
+        expect(barFnCount).toBe(1)
       })
 
       afterEach<Fixture>(({ foo, bar }) => {
@@ -307,42 +309,42 @@ describe('test.extend()', () => {
       })
 
       afterAll(() => {
-        expect(barFn).toHaveBeenCalledTimes(1)
-        expect(barCleanup).toHaveBeenCalledTimes(1)
-        expect(fooFn).toHaveBeenCalledTimes(2)
-        expect(barCleanup).toHaveBeenCalledTimes(1)
+        expect(barFnCount).toBe(1)
+        expect(barCleanupCount).toBe(1)
+        expect(fooFnCount).toBe(2)
+        expect(barCleanupCount).toBe(1)
       })
     })
 
     nestedTest('should initialize foo again', ({ foo }) => {
       expect(foo).toBe(0)
-      expect(fooFn).toBeCalledTimes(3)
+      expect(fooFnCount).toBe(3)
     })
 
     afterEach<Fixture>(({ foo }) => {
       expect(foo).toBe(0)
     })
 
     afterAll(() => {
-      expect(fooFn).toHaveBeenCalledTimes(3)
-      expect(fooCleanup).toHaveBeenCalledTimes(3)
-      expect(barFn).toHaveBeenCalledTimes(1)
-      expect(barCleanup).toHaveBeenCalledTimes(1)
+      expect(fooFnCount).toBe(3)
+      expect(fooCleanupCount).toBe(3)
+      expect(barFnCount).toBe(1)
+      expect(barCleanupCount).toBe(1)
     })
   })
 })
 
 // test extend with top level test
 const numbers: number[] = []
-const teardownFn = vi.fn()
+let teardownCount = 0
 const teardownTest = test.extend<{
   numbers: number[]
 }>({
   numbers: async ({}, use) => {
     numbers.push(1, 2, 3)
     await use(numbers)
     numbers.splice(0, numbers.length)
-    teardownFn()
+    teardownCount++
   },
 })
 
@@ -352,7 +354,7 @@ teardownTest('test without describe', ({ numbers }) => {
 
 test('teardown should be called once time', () => {
   expect(numbers).toHaveLength(0)
-  expect(teardownFn).toBeCalledTimes(1)
+  expect(teardownCount).toBe(1)
 })
 
 describe('asynchronous setup/teardown', () => {
diff --git a/test/unit/test/vi.spec.ts b/test/unit/test/vi.spec.ts
@@ -263,13 +263,13 @@ describe('testing vi utils', () => {
   test('can change config', () => {
     const state = getWorkerState()
     expect(state.config.hookTimeout).toBe(10000)
-    expect(state.config.clearMocks).toBe(false)
-    vi.setConfig({ hookTimeout: 6000, clearMocks: true })
-    expect(state.config.hookTimeout).toBe(6000)
     expect(state.config.clearMocks).toBe(true)
+    vi.setConfig({ hookTimeout: 6000, clearMocks: false })
+    expect(state.config.hookTimeout).toBe(6000)
+    expect(state.config.clearMocks).toBe(false)
     vi.resetConfig()
     expect(state.config.hookTimeout).toBe(10000)
-    expect(state.config.clearMocks).toBe(false)
+    expect(state.config.clearMocks).toBe(true)
   })
 
   test('loads unloaded module', async () => {
