Mock-Funktionen

Sie können eine Mock-Funktion erstellen, um deren Ausführung mit der Methode vi.fn zu verfolgen. Wenn Sie eine Methode eines bereits existierenden Objekts verfolgen möchten, können Sie 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;

Sie sollten Mock-Assertions (z. B. toHaveBeenCalled) in Verbindung mit expect verwenden, um das Verhalten des Mocks zu überprüfen. Diese API-Referenz beschreibt die verfügbaren Eigenschaften und Methoden zur Manipulation des Mock-Verhaltens.

TIP

Die benutzerdefinierte Implementierung der Funktion in den folgenden Typen ist mit einem generischen <T> gekennzeichnet.

getMockImplementation

function getMockImplementation(): T | undefined;

Gibt die aktuelle Implementierung des Mocks zurück, falls vorhanden.

Wurde der Mock mit vi.fn erstellt, wird die bereitgestellte Funktion als Mock-Implementierung verwendet.

Wenn der Mock mit vi.spyOn erstellt wurde, wird undefined zurückgegeben, es sei denn, eine benutzerdefinierte Implementierung wurde bereitgestellt.

getMockName

function getMockName(): string;

Verwenden Sie dies, um den Namen zurückzugeben, der dem Mock mit der Methode .mockName(name) zugewiesen wurde. Standardmäßig wird vi.fn() zurückgegeben.

mockClear

function mockClear(): MockInstance<T>;

Löscht alle Informationen zu jedem Aufruf. Nach dem Aufruf kehren alle Eigenschaften auf .mock in ihren ursprünglichen Zustand zurück. Diese Methode setzt die Implementierungen nicht zurück. Sie ist nützlich, um Mocks zwischen verschiedenen Assertions zu bereinigen.

Um diese Methode vor jedem Test automatisch aufzurufen, aktivieren Sie die Einstellung clearMocks in der Konfiguration.

mockName

function mockName(name: string): MockInstance<T>;

Setzt den internen Namen des Mocks. Dies ist nützlich, um den Mock zu identifizieren, wenn eine Assertion fehlschlägt.

mockImplementation

function mockImplementation(fn: T): MockInstance<T>;

Akzeptiert eine Funktion, die als Implementierung des Mocks verwendet werden soll. TypeScript erwartet, dass die Argumente und der Rückgabetyp mit denen der ursprünglichen Funktion übereinstimmen.

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

function mockImplementationOnce(fn: T): MockInstance<T>;

Akzeptiert eine Funktion, die als Mock-Implementierung verwendet werden soll. TypeScript erwartet, dass die Argumente und der Rückgabetyp mit denen der ursprünglichen Funktion übereinstimmen. Diese Methode kann verkettet werden, um unterschiedliche Ergebnisse für mehrere Funktionsaufrufe zu erzielen.

const myMockFn = vi
  .fn()
  .mockImplementationOnce(() => true) // 1st call
  .mockImplementationOnce(() => false); // 2nd call

myMockFn(); // 1st call: true
myMockFn(); // 2nd call: false

Wenn der gemockten Funktion die Implementierungen ausgehen, wird die Standardimplementierung aufgerufen, die mit vi.fn(() => defaultValue) oder .mockImplementation(() => defaultValue) festgelegt wurde, falls diese zuvor aufgerufen 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

function withImplementation(fn: T, cb: () => void): MockInstance<T>;
function withImplementation(
  fn: T,
  cb: () => Promise<void>
): Promise<MockInstance<T>>;

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

const myMockFn = vi.fn(() => 'original');

myMockFn.withImplementation(
  () => 'temp',
  () => {
    myMockFn(); // 'temp'
  }
);

myMockFn(); // 'original'

Kann mit einem asynchronen Callback verwendet werden. Die Methode muss awaited werden, um die ursprüngliche Implementierung danach wieder verwenden zu können.

test('async callback', () => {
  const myMockFn = vi.fn(() => 'original');

  // We await this call since the callback is async
  await myMockFn.withImplementation(
    () => 'temp',
    async () => {
      myMockFn(); // 'temp'
    }
  );

  myMockFn(); // 'original'
});

Beachten Sie, dass diese Methode Vorrang vor mockImplementationOnce hat.

mockRejectedValue

function mockRejectedValue(value: unknown): MockInstance<T>;

Akzeptiert einen Fehler, der zurückgewiesen wird, wenn die asynchrone Funktion aufgerufen wird.

const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'));

await asyncMock(); // throws Error<'Async error'>

mockRejectedValueOnce

function mockRejectedValueOnce(value: unknown): MockInstance<T>;

Akzeptiert einen Wert, der beim nächsten Aufruf der Funktion zurückgewiesen wird. Bei Verkettung wird bei jedem weiteren Aufruf der angegebene Wert zurückgewiesen.

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

await asyncMock(); // 'first call'
await asyncMock(); // throws Error<'Async error'>

mockReset

function mockReset(): MockInstance<T>;

Führt die gleichen Aktionen wie mockClear aus und setzt die interne Implementierung auf eine leere Funktion (die undefined zurückgibt, wenn sie aufgerufen wird). Dies setzt auch alle "once"-Implementierungen zurück. Es ist nützlich, um einen Mock vollständig auf seinen Standardzustand zurückzusetzen.

Um diese Methode automatisch vor jedem Test aufzurufen, aktivieren Sie die Einstellung mockReset in der Konfiguration.

mockRestore

function mockRestore(): MockInstance<T>;

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

Beachten Sie, dass beim Wiederherstellen eines mit vi.fn() erstellten Mocks die Implementierung auf eine leere Funktion zurückgesetzt wird, die undefined zurückgibt. Das Wiederherstellen eines mit vi.fn(impl) erstellten Mocks stellt die Implementierung auf impl wieder her.

Um diese Methode automatisch vor jedem Test aufzurufen, aktivieren Sie die Einstellung restoreMocks in der Konfiguration.

mockResolvedValue

function mockResolvedValue(value: Awaited<ReturnType<T>>): MockInstance<T>;

Akzeptiert einen Wert, der aufgelöst wird, wenn die asynchrone Funktion aufgerufen wird. TypeScript lässt nur Werte zu, die dem Rückgabetyp der ursprünglichen Funktion entsprechen.

const asyncMock = vi.fn().mockResolvedValue(42);

await asyncMock(); // 42

mockResolvedValueOnce

function mockResolvedValueOnce(value: Awaited<ReturnType<T>>): MockInstance<T>;

Akzeptiert einen Wert, der beim nächsten Funktionsaufruf aufgelöst wird. TypeScript lässt nur Werte zu, die dem Rückgabetyp der ursprünglichen Funktion entsprechen. Bei Verkettung wird bei jedem weiteren Aufruf der angegebene Wert aufgelöst.

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

function mockReturnThis(): MockInstance<T>;

Verwenden Sie dies, wenn Sie den this-Kontext von der Methode zurückgeben müssen, ohne die tatsächliche Implementierung aufzurufen. Dies ist eine Abkürzung für:

spy.mockImplementation(function () {
  return this;
});

mockReturnValue

function mockReturnValue(value: ReturnType<T>): MockInstance<T>;

Akzeptiert einen Wert, der zurückgegeben wird, wenn die Mock-Funktion aufgerufen wird. TypeScript lässt nur Werte zu, die dem Rückgabetyp der ursprünglichen Funktion entsprechen.

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

mockReturnValueOnce

function mockReturnValueOnce(value: ReturnType<T>): MockInstance<T>;

Akzeptiert einen Wert, der zurückgegeben wird, wenn die Mock-Funktion aufgerufen wird. TypeScript lässt nur Werte zu, die dem Rückgabetyp der ursprünglichen Funktion entsprechen.

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

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

const calls: Parameters<T>[];

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');

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

mock.lastCall

const lastCall: Parameters<T> | undefined;

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

mock.results

interface MockResultReturn<T> {
  type: 'return';
  /**
   * The value that was returned from the function.
   * If function returned a Promise, then this will be a resolved value.
   */
  value: T;
}

interface MockResultIncomplete {
  type: 'incomplete';
  value: undefined;
}

interface MockResultThrow {
  type: 'throw';
  /**
   * An error that was thrown during function execution.
   */
  value: any;
}

type MockResult<T> =
  | MockResultReturn<T>
  | MockResultThrow
  | MockResultIncomplete;

const results: MockResult<ReturnType<T>>[];

Dies ist ein Array, das die Ergebnisse aller Funktionsaufrufe enthält. Jedes Element des Arrays ist ein Objekt mit den Eigenschaften type und value. Verfügbare Typen sind:

• 'return' - Die Funktion wurde erfolgreich beendet und hat einen Wert zurückgegeben.
• 'throw' - Die Funktion hat einen Fehler geworfen.

Die Eigenschaft value enthält den zurückgegebenen Wert oder den geworfenen Fehler. Wenn die Funktion ein Promise zurückgegeben hat, ist result immer 'return', auch wenn das Promise zurückgewiesen wurde.

const fn = vi
  .fn()
  .mockReturnValueOnce('result')
  .mockImplementationOnce(() => {
    throw new Error('thrown error');
  });

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.settledResults

interface MockSettledResultFulfilled<T> {
  type: 'fulfilled';
  value: T;
}

interface MockSettledResultRejected {
  type: 'rejected';
  value: any;
}

export type MockSettledResult<T> =
  | MockSettledResultFulfilled<T>
  | MockSettledResultRejected;

const settledResults: MockSettledResult<Awaited<ReturnType<T>>>[];

Ein Array, das die Ergebnisse aller Funktionsaufrufe enthält, nachdem Promises aufgelöst oder zurückgewiesen wurden.

Dieses Array ist leer, wenn die Funktion nie aufgelöst oder zurückgewiesen wurde.

const fn = vi.fn().mockResolvedValueOnce('result');

const result = fn();

fn.mock.settledResults === [];

await result;

fn.mock.settledResults ===
  [
    {
      type: 'fulfilled',
      value: 'result',
    },
  ];

mock.invocationCallOrder

const invocationCallOrder: number[];

Diese Eigenschaft gibt die Reihenfolge der Ausführung der Mock-Funktion zurück. Es ist ein Array von Zahlen, die zwischen allen definierten Mocks geteilt werden.

const fn1 = vi.fn();
const fn2 = vi.fn();

fn1();
fn2();
fn1();

fn1.mock.invocationCallOrder === [1, 3];
fn2.mock.invocationCallOrder === [2];

mock.contexts

const contexts: ThisParameterType<T>[];

Diese Eigenschaft enthält ein Array der this-Kontexte, die bei jedem Aufruf der Mock-Funktion verwendet wurden.

const fn = vi.fn();
const context = {};

fn.apply(context);
fn.call(context);

fn.mock.contexts[0] === context;
fn.mock.contexts[1] === context;

mock.instances

const instances: ReturnType<T>[];

Diese Eigenschaft ist ein Array, das alle Instanzen enthält, die erstellt wurden, als der Mock mit dem Schlüsselwort new aufgerufen wurde. Beachten Sie, dass dies der tatsächliche this-Kontext der Funktion ist, nicht ein Rückgabewert.

WARNING

Wurde der Mock mit new MyClass() instanziiert, ist mock.instances ein Array mit einem Wert:

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

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

Falls der Konstruktor einen Wert zurückgibt, wird dieser nicht im instances-Array, sondern stattdessen in results enthalten sein:

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

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