Mocking

Mocking functions

Mock functions (or "spies") observe functions, that are invoked in some other code, allowing you to test its arguments, output or even redeclare its implementation.

We use Tinyspy as a base for mocking functions, but we have our own wrapper to make it jest compatible.

Both vi.fn() and vi.spyOn() share the same methods, but the return result of vi.fn() is callable.

vi.fn

Type: (fn: Function) => CallableMockInstance

Creates a spy on a function, though can be initiated without one. Every time a function is invoked, it stores its call arguments, returns and instances. Also, you can manipulate its behavior with methods. If no function is given, mock will return undefined, when invoked.

const getApples = vi.fn(() => 0)

getApples()

expect(getApples).toHaveBeenCalled()
expect(getApples).toHaveReturnedWith(0)

getApples.mockReturnOnce(5)

const res = getApples()
expect(res).toBe(5)
expect(getApples).toHaveReturnedNthTimeWith(1, 5)

vi.spyOn

Type: <T, K extends keyof T>(object: T, method: K, accessType?: 'get' | 'set') => MockInstance

Creates a spy on a method or getter/setter of an object.

let apples = 0
const obj = {
  getApples: () => 13,
}

const spy = vi.spyOn(obj, 'getApples').mockImplementation(() => apples)
apples = 1

expect(obj.getApples()).toBe(1)

expect(spy).toHaveBeenCalled()
expect(spy).toHaveReturnedWith(1)

Mock methods

mockName

Type: (name: string) => MockInstance

Sets internal mock name. Useful to see what mock has failed the assertion.

getMockName

Type: () => string

Use it to return the name given to mock with method .mockName(name).

mockClear

Type: () => MockInstance

Clears all information about every call. After calling it, spy.mock.calls, spy.mock.returns will return empty arrays. It is useful if you need to clean up spy between different assertions.

If you want this method to be called before each test automatically, you can enable clearMocks setting in config.

mockReset

Type: () => MockInstance

Does what mockClear does and makes inner implementation as an empty function (returning undefined, when invoked). This is useful when you want to completely reset a mock back to its initial state.

If you want this method to be called before each test automatically, you can enable mockReset setting in config.

mockRestore

Type: () => MockInstance

Does what mockRestore does and restores inner implementation to the original function.

Note that restoring mock from vi.fn() will set implementation to an empty function that returns undefined. Restoring a vi.fn(impl) will restore implementation to impl.

If you want this method to be called before each test automatically, you can enable restoreMocks setting in config.

mockImplementation

Type: (fn: Function) => MockInstance

Accepts a function that will be used as an implementation of the mock.

For example:

const mockFn = vi.fn().mockImplementation(apples => apples + 1);
// or: 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

mockImplementationOnce

Type: (fn: Function) => MockInstance

Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results.

const myMockFn = vi
  .fn()
  .mockImplementationOnce(() => true)
  .mockImplementationOnce(() => false);

myMockFn(); // true
myMockFn(); // false

When the mocked function runs out of implementations, it will invoke the default implementation that was set with vi.fn(() => defaultValue) or .mockImplementation(() => defaultValue) if they were called:

const myMockFn = vi
  .fn(() => 'default')
  .mockImplementationOnce(() => 'first call')
  .mockImplementationOnce(() => 'second call');

// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());