Funções Mock

Você pode criar uma função mock para monitorar sua execução usando o método vi.fn. Se você deseja monitorar um método em um objeto já existente, você pode usar o método 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;

Você deve usar asserções de mock (por exemplo, toHaveBeenCalled) em expect para verificar o resultado do mock. Esta referência de API descreve as propriedades e métodos disponíveis para manipular o comportamento do mock.

getMockName

• Tipo: () => string

  Use este método para retornar o nome atribuído ao mock com o método .mockName(name).

mockClear

• Tipo: () => MockInstance

  Remove todas as informações de cada chamada. Após chamá-lo, spy.mock.calls e spy.mock.results retornarão arrays vazios. É útil quando você precisa limpar o mock entre diferentes verificações.

  Se você deseja que este método seja chamado automaticamente antes de cada teste, você pode habilitar a opção clearMocks nas configurações.

mockName

• Tipo: (name: string) => MockInstance

  Atribui um nome interno ao mock. Útil para identificar qual mock falhou na asserção.

mockImplementation

• Tipo: (fn: Function) => MockInstance

  Recebe uma função que será usada como a implementação do mock.

  Por exemplo:

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

• Tipo: (fn: Function) => MockInstance

  Recebe uma função que será usada como implementação do mock para uma única chamada à função mockada. Pode ser encadeado para que múltiplas chamadas de função produzam resultados diferentes.

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

  Quando a função mock não tem mais implementações definidas com mockImplementationOnce, ela invocará a implementação padrão que foi definida com vi.fn(() => defaultValue) ou .mockImplementation(() => defaultValue) se elas foram chamadas:

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

withImplementation

• Tipo: (fn: Function, callback: () => void) => MockInstance

• Tipo: (fn: Function, callback: () => Promise<unknown>) => Promise<MockInstance>

  Substitui temporariamente a implementação original do mock enquanto o callback é executado.

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

  Pode ser usado com um callback assíncrono. O método deve ser aguardado para que a implementação original seja utilizada posteriormente.

  test('async callback', () => {
    const myMockFn = vi.fn(() => 'original');
  
    // Aguardamos esta chamada, pois o callback é assíncrono
    await myMockFn.withImplementation(
      () => 'temp',
      async () => {
        myMockFn(); // 'temp'
      }
    );
  
    myMockFn(); // 'original'
  });

  Além disso, tem precedência sobre mockImplementationOnce.

mockRejectedValue

• Tipo: (value: any) => MockInstance

  Define um erro que será rejeitado quando a função assíncrona for chamada.

  const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'));
  
  await asyncMock(); // lança um erro "Async error"

mockRejectedValueOnce

• Tipo: (value: any) => MockInstance

  Define um valor que será rejeitado para uma única chamada à função mock. Se encadeado, cada chamada consecutiva rejeitará o valor fornecido.

  const asyncMock = vi
    .fn()
    .mockResolvedValueOnce('first call')
    .mockRejectedValueOnce(new Error('Async error'));
  
  await asyncMock(); // first call
  await asyncMock(); // lança um erro "Async error"

mockReset

• Tipo: () => MockInstance

  Faz o mesmo que mockClear, tornando a implementação interna uma função vazia (retornando undefined quando invocada). Isso é útil quando você quer resetar completamente um mock de volta ao seu estado inicial.

  Se você deseja que este método seja chamado automaticamente antes de cada teste, você pode habilitar a configuração mockReset na configuração.

mockRestore

• Tipo: () => MockInstance

  Faz o mesmo que mockReset e restaura a implementação interna para a função original.

  Observe que restaurar um mock criado com vi.fn() definirá a implementação para uma função vazia que retorna undefined. Restaurar um vi.fn(impl) restaurará a implementação para impl.

  Se você deseja que este método seja chamado automaticamente antes de cada teste, você pode habilitar a configuração restoreMocks na configuração.

mockResolvedValue

• Tipo: (value: any) => MockInstance

  Define um valor que será resolvido quando a função assíncrona for chamada.

  const asyncMock = vi.fn().mockResolvedValue(43);
  
  await asyncMock(); // 43

mockResolvedValueOnce

• Tipo: (value: any) => MockInstance

  Define um valor que será resolvido em uma única chamada à função mock. Se encadeado, cada chamada consecutiva resolverá o valor passado.

  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(); // default

mockReturnThis

• Tipo: () => MockInstance

  Define a implementação interna para retornar o contexto this.

mockReturnValue

• Tipo: (value: any) => MockInstance

  Recebe um valor que será retornado sempre que a função mock for chamada.

  const mock = vi.fn();
  mock.mockReturnValue(42);
  mock(); // 42
  mock.mockReturnValue(43);
  mock(); // 43

mockReturnValueOnce

• Tipo: (value: any) => MockInstance

  Recebe um valor que será retornado para uma única chamada à função mock. Se encadeado, cada chamada consecutiva retornará o valor passado. Quando não houver mais valores mockReturnValueOnce para usar, chama uma função especificada por mockImplementation ou outros métodos mockReturn*.

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

mock.calls

Este é um array contendo todos os argumentos de cada chamada. Cada item do array representa os argumentos de uma chamada específica.

const fn = vi.fn();

fn('arg1', 'arg2');
fn('arg3', 'arg4');

fn.mock.calls ===
  [
    ['arg1', 'arg2'], // primeira chamada
    ['arg3', 'arg4'], // segunda chamada
  ];

mock.lastCall

Contém os argumentos da última chamada. Se o mock não foi chamado, retornará undefined.

mock.results

Este é um array contendo todos os valores que foram retornados pela função. Cada item do array é um objeto com as propriedades type e value. Os tipos disponíveis são:

• 'return' - função retornada sem erro.
• 'throw' - função lançou um erro.

A propriedade value contém o valor retornado ou o erro lançado. Se a função retornou uma promise, quando ela for resolvida, a propriedade value se tornará o valor para o qual a promise foi resolvida.

const fn = vi.fn();

const result = fn(); // retornou 'resultado'

try {
  fn(); // disparou um Error
} catch {}

fn.mock.results ===
  [
    // primeiro resultado
    {
      type: 'return',
      value: 'result',
    },
    // último resultado
    {
      type: 'throw',
      value: Error,
    },
  ];

mock.instances

Este é um array contendo todas as instâncias que foram criadas quando o mock foi chamado com a palavra-chave new. Note que este é o contexto real (this) da função, não um valor de retorno.

WARNING

Se o mock foi criado com new MyClass(), então mock.instances será um array com um valor:

const MyClass = vi.fn();
const a = new MyClass();

MyClass.mock.instances[0] === a;

Se o construtor retornar um valor, ele não estará no array instances, mas sim em results:

const Spy = vi.fn(() => ({ method: vi.fn() }));
const a = new Spy();

Spy.mock.instances[0] !== a;
Spy.mock.results[0] === a;