Interface SpyInstance<TArgs, TReturns>

mock

getMockImplementation

• getMockImplementation(): undefined | ((...args) => TReturns)

• Returns current mock implementation if there is one.

  If mock was created with vi.fn, it will consider passed down method as a mock implementation.

  If mock was created with vi.spyOn, it will return undefined unless a custom implementation was provided.

  Returns undefined | ((...args) => TReturns)

getMockName

• getMockName(): string

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

  Returns string

mockClear

• mockClear(): this

• Clears all information about every call. After calling it, all properties on .mock will return an empty state. This method does not reset implementations.

  It is useful if you need to clean up mock between different assertions.

  Returns this

mockImplementation

• mockImplementation(fn): this

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

  Parameters

  • fn: ((...args) => TReturns) | (() => Promise<TReturns>)

  Returns this

  Example

  const increment = vi.fn().mockImplementation(count => count + 1);
  expect(increment(3)).toBe(4);
  Copy

mockImplementationOnce

• mockImplementationOnce(fn): this

• Accepts a function that will be used as a mock implementation during the next call. Can be chained so that multiple function calls produce different results.

  Parameters

  • fn: ((...args) => TReturns) | (() => Promise<TReturns>)

  Returns this

  Example

  const fn = vi.fn(count => count).mockImplementationOnce(count => count + 1);
  expect(fn(3)).toBe(4);
  expect(fn(3)).toBe(3);
  Copy

mockName

• mockName(n): this

• Sets internal mock name. Useful to see the name of the mock if an assertion fails.

  Parameters

  • n: string

  Returns this

mockRejectedValue

• mockRejectedValue(obj): this

• Accepts an error that will be rejected when async function is called.

  Parameters

  • obj: any

  Returns this

  Example

  const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'))
  await asyncMock() // throws 'Async error'
  Copy

mockRejectedValueOnce

• mockRejectedValueOnce(obj): this

• Accepts a value that will be rejected during the next function call. If chained, every consecutive call will reject specified value.

  Parameters

  • obj: any

  Returns this

  Example

  const asyncMock = vi
    .fn()
    .mockResolvedValueOnce('first call')
    .mockRejectedValueOnce(new Error('Async error'))
  
  await asyncMock() // first call
  await asyncMock() // throws "Async error"
  Copy

mockReset

• mockReset(): this

• Does what mockClear does and makes inner implementation an empty function (returning undefined when invoked). This also resets all "once" implementations.

  This is useful when you want to completely reset a mock to the default state.

  Returns this

mockResolvedValue

• mockResolvedValue(obj): this

• Accepts a value that will be resolved when async function is called.

  Parameters

  • obj: Awaited<TReturns>

  Returns this

  Example

  const asyncMock = vi.fn().mockResolvedValue(42)
  asyncMock() // Promise<42>
  Copy

mockResolvedValueOnce

• mockResolvedValueOnce(obj): this

• Accepts a value that will be resolved during the next function call. If chained, every consecutive call will resolve specified value.

  Parameters

  • obj: Awaited<TReturns>

  Returns this

  Example

  const myMockFn = vi
    .fn()
    .mockResolvedValue('default')
    .mockResolvedValueOnce('first call')
    .mockResolvedValueOnce('second call')
  
  // Promise<'first call'>, Promise<'second call'>, Promise<'default'>
  console.log(myMockFn(), myMockFn(), myMockFn())
  Copy

mockRestore

• mockRestore(): void

• Does what mockReset 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.

  Returns void

mockReturnThis

• mockReturnThis(): this

• Use this if you need to return this context from the method without invoking actual implementation.

  Returns this

mockReturnValue

• mockReturnValue(obj): this

• Accepts a value that will be returned whenever the mock function is called.

  Parameters

  • obj: TReturns

  Returns this

mockReturnValueOnce

• mockReturnValueOnce(obj): this

• Accepts a value that will be returned during the next function call. If chained, every consecutive call will return the specified value.

  When there are no more mockReturnValueOnce values to use, mock will fallback to the previously defined implementation if there is one.

  Parameters

  • obj: TReturns

  Returns this

  Example

  const myMockFn = vi
    .fn()
    .mockReturnValue('default')
    .mockReturnValueOnce('first call')
    .mockReturnValueOnce('second call')
  
  // 'first call', 'second call', 'default'
  console.log(myMockFn(), myMockFn(), myMockFn())
  Copy

withImplementation

• withImplementation<T>(fn, cb): T extends Promise<unknown>
      ? Promise<SpyInstance<TArgs, TReturns>>
      : SpyInstance<TArgs, TReturns>

• Overrides the original mock implementation temporarily while the callback is being executed.

  Type Parameters

  • T

  Parameters

  • fn: ((...args) => TReturns)

    • • (...args): TReturns

      • Parameters

        • Rest ...args: TArgs

        Returns TReturns

  • cb: (() => T)

    • • (): T

      • Returns T

  Returns T extends Promise<unknown>
      ? Promise<SpyInstance<TArgs, TReturns>>
      : SpyInstance<TArgs, TReturns>

  Example

  const myMockFn = vi.fn(() => 'original')
  
  myMockFn.withImplementation(() => 'temp', () => {
    myMockFn() // 'temp'
  })
  
  myMockFn() // 'original'
  Copy