Mock-Funktionen

Du kannst eine Mock-Funktion erstellen, um ihre Ausführung mit der Methode vi.fn zu überwachen. Wenn du eine Methode eines bereits erstellten Objekts überwachen möchtest, kannst du die Methode vi.spyOn verwenden:

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;

Verwende Spion-Assertions (zum Beispiel toHaveBeenCalled) auf expect, um das Ergebnis der Spionagefunktion zu überprüfen. Diese API-Referenz beschreibt die verfügbaren Eigenschaften und Methoden zur Manipulation des Spy-Verhaltens.

getMockName

• Typ: () => string

  Gibt den Namen zurück, der dem Mock mit der Methode .mockName(name) zugewiesen wurde.

mockClear

• Typ: () => MockInstance

  Entfernt alle Informationen über jeden Aufruf. Nach dem Aufruf geben spy.mock.calls und spy.mock.results leere Arrays zurück. Dies ist hilfreich, wenn du den Spy zwischen verschiedenen Assertions zurücksetzen musst.

  Wenn diese Methode automatisch vor jedem Test aufgerufen werden soll, kannst du die Einstellung clearMocks in der Konfiguration aktivieren.

mockName

• Typ: (name: string) => MockInstance

  Setzt den internen Mock-Namen. Hilfreich, um festzustellen, welcher Mock die Assertion nicht bestanden hat.

mockImplementation

• Typ: (fn: Function) => MockInstance

  Erwartet eine Funktion, die als Implementierung für den Mock verwendet wird.

  Zum Beispiel:

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

• Typ: (fn: Function) => MockInstance

  Erwartet eine Funktion, die für einen einzelnen Aufruf der gemockten Funktion als Implementierung verwendet wird. Kann verkettet werden, sodass aufeinanderfolgende Funktionsaufrufe unterschiedliche Ergebnisse liefern.

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

  Wenn der gemockten Funktion die Implementierungen ausgehen, wird die Standardimplementierung aufgerufen, die mit vi.fn(() => defaultValue) oder .mockImplementation(() => defaultValue) festgelegt wurde, falls diese definiert wurden:

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

withImplementation

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

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

  Überschreibt die ursprüngliche Mock-Implementierung temporär, während der Callback ausgeführt wird.

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

  Kann auch mit asynchronen Callbacks verwendet werden. Die Methode muss mit await aufgerufen werden, um die ursprüngliche Implementierung nach dem Callback wieder zu verwenden.

  test('async callback', () => {
    const myMockFn = vi.fn(() => 'original');
  
    // Wir erwarten diesen Aufruf, da der Callback asynchron ist
    await myMockFn.withImplementation(
      () => 'temp',
      async () => {
        myMockFn(); // 'temp'
      }
    );
  
    myMockFn(); // 'original'
  });

  Außerdem hat sie Vorrang vor mockImplementationOnce.

mockRejectedValue

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der als Promise verworfen wird, wenn die asynchrone Funktion aufgerufen wird.

  const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'));
  
  await asyncMock(); // löst "Async error" aus

mockRejectedValueOnce

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der für einen einzelnen Aufruf der Mock-Funktion als Promise verworfen wird. Bei Verkettung verwirft jeder weitere Aufruf den übergebenen Wert.

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

mockReset

• Typ: () => MockInstance

  Führt dieselbe Aktion wie mockClear aus und setzt die interne Implementierung auf eine leere Funktion zurück (die bei Aufruf undefined zurückgibt). Dies ist hilfreich, wenn du einen Mock vollständig in seinen ursprünglichen Zustand zurückversetzen möchtest.

  Wenn diese Methode automatisch vor jedem Test aufgerufen werden soll, kannst du die Einstellung mockReset in der Konfiguration aktivieren.

mockRestore

• Typ: () => MockInstance

  Führt dieselbe Aktion wie mockReset aus und stellt die interne Implementierung auf die ursprüngliche Funktion wieder her.

  Beachte, dass das Wiederherstellen eines Mocks von vi.fn() die Implementierung auf eine leere Funktion setzt, die undefined zurückgibt. Das Wiederherstellen von vi.fn(impl) stellt die Implementierung auf impl wieder her.

  Wenn diese Methode automatisch vor jedem Test aufgerufen werden soll, kannst du die Einstellung restoreMocks in der Konfiguration aktivieren.

mockResolvedValue

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der als Promise aufgelöst wird, wenn die asynchrone Funktion aufgerufen wird.

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

mockResolvedValueOnce

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der für einen einzelnen Aufruf der Mock-Funktion als Promise aufgelöst wird. Bei Verkettung löst jeder weitere Aufruf den übergebenen Wert auf.

  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

• Typ: () => MockInstance

  Setzt die interne Implementierung so, dass der this-Kontext zurückgegeben wird.

mockReturnValue

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der immer dann zurückgegeben wird, wenn die Mock-Funktion aufgerufen wird.

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

mockReturnValueOnce

• Typ: (value: any) => MockInstance

  Erwartet einen Wert, der für einen einzelnen Aufruf der Mock-Funktion zurückgegeben wird. Bei Verkettung gibt jeder aufeinanderfolgende Aufruf den übergebenen Wert zurück. Wenn alle mockReturnValueOnce-Werte aufgebraucht sind, wird die Implementierung verwendet, die durch mockImplementation oder andere mockReturn*-Methoden angegeben wurde.

  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

Dies ist ein Array, das alle Argumente für jeden Aufruf enthält. Jedes Element des Arrays repräsentiert die Argumente eines einzelnen Aufrufs.

const fn = vi.fn();

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

fn.mock.calls ===
  [
    ['arg1', 'arg2'], // erster Aufruf
    ['arg3', 'arg4'], // zweiter Aufruf
  ];

mock.lastCall

Dies enthält die Argumente des letzten Aufrufs. Wenn der Spy noch nicht aufgerufen wurde, wird undefined zurückgegeben.

mock.results

Dies ist ein Array, das alle Ergebnisse enthält, die von der Funktion zurückgegeben wurden. Jedes Element des Arrays ist ein Objekt mit den Eigenschaften type und value. Verfügbare Typen sind:

• 'return' - Funktion wurde ohne Fehler beendet und hat einen Wert zurückgegeben.
• 'throw' - Funktion hat eine Ausnahme (Error) ausgelöst.

Die Eigenschaft value enthält den zurückgegebenen Wert oder die ausgelöste Ausnahme. Wenn die Funktion eine Promise zurückgegeben hat, wird die Eigenschaft value zu dem Wert, zu dem die Promise aufgelöst wurde, sobald sie aufgelöst ist.

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

Dies ist ein Array, das alle Instanzen enthält, die erstellt wurden, als der Mock mit dem Schlüsselwort new aufgerufen wurde. Beachte, dass dies der tatsächliche Kontext (this) der Funktion ist, nicht der Rückgabewert.

WARNING

Wenn ein Mock mit new MyClass() instanziiert wurde, ist mock.instances ein Array mit einem Element:

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

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

Wenn ein Konstruktor einen Wert zurückgibt, befindet sich dieser nicht im instances-Array, sondern stattdessen in results:

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

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