vi.fn() 是 Vitest 中创建可追踪模拟函数的核心方法，用于监听调用次数、参数、返回值等；支持 mockReturnValue、mockImplementation 等配置，并需配合 vi.mock() 替换模块函数以实现真实场景测试。
在 JavaScript 测试中，vi.fn() 是 Vitest 提供的创建模拟函数（Mock Function）的核心方法，常用于监听函数是否被调用、被传入什么参数、调用几次等行为。它不执行原始逻辑，而是记录调用痕迹，便于断言验证。
基础用法：创建空 Mock 函数
直接调用 vi.fn() 会返回一个可追踪的模拟函数：
const mockFn = vi.fn();
之后你可以像普通函数一样调用它：
mockFn('hello', 42);
它不会报错，也不会做任何事，但内部已记录了这次调用。
立即学习“Java免费学习笔记（深入）”；
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
监听调用信息：常用断言方法
Mock 函数自带多个属性和方法，用于检查调用情况：
-
mockFn.mock.calls：二维数组，每个子数组是某次调用的参数列表。例如[[ 'hello', 42 ]] -
mockFn.mock.callCount或mockFn.mock.calls.length：调用总次数 -
mockFn.mock.instances：若被new调用，记录每次构造出的实例 -
mockFn.mock.results：记录每次调用的返回值或抛出的错误
常见断言示例：
expect(mockFn).toHaveBeenCalledTimes(1);
expect(mockFn).toHaveBeenCalledWith('hello', 42);
expect(mockFn.mock.calls[0]).toEqual(['hello', 42]);
设置返回值或实现逻辑
可以控制 Mock 函数的行为，让测试更贴近真实场景：
-
固定返回值：
vi.fn().mockReturnValue(100) -
按调用顺序返回不同值：
vi.fn().mockReturnValueOnce('first').mockReturnValueOnce('second') -
模拟实现函数体：
vi.fn().mockImplementation((a, b) => a + b) -
模拟抛出错误：
vi.fn().mockImplementation(() => { throw new Error('oops'); })
替换真实函数（如模块方法）进行监听
配合 vi.mock() 可以拦截模块导出，把真实函数替换成可监听的 Mock：
// 假设 utils.ts 导出一个函数
// import { fetchData } from './utils';
vi.mock('./utils', () => ({
fetchData: vi.fn(),
}));
// 在测试中使用
import { fetchData } from './utils';
test('fetchData is called with correct URL', () => {
fetchData('https://api.example.com');
expect(fetchData).toHaveBeenCalledWith('https://api.example.com');
expect(fetchData).toHaveBeenCalledTimes(1);
});
注意：vi.mock() 必须放在文件顶部（且不能在条件块中），Vitest 才能正确 hoist 并生效。
