Vitest clearMocks 配置详解自动清理 Mock 历史隔离测试间的调用记录【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestclearMocks 是 Vitest 中控制每个测试用例执行前是否自动清理 mock 历史记录的核心配置项。本文以 docs/config/clearmocks.md 为骨架结合 packages/vitest/src/runtime/runners/test.ts 与 packages/vitest/src/integrations/vi.ts 的源码实现讲清该选项的默认行为、底层触发时机、与 restoreMocks / mockReset 的区别以及并发测试下的注意事项读完即可在生产测试套件中正确配置。配置项速览类型boolean默认值true作用是否在每个测试用例test执行前自动调用vi.clearAllMocks()开启后Vitest 会自动清除所有 mock 的调用历史如调用次数、入参、返回值记录但不会影响 mock 的实现本身。也就是说你通过vi.fn()、vi.spyOn()或vi.mock()定义的行为与返回值会原样保留只是历史记录被重置保证每个测试都在干净的调用状态上开始。在vitest.config.js中关闭该行为的配置方式如下import { defineConfig } from vitest/config export default defineConfig({ test: { clearMocks: false, }, })默认值与源码依据该选项的默认值定义在 packages/vitest/src/defaults.ts 中与 mock 清理相关的五个选项默认值集中在一起配置项默认值行为clearMockstrue清除 mock 历史restoreMocksfalse恢复被 spy 的原始实现mockResetfalse重置 mock 实现并清空历史unstubGlobalsfalse还原被 stub 的全局变量unstubEnvsfalse还原被 stub 的环境变量从默认值可以看出Vitest 默认只开启clearMocks轻量清理历史而更重度的restoreMocks、mockReset默认关闭需要用户按需开启。底层实现触发时机与调用链从源码结构看clearMocks的自动清理发生在测试运行器的onBeforeTryTask钩子中即每个测试任务真正执行或重试之前。相关实现位于 packages/vitest/src/runtime/runners/test.tsonBeforeTryTask(test: Task, _options: TestTryOptions): void { clearModuleMocks(this.config) // ... }而clearModuleMocks函数同文件 test.ts按固定顺序执行各清理策略function clearModuleMocks(config: SerializedConfig) { const { clearMocks, mockReset, restoreMocks, unstubEnvs, unstubGlobals } config if (restoreMocks) { vi.restoreAllMocks() } if (mockReset) { vi.resetAllMocks() } if (clearMocks) { vi.clearAllMocks() } if (unstubEnvs) { vi.unstubAllEnvs() } if (unstubGlobals) { vi.unstubAllGlobals() } }值得注意的执行顺序restoreAllMocks→resetAllMocks→clearAllMocks。由于mockReset本身已包含清除历史的能力若同时开启mockReset与clearMocks实际以mockReset的结果为准clearMocks只对仍处于 mock 状态的函数执行清历史动作。clearAllMocks 到底清除了什么配置项最终落到vi.clearAllMocks()上其实现位于 packages/vitest/src/integrations/vi.tsclearAllMocks() { clearAllMocks() return utils },它直接委托给vitest/spy包导出的clearAllMocks见同文件顶部import { clearAllMocks, ... } from vitest/spy并返回utils以支持链式调用。该方法清除的内容包括mock 函数被调用的次数mock.calls每次调用的参数记录mock.results中的入参调用结果、错误记录等历史元数据不会清除mock 的实现vi.fn().mockImplementation(...)设置的行为mock 的返回值mockReturnValue等配置spy 对原始实现的包装关系一句话总结clearMocks负责忘记过去不负责改变未来。这也是它与restoreMocks恢复原始实现、mockReset连实现一起重置的本质区别。典型使用场景1. 校验调用次数时的隔离默认开启推荐这是默认行为true的直接收益每个测试只统计本测试内发生的调用避免前一个测试的调用记录污染断言import { vi, it, expect } from vitest const send vi.fn() it(第一次发送只被调用一次, () { send(hello) expect(send).toHaveBeenCalledTimes(1) // 通过上一用例的历史已被自动清除 }) it(第二次发送同样只被调用一次, () { send(world) expect(send).toHaveBeenCalledTimes(1) // 若未清除这里会是 2 })2. 需要在用例之间保留调用记录的场景关闭当你在多个测试中连续验证同一个 mock 的累计调用次数、或依赖跨用例累计的调用参数序列做快照断言时可关闭该选项export default defineConfig({ test: { clearMocks: false, }, })关闭后如需在特定用例前手动清理可在该用例内显式调用vi.clearAllMocks()。3. 通过 CLI 临时覆盖无需改动配置文件可在命令行按需覆盖npx vitest run --clearMocksfalse与并发测试concurrent的冲突警告原文档明确给出警告启用clearMocks可能与异步并发测试test.concurrent产生冲突。原因在于自动清理发生在一个测试完成的时间点。若多个并发测试共享同一批 mock其中一个测试完成触发clearAllMocks时会连带清除其他仍在执行中的测试所依赖的调用历史导致这些测试出现错误的断言结果如toHaveBeenCalledTimes突然变为 0。因此在使用test.concurrent且共享 mock 状态的测试文件中建议关闭clearMocks改为在测试内部自行管理清理时机import { describe, it, vi, expect } from vitest describe.concurrent(共享 mock 的并发测试, () { it(用例 A, () { // 按需手动清理而不是依赖全局自动清理 vi.clearAllMocks() // ... 断言 }) it(用例 B, () { vi.clearAllMocks() // ... 断言 }) })与相关配置项的组合矩阵配置组合每个测试前发生的行为适用场景仅clearMocks: true默认清除历史保留实现绝大多数测试隔离调用记录mockReset: true清除历史 重置实现mock 函数回到无实现状态需要每次从空白 mock开始定义行为restoreMocks: true恢复被spyOn包装的原始实现避免 spy 影响跨测试的模块行为clearMocks: false什么都不做依赖跨用例累计记录 / 并发共享 mock更多清理语义可对照vi.restoreAllMocks()与vi.resetAllMocks()的 API 文档以及定时器相关的vi.clearAllTimers()。小结clearMocks是 Vitest 默认开启的一项轻量级自动清理机制它在每个测试执行前通过onBeforeTryTask→clearModuleMocks→vi.clearAllMocks()的调用链清除全部 mock 的调用历史让测试之间互不干扰。理解它与restoreMocks、mockReset的层次关系并根据是否使用test.concurrent决定是否关闭它是写出稳定、可重复测试套件的关键一步。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
