Mocks
用 vi.fn 即可创建 mock 函数或类,并全程记录其调用情况;若想监控已存在对象上的某个属性,则改用 vi.spyOn。
import { vi } from 'vitest'
const fn = vi.fn()
fn('hello world')
fn.mock.calls[0] === ['hello world']
const market = {
getApples: () => 100,
}
const getApplesSpy = vi.spyOn(market, 'getApples')
market.getApples()
getApplesSpy.mock.calls.length === 1要验证 mock 的行为,请通过 expect 调用类似 toHaveBeenCalled 的断言方法;以下 API 参考汇总了所有可用来操控 mock 的属性和方法。
重要说明
Vitest 的 spy 函数在初始化时会继承被监听函数的 length 属性,但后续如果修改被监听函数,则不会覆盖该属性值。
const fn = vi.fn((arg1) => {})
fn.length // == 1
fn.mockImplementation(() => {})
fn.length // == 1const example = {
fn(arg1, arg2) {
// ...
}
}
const fn = vi.spyOn(example, 'fn')
fn.length // == 2
fn.mockImplementation(() => {})
fn.length // == 2提示
以下类型中的自定义函数实现使用泛型 <T> 进行标记。
Class Support
The mockReturnValue, mockReturnValueOnce, mockResolvedValue, mockResolvedValueOnce, mockRejectedValue and mockRejectedValueOnce methods cannot be used when the mock is called with the new keyword. Class constructors have unintuitive behaviour regarding the return value:
const CorrectDogClass = vi.fn(class {
constructor(public name: string) {}
})
const IncorrectDogClass = vi.fn(class {
constructor(public name: string) {
return { name }
}
})
const Marti = new CorrectDogClass('Marti')
const Newt = new IncorrectDogClass('Newt')
Marti instanceof CorrectDogClass // ✅ true
Newt instanceof IncorrectDogClass // ❌ false!尽管接口规范相同,但构造函数的 返回值 被赋给了 Newt,这是一个普通对象,而非模拟类的实例。Vitest 会在简写方法中(但不会在 mockImplementation 中!)防止这种行为,转而抛出错误。
如果需要模拟类的构造实例,考虑改用 class 语法配合 mockImplementation:
mock.mockReturnValue({ hello: () => 'world' })
mock.mockImplementation(class { hello = () => 'world' }) 如果需要测试这种有效用例的行为,可以使用带有 constructor 的 mockImplementation:
mock.mockImplementation(class {
constructor(name: string) {
return { name }
}
})getMockImplementation
function getMockImplementation(): T | undefined若存在 mock 实现,则返回其当前版本;否则返回空值。If an implementation was queued with mockImplementationOnce, it returns the first queued implementation instead.
如果 mock 对象是使用 vi.fn 创建的,它将使用提供的方法作为模拟实现。
如果 mock 对象是使用 vi.spyOn 创建的,除非提供了自定义实现,否则它将返回 undefined。
getMockName
function getMockName(): string此方法返回由 .mockName(name) 为 mock 指定的名称。vi.fn() 创建的替身默认返回 'vi.fn()';vi.spyOn 生成的 spy 则沿用被监视方法的原始名称。
mockClear
function mockClear(): Mock<T>清除所有关于每次调用的信息。调用此方法后,.mock 上的所有属性将恢复到初始状态。这个方法不会重置实现。它适用于在不同断言之间清理 mock 对象。
const person = {
greet: (name: string) => `Hello ${name}`,
}
const spy = vi.spyOn(person, 'greet').mockImplementation(() => 'mocked')
expect(person.greet('Alice')).toBe('mocked')
expect(spy.mock.calls).toEqual([['Alice']])
// 清空历史,但是保留模拟对象的实现
spy.mockClear()
expect(spy.mock.calls).toEqual([])
expect(person.greet('Bob')).toBe('mocked')
expect(spy.mock.calls).toEqual([['Bob']])要在每个测试之前自动调用此方法,请在配置中启用 clearMocks 设置。
mockName
function mockName(name: string): Mock<T>设置内部 mock 名称。这在断言失败时识别 mock 对象非常有用。
mockImplementation
function mockImplementation(fn: T): Mock<T>接受一个函数,用作 mock 实现。TypeScript 要求参数和返回类型与原始函数相匹配。
const mockFn = vi.fn().mockImplementation((apples: number) => apples + 1)
// 或:vi.fn(apples => apples + 1);
const NelliesBucket = mockFn(0)
const BobsBucket = mockFn(1)
NelliesBucket === 1 // true
BobsBucket === 2 // true
mockFn.mock.calls[0][0] === 0 // true
mockFn.mock.calls[1][0] === 1 // true如果实现是一个类,模拟对象的 prototype 会重新指向实现的原型,这样构造的实例就能访问其原型方法,并通过 instanceof 检查。详情参阅 模拟类。
mockImplementationOnce
function mockImplementationOnce(fn: T): Mock<T>接受一个函数作为 mock 实现。TypeScript 要求该函数的参数和返回类型与原函数相匹配。这个方法可以被链式调用,以便对多次函数调用产生不同的结果。
const myMockFn = vi
.fn()
.mockImplementationOnce(() => true) // 1st 调用
.mockImplementationOnce(() => false) // 2nd 调用
myMockFn() // 1st 调用:true
myMockFn() // 2nd 调用:false当 mock 函数用完所有实现后,如果之前调用过 vi.fn(() => defaultValue) 或 .mockImplementation(() => defaultValue),它将调用设置的默认实现:
const myMockFn = vi
.fn(() => 'default')
.mockImplementationOnce(() => 'first call')
.mockImplementationOnce(() => 'second call')
// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn())withImplementation
function withImplementation(
fn: T,
cb: () => void
): Mock<T>
function withImplementation(
fn: T,
cb: () => Promise<void>
): Promise<Mock<T>>在执行回调时,临时覆盖原始模拟实现。
const myMockFn = vi.fn(() => 'original')
myMockFn.withImplementation(
() => 'temp',
() => {
myMockFn() // 'temp'
}
)
myMockFn() // 'original'可与异步回调一起使用。该方法必须等待,之后才能使用原始实现。
test('async callback', async () => {
const myMockFn = vi.fn(() => 'original')
// 由于回调是异步的,我们要等待这个调用
await myMockFn.withImplementation(
() => 'temp',
async () => {
myMockFn() // 'temp'
}
)
myMockFn() // 'original'
})请注意,该方法优先于 mockImplementationOnce。
mockRejectedValue
function mockRejectedValue(value: unknown): Mock<T>传入一个错误对象后,一旦 async 函数被调用,就会立即以该错误作为拒绝原因抛出。
const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'))
await asyncMock() // 抛出 Error<'Async error'>mockRejectedValueOnce
function mockRejectedValueOnce(value: unknown): Mock<T>接受一个值,该值将在下一次函数调用时被拒绝。如果进行链式调用,每个连续的调用都将拒绝指定的值。
const asyncMock = vi
.fn()
.mockResolvedValueOnce('first call')
.mockRejectedValueOnce(new Error('Async error'))
await asyncMock() // 'first call'
await asyncMock() // 抛出 Error<'Async error'>mockReset
function mockReset(): Mock<T>该方法会先执行与 mockClear 相同的清理,再重置 mock 的实现,并一并清除所有一次性(once)设定。
注意:如果 mock 由 vi.fn() 创建,重置后其函数体将变为空实现,默认返回 undefined。如果由 vi.fn(impl) 创建,重置后实现会恢复为传入的 impl。
模拟对象的 prototype 链(原型链)也会随之重置:对于 vi.fn(impl) 和 vi.spyOn() 会恢复为原始类;对于 vi.fn() 则恢复为普通对象。因此,重置后构造的实例将无法再通过针对先前设置的类实现的 instanceof 检查。
适用于想将模拟重置为初始状态。
const person = {
greet: (name: string) => `Hello ${name}`,
}
const spy = vi.spyOn(person, 'greet').mockImplementation(() => 'mocked')
expect(person.greet('Alice')).toBe('mocked')
expect(spy.mock.calls).toEqual([['Alice']])
// 清空历史和重置实现,但是方法依然是被监视
spy.mockReset()
expect(spy.mock.calls).toEqual([])
expect(person.greet).toBe(spy)
expect(person.greet('Bob')).toBe('Hello Bob')
expect(spy.mock.calls).toEqual([['Bob']])要在每个测试之前自动调用此方法,可以在配置中启用 mockReset 设置。
mockRestore
function mockRestore(): void该方法先完成 mockReset 的全部工作;若 mock 通过 vi.spyOn 创建,还会进一步恢复被监视对象的原始属性描述符。
对于由 vi.fn() 创建的 mock,mockRestore 的行为与 mockReset 完全一致。
const person = {
greet: (name: string) => `Hello ${name}`,
}
const spy = vi.spyOn(person, 'greet').mockImplementation(() => 'mocked')
expect(person.greet('Alice')).toBe('mocked')
expect(spy.mock.calls).toEqual([['Alice']])
// 清空调用历史和恢复被监视对象方法
spy.mockRestore()
expect(spy.mock.calls).toEqual([])
expect(person.greet).not.toBe(spy)
expect(person.greet('Bob')).toBe('Hello Bob')
expect(spy.mock.calls).toEqual([])要在每个测试之前自动调用此方法,请在配置中启用 restoreMocks 设置。
mockResolvedValue
function mockResolvedValue(value: Awaited<ReturnType<T>>): Mock<T>接受一个值,该值将在调用异步函数时被解析。TypeScript 只接受与原始函数返回类型相匹配的值。
const asyncMock = vi.fn().mockResolvedValue(42)
await asyncMock() // 42mockResolvedValueOnce
function mockResolvedValueOnce(value: Awaited<ReturnType<T>>): Mock<T>接受一个值,该值将在下一次函数调用时被解析。TypeScript 仅接受与原始函数返回类型相匹配的值。如果进行链式调用,每个连续的调用都将解析指定的值。
const asyncMock = vi
.fn()
.mockResolvedValue('default')
.mockResolvedValueOnce('first call')
.mockResolvedValueOnce('second call')
await asyncMock() // first call
await asyncMock() // second call
await asyncMock() // default
await asyncMock() // defaultmockReturnThis
function mockReturnThis(): Mock<T>如果我们需要返回方法中的 this 上下文而不调用实际实现,请使用此方法。这是以下写法的简写形式:
spy.mockImplementation(function () {
return this
})mockReturnValue
function mockReturnValue(value: ReturnType<T>): Mock<T>接受一个值,该值将在模拟函数每次被调用时返回。TypeScript 仅接受与原始函数返回类型一致的值。
const mock = vi.fn()
mock.mockReturnValue(42)
mock() // 42
mock.mockReturnValue(43)
mock() // 43mockReturnValueOnce
function mockReturnValueOnce(value: ReturnType<T>): Mock<T>接受一个值,该值将在下一次调用 Mock 函数时返回。TypeScript 仅接受与原始函数返回类型相匹配的值。如果链式调用此方法,后续每次调用模拟函数时将依次返回指定的值。
当 mock 函数用尽所有实现后,如果之前调用过 vi.fn(() => defaultValue) 或 .mockImplementation(() => defaultValue),它将调用设置的默认实现:
const myMockFn = vi
.fn()
.mockReturnValue('default')
.mockReturnValueOnce('first call')
.mockReturnValueOnce('second call')
// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn())mockThrow 4.1.0+
function mockThrow(value: unknown): Mock<T>接收一个值,该值会在每次调用模拟函数时被抛出。
const myMockFn = vi.fn()
myMockFn.mockThrow(new Error('error message'))
myMockFn() // 抛出 <'error message'> 错误mockThrowOnce 4.1.0+
function mockThrowOnce(value: unknown): Mock<T>接收一个值,该值会在下一次函数调用时被抛出。如果链式调用,每次连续调用都会抛出指定的值。
const myMockFn = vi
.fn()
.mockReturnValue('default')
.mockThrowOnce(new Error('first call error'))
.mockThrowOnce('second call error')
expect(() => myMockFn()).toThrow('first call error')
expect(() => myMockFn()).toThrow('second call error')
expect(myMockFn()).toEqual('default')mock.calls
const calls: Parameters<T>[]这是一个数组,包含了每次调用的所有参数。数组中的每个项目都是那次调用的参数。
const fn = vi.fn()
fn('arg1', 'arg2')
fn('arg3')
fn.mock.calls
=== [
['arg1', 'arg2'], // 首次调用
['arg3'], // 第二次调用
]对象按引用存储。
请注意,Vitest 在 mock 状态的所有属性中始终按引用保存对象。一旦你的代码修改了这些属性,诸如 .toHaveBeenCalledWith 之类的断言便可能无法通过:
const argument = {
value: 0,
}
const fn = vi.fn()
fn(argument) // { value: 0 }
argument.value = 10
expect(fn).toHaveBeenCalledWith({ value: 0 })
// 相等性检查是针对原始参数进行的,
// 但是,该参数的属性在调用和断言之间发生了更改。
expect(fn).toHaveBeenCalledWith({ value: 10 }) 此时,可先自行克隆该参数:
const calledArguments = []
const fn = vi.fn((arg) => {
calledArguments.push(structuredClone(arg))
})
expect(calledArguments[0]).toEqual({ value: 0 })mock.lastCall
const lastCall: Parameters<T> | undefined该属性保存最近一次调用时传入的全部参数;若 mock 尚未被调用,则返回 undefined。
mock.results
interface MockResultReturn<T> {
type: 'return'
/**
* 函数返回的值。
* 如果函数返回的是一个 Promise,那么此处的值就是该 Promise,而不是其 resolved 后的值。
*/
value: T
}
interface MockResultIncomplete {
type: 'incomplete'
value: undefined
}
interface MockResultThrow {
type: 'throw'
/**
* 函数执行过程中抛出的错误。
*/
value: any
}
type MockResult<T>
= | MockResultReturn<T>
| MockResultThrow
| MockResultIncomplete
const results: MockResult<ReturnType<T>>[]这是一个数组,包含了从函数中返回的所有值。数组中的每个项目是一个包含属性 type 和 value 的对象。可用的类型包括:
'return':函数已正常返回,未抛异常。'throw':函数执行过程中抛出了异常。'incomplete':函数尚未结束,仍在运行。
value 属性包含返回值或抛出的错误。如果函数返回一个 Promise,那么即使 Promise rejected,result 也将始终为 'return'。
const fn = vi
.fn()
.mockReturnValueOnce('result')
.mockImplementationOnce(() => {
throw new Error('thrown error')
})
const result = fn() // 返回 'result'
try {
fn() // 抛出错误
}
catch {}
fn.mock.results
=== [
// 首个结果
{
type: 'return',
value: 'result',
},
// 最后结果
{
type: 'throw',
value: Error,
},
]mock.settledResults
interface MockSettledResultIncomplete {
type: 'incomplete'
value: undefined
}
interface MockSettledResultFulfilled<T> {
type: 'fulfilled'
value: T
}
interface MockSettledResultRejected {
type: 'rejected'
value: any
}
export type MockSettledResult<T>
= | MockSettledResultFulfilled<T>
| MockSettledResultRejected
| MockSettledResultIncomplete
const settledResults: MockSettledResult<Awaited<ReturnType<T>>>[]该数组按顺序记录了函数每次被调用后最终兑现或拒绝的值。
若函数返回的是非 Promise ,实际值会原封不动地保留,但状态仍被标记为 fulfilled 或 rejected。
在结果出来前,对应的 settledResult 类型始终为 incomplete。
const fn = vi.fn().mockResolvedValueOnce('result')
const result = fn()
fn.mock.settledResults === [
{
type: 'incomplete',
value: undefined,
},
]
await result
fn.mock.settledResults === [
{
type: 'fulfilled',
value: 'result',
},
]mock.invocationCallOrder
const invocationCallOrder: number[]这个属性返回 mock 函数执行的顺序。它是一个数字数组,这些数字在所有定义的 mock 之间共享。
const fn1 = vi.fn()
const fn2 = vi.fn()
fn1()
fn2()
fn1()
fn1.mock.invocationCallOrder === [1, 3]
fn2.mock.invocationCallOrder === [2]mock.contexts
type MockProcedureContext<T> = T extends new (...args: any[]) => any
? InstanceType<T>
: ThisParameterType<T>
const contexts: MockProcedureContext<T>[]这个属性是一个数组,包含了在每次调用模拟函数时使用的 this 值。If the mock was called with the new keyword, the value is the same as in mock.instances.
const fn = vi.fn()
const context = {}
fn.apply(context)
fn.call(context)
fn.mock.contexts[0] === context
fn.mock.contexts[1] === contextmock.instances
const instances: MockProcedureContext<T>[]This property is an array with one value for each call to the mock function. If the mock was called with the new keyword, the value is the object that new returned, or undefined if the constructor threw an error. Otherwise, the value is the context (this) of the call, the same as in mock.contexts.
const MyClass = vi.fn()
const context = {}
const a = new MyClass()
MyClass.call(context)
MyClass.mock.instances[0] === a
MyClass.mock.instances[1] === context若模拟实现从构造函数中返回一个对象,mock.instances 会存储该对象:
const Spy = vi.fn(function () {
return { method: vi.fn() }
})
const a = new Spy()
Spy.mock.instances[0] === a
Spy.mock.results[0].value === a