Funzioni Mock

Puoi creare una funzione mock (spia) per monitorarne l'esecuzione tramite il metodo vi.fn. Se desideri tracciare un metodo su un oggetto esistente, puoi usare il metodo 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;

Dovresti utilizzare asserzioni sulle spie (ad esempio, toHaveBeenCalled) su expect per verificare il risultato della spia. Questo riferimento API descrive le proprietà e i metodi disponibili per manipolare il comportamento della spia.

getMockName

• Tipo: () => string

  Usalo per restituire il nome assegnato al mock con il metodo .mockName(name).

mockClear

• Tipo: () => MockInstance

  Elimina tutte le informazioni relative a ogni chiamata. Dopo averlo chiamato, spy.mock.calls e spy.mock.results restituiranno array vuoti. È utile se hai bisogno di resettare la spia tra diverse asserzioni.

  Se vuoi che questo metodo venga chiamato automaticamente prima di ogni test, puoi abilitare l'impostazione clearMocks nella configurazione.

mockName

• Tipo: (name: string) => MockInstance

  Imposta il nome interno del mock. Utile per identificare quale mock ha fallito l'asserzione.

mockImplementation

• Tipo: (fn: Function) => MockInstance

  Accetta una funzione che sarà utilizzata come implementazione del mock.

  Per esempio:

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

  Accetta una funzione che verrà utilizzata come implementazione del mock per una singola chiamata alla funzione mockata. Può essere concatenata in modo che più chiamate di funzione producano risultati diversi.

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

  Quando la funzione mockata esaurisce le implementazioni una tantum, verrà invocata l'implementazione predefinita impostata con vi.fn(() => defaultValue) o .mockImplementation(() => defaultValue), se precedentemente definite:

  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>

  Sovrascrive temporaneamente l'implementazione originale del mock mentre la callback è in esecuzione.

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

  Può essere usato con una callback asincrona. È necessario attendere il completamento del metodo per poter riutilizzare l'implementazione originale.

  test('async callback', () => {
    const myMockFn = vi.fn(() => 'original');
  
    // Attendiamo questa chiamata poiché la callback è asincrona
    await myMockFn.withImplementation(
      () => 'temp',
      async () => {
        myMockFn(); // 'temp'
      }
    );
  
    myMockFn(); // 'original'
  });

  Inoltre, ha la precedenza su mockImplementationOnce.

mockRejectedValue

• Tipo: (value: any) => MockInstance

  Accetta un errore che verrà rifiutato quando la funzione asincrona verrà chiamata.

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

mockRejectedValueOnce

• Tipo: (value: any) => MockInstance

  Accetta un valore che verrà rifiutato per una singola chiamata alla funzione mock. Se concatenato, ogni chiamata consecutiva rifiuterà il valore passato.

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

mockReset

• Tipo: () => MockInstance

  Si comporta come mockClear e trasforma l'implementazione interna in una funzione vuota (che restituisce undefined quando invocata). Questo è utile quando vuoi resettare completamente un mock al suo stato iniziale.

  Se vuoi che questo metodo venga chiamato automaticamente prima di ogni test, puoi abilitare l'impostazione mockReset nella configurazione.

mockRestore

• Tipo: () => MockInstance

  Fa quello che fa mockReset e ripristina l'implementazione interna alla funzione originale.

  Si noti che il ripristino del mock da vi.fn() imposterà l'implementazione a una funzione vuota che restituisce undefined. Il ripristino di un vi.fn(impl) ripristinerà l'implementazione a impl.

  Se vuoi che questo metodo venga chiamato automaticamente prima di ogni test, puoi abilitare l'impostazione restoreMocks nella configurazione.

mockResolvedValue

• Tipo: (value: any) => MockInstance

  Accetta un valore che verrà risolto, quando la funzione asincrona verrà chiamata.

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

mockResolvedValueOnce

• Tipo: (value: any) => MockInstance

  Accetta un valore che verrà risolto per una singola chiamata alla funzione mock. Se concatenato, ogni chiamata consecutiva risolverà il valore passato.

  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

  Imposta l'implementazione interna per restituire il contesto this.

mockReturnValue

• Tipo: (value: any) => MockInstance

  Accetta un valore che verrà restituito ogni volta che la funzione mock viene chiamata.

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

mockReturnValueOnce

• Tipo: (value: any) => MockInstance

  Accetta un valore che verrà restituito per una singola chiamata alla funzione mock. Se concatenato, ogni chiamata consecutiva restituirà il valore passato. Quando non ci sono più valori mockReturnValueOnce da usare, viene chiamata una funzione specificata da mockImplementation o altri metodi 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

Questo è un array contenente tutti gli argomenti per ogni chiamata alla funzione mock. Ogni elemento dell'array contiene gli argomenti di una singola chiamata.

const fn = vi.fn();

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

fn.mock.calls ===
  [
    ['arg1', 'arg2'], // first call
    ['arg3', 'arg4'], // second call
  ];

mock.lastCall

Questo contiene gli argomenti dell'ultima chiamata alla funzione mock. Se la spia non è stata chiamata, restituirà undefined.

mock.results

Questo è un array che contiene tutti i risultati restituiti dalla funzione mock. Un elemento dell'array è un oggetto con le proprietà type e value. I tipi disponibili sono:

• 'return' - la funzione ha terminato l'esecuzione senza generare eccezioni.
• 'throw' - la funzione ha lanciato un'eccezione.

La proprietà value contiene il valore restituito o l'errore lanciato. Se la funzione ha restituito una promise, quando si risolve la proprietà value diventerà il valore a cui la promise si è risolta.

const fn = vi.fn();

const result = fn(); // returned 'result'

try {
  fn(); // threw Error
} catch {}

fn.mock.results ===
  [
    // first result
    {
      type: 'return',
      value: 'result',
    },
    // last result
    {
      type: 'throw',
      value: Error,
    },
  ];

mock.instances

Questo è un array contenente tutte le istanze create quando il mock è stato invocato con la parola chiave new. Si noti che questo rappresenta il contesto corrente (this) della funzione, non il valore restituito.

WARNING

Se il mock è stato istanziato con new MyClass(), allora mock.instances sarà un array con un valore:

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

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

Se il costruttore restituisce un valore, questo non sarà presente nell'array instances, bensì in results:

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

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