Fonctions Mock

Vous pouvez créer une fonction espion (mock) pour suivre son exécution à l'aide de la méthode vi.fn. Si vous souhaitez espionner une méthode sur un objet existant, vous pouvez utiliser 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;

Il est recommandé d'utiliser les assertions d'espionnage (spy assertions) (par exemple, toHaveBeenCalled) sur expect pour vérifier le résultat de l'espionnage. Cette référence d'API décrit les propriétés et méthodes disponibles pour manipuler le comportement de l'espion.

getMockName

• Type: () => string

  Utilisez cette méthode pour obtenir le nom attribué au mock avec .mockName(name).

mockClear

• Type: () => MockInstance

  Efface toutes les informations concernant chaque appel. Après l'appel de cette méthode, spy.mock.calls et spy.mock.results renverront des tableaux vides. Ceci est utile si vous devez réinitialiser l'espion entre différentes assertions.

  Si vous souhaitez que cette méthode soit appelée automatiquement avant chaque test, vous pouvez activer l'option clearMocks dans la configuration.

mockName

• Type: (name: string) => MockInstance

  Définit le nom interne du mock. Ceci est utile pour identifier quel mock a échoué lors d'une assertion.

mockImplementation

• Type: (fn: Function) => MockInstance

  Prend une fonction qui servira d'implémentation pour le mock.

  Par exemple :

  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

• Type: (fn: Function) => MockInstance

  Accepte une fonction qui sera utilisée comme implémentation du mock pour un appel unique à la fonction simulée. Elle peut être chaînée afin que plusieurs appels de fonction produisent des résultats différents.

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

  Lorsque la fonction simulée a épuisé ses implémentations définies avec mockImplementationOnce, elle invoquera l'implémentation par défaut qui a été définie avec vi.fn(() => defaultValue) ou .mockImplementation(() => defaultValue) si ces dernières ont été appelées :

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

withImplementation

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

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

  Remplace temporairement l'implémentation du mock pendant l'exécution du callback.

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

  Peut être utilisé avec un callback asynchrone. Il est nécessaire d'attendre la fin de cette méthode pour que l'implémentation originale soit restaurée.

  test('async callback', () => {
    const myMockFn = vi.fn(() => 'original');
  
    // Nous attendons cet appel car le callback est asynchrone
    await myMockFn.withImplementation(
      () => 'temp',
      async () => {
        myMockFn(); // 'temp'
      }
    );
  
    myMockFn(); // 'original'
  });

  De plus, cette méthode est prioritaire par rapport à mockImplementationOnce.

mockRejectedValue

• Type: (value: any) => MockInstance

  Prend une valeur d'erreur qui sera rejetée lors de l'appel de la fonction asynchrone.

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

mockRejectedValueOnce

• Type: (value: any) => MockInstance

  Accepte une valeur qui sera rejetée pour un appel unique à la fonction mock. Si elle est chaînée, chaque appel consécutif rejettera la valeur transmise.

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

mockReset

• Type: () => MockInstance

  Similaire à mockClear, mais transforme également l'implémentation interne en une fonction vide (renvoyant undefined lorsqu'elle est invoquée). Ceci est utile lorsque vous souhaitez réinitialiser complètement un mock à son état initial.

  Si vous souhaitez que cette méthode soit appelée automatiquement avant chaque test, vous pouvez activer l'option mockReset dans la configuration.

mockRestore

• Type: () => MockInstance

  Effectue les actions de mockReset et restaure l'implémentation interne à la fonction d'origine.

  Notez que la restauration d'un mock créé avec vi.fn() définira l'implémentation sur une fonction vide qui renvoie undefined. La restauration d'un mock créé avec vi.fn(impl) restaurera l'implémentation à impl.

  Si vous souhaitez que cette méthode soit appelée automatiquement avant chaque test, vous pouvez activer l'option restoreMocks dans la configuration.

mockResolvedValue

• Type: (value: any) => MockInstance

  Accepte une valeur qui sera résolue lorsque la fonction asynchrone sera appelée.

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

mockResolvedValueOnce

• Type: (value: any) => MockInstance

  Accepte une valeur qui sera résolue pour un appel unique à la fonction mock. Si elle est chaînée, chaque appel consécutif résoudra la valeur transmise.

  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

• Type: () => MockInstance

  Définit l'implémentation interne pour renvoyer le contexte this.

mockReturnValue

• Type: (value: any) => MockInstance

  Accepte une valeur qui sera renvoyée à chaque appel de la fonction simulée.

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

mockReturnValueOnce

• Type: (value: any) => MockInstance

  Accepte une valeur qui sera renvoyée pour un appel unique à la fonction mock. Si elle est chaînée, chaque appel consécutif renverra la valeur transmise. Lorsqu'il n'y a plus de valeurs mockReturnValueOnce à utiliser, la fonction spécifiée par mockImplementation ou d'autres méthodes mockReturn* est appelée.

  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

C'est un tableau contenant tous les arguments de chaque appel. Chaque élément du tableau représente les arguments d'un appel spécifique.

const fn = vi.fn();

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

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

mock.lastCall

Contient les arguments du dernier appel. Si l'espion n'a pas été appelé, cette propriété renverra undefined.

mock.results

C'est un tableau contenant toutes les valeurs qui ont été returned par la fonction. Chaque élément du tableau est un objet ayant les propriétés type et value. Les types disponibles sont :

• 'return' - la fonction s'est exécutée sans erreur.
• 'throw' - la fonction a levé une erreur.

La propriété value contient la valeur renvoyée ou l'erreur levée. Si la fonction a renvoyé une promesse, lorsque celle-ci est résolue, la propriété value contiendra la valeur à laquelle la promesse s'est résolue.

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

C'est un tableau contenant toutes les instances qui ont été créées lorsque le mock a été appelé avec le mot-clé new. Notez qu'il s'agit du contexte réel (this) de la fonction, et non d'une valeur de retour.

WARNING

Si le mock a été instancié avec new MyClass(), alors mock.instances sera un tableau ne contenant qu'une seule valeur :

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

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

Si vous renvoyez une valeur depuis le constructeur, elle ne sera pas dans le tableau instances, mais plutôt dans results :

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

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