Zum Hauptinhalt springen
Version: 29.7

Mock-Funktionen

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Mock-Funktionen werden auch als "Spies" bezeichnet, da sie es ermöglichen, das Verhalten einer Funktion zu beobachten, die indirekt durch anderen Code aufgerufen wird, anstatt nur die Ausgabe zu testen. Du kannst eine Mock-Funktion mit jest.fn() erstellen. Wenn keine Implementierung angegeben ist, gibt die Mock-Funktion bei Aufruf undefined zurück.

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Hinweis

Die TypeScript-Beispiele auf dieser Seite funktionieren nur wie dokumentiert, wenn Sie die Jest-APIs explizit importieren:

import {expect, jest, test} from '@jest/globals';

Weitere Details zur Einrichtung von Jest mit TypeScript finden Sie im Leitfaden Erste Schritte.

Methoden​

Referenz​

mockFn.getMockName()​

Gibt den Mock-Namen-String zurück, der durch den Aufruf von .mockName() gesetzt wurde.

mockFn.mock.calls​

Ein Array, das die Aufrufargumente aller Aufrufe dieser Mock-Funktion enthält. Jedes Element im Array ist ein Array der Argumente, die während des Aufrufs übergeben wurden.

Beispiel: Eine Mock-Funktion f, die zweimal aufgerufen wurde – mit den Argumenten f('arg1', 'arg2') und dann mit f('arg3', 'arg4') – hätte ein mock.calls-Array, das so aussieht:

[
  ['arg1', 'arg2'],
  ['arg3', 'arg4'],
];

mockFn.mock.results​

Ein Array, das die Ergebnisse aller Aufrufe dieser Mock-Funktion enthält. Jeder Eintrag ist ein Objekt mit einer type-Eigenschaft und einer value-Eigenschaft. type kann einer der folgenden Werte sein:

  • 'return' - Zeigt an, dass der Aufruf durch normale Rückgabe abgeschlossen wurde.

  • 'throw' - Zeigt an, dass der Aufruf durch Werfen eines Fehlers abgeschlossen wurde.

  • 'incomplete' - Zeigt an, dass der Aufruf noch nicht abgeschlossen ist. Tritt auf, wenn du das Ergebnis innerhalb der Mock-Funktion selbst oder innerhalb einer von ihr aufgerufenen Funktion testest.

Die value-Eigenschaft enthält den zurückgegebenen oder geworfenen Wert. value ist undefined, wenn type === 'incomplete'.

Beispiel: Eine Mock-Funktion f, die dreimal aufgerufen wurde – Rückgabe von 'result1', Werfen eines Fehlers und Rückgabe von 'result2' – hätte ein mock.results-Array, das so aussieht:

[
  {
    type: 'return',
    value: 'result1',
  },
  {
    type: 'throw',
    value: {
      /* Error instance */
    },
  },
  {
    type: 'return',
    value: 'result2',
  },
];

mockFn.mock.instances​

Ein Array, das alle Objektinstanzen enthält, die mit new aus dieser Mock-Funktion instanziiert wurden.

Beispiel: Eine Mock-Funktion, die zweimal instanziiert wurde, hätte folgendes mock.instances-Array:

const mockFn = jest.fn();

const a = new mockFn();
const b = new mockFn();

mockFn.mock.instances[0] === a; // true
mockFn.mock.instances[1] === b; // true

mockFn.mock.contexts​

Ein Array, das die Kontexte aller Aufrufe der Mock-Funktion enthält.

Ein Kontext ist der this-Wert, den eine Funktion bei Aufruf erhält. Der Kontext kann mit Function.prototype.bind, Function.prototype.call oder Function.prototype.apply gesetzt werden.

Beispiel:

const mockFn = jest.fn();

const boundMockFn = mockFn.bind(thisContext0);
boundMockFn('a', 'b');
mockFn.call(thisContext1, 'a', 'b');
mockFn.apply(thisContext2, ['a', 'b']);

mockFn.mock.contexts[0] === thisContext0; // true
mockFn.mock.contexts[1] === thisContext1; // true
mockFn.mock.contexts[2] === thisContext2; // true

mockFn.mock.lastCall​

Ein Array mit den Argumenten des letzten Aufrufs dieser Mock-Funktion. Wenn die Funktion nicht aufgerufen wurde, wird undefined zurückgegeben.

Beispiel: Eine Mock-Funktion f, die zweimal aufgerufen wurde – mit den Argumenten f('arg1', 'arg2') und dann mit f('arg3', 'arg4') – hätte ein mock.lastCall-Array, das so aussieht:

['arg3', 'arg4'];

mockFn.mockClear()​

Löscht alle Informationen in den Arrays mockFn.mock.calls, mockFn.mock.instances, mockFn.mock.contexts und mockFn.mock.results. Dies ist oft nützlich, wenn du Mock-Nutzungsdaten zwischen zwei Assertions bereinigen möchtest.

Die Konfigurationsoption clearMocks ist verfügbar, um Mocks automatisch vor jedem Test zu löschen.

Vorsicht

Achtung: mockFn.mockClear() ersetzt das gesamte mockFn.mock-Objekt und setzt nicht nur die Eigenschaftswerte zurück! Vermeide daher, mockFn.mock anderen Variablen (auch temporären) zuzuweisen, um den Zugriff auf veraltete Daten zu verhindern.

mockFn.mockReset()​

Führt alle Aktionen von mockFn.mockClear() durch und ersetzt zusätzlich die Mock-Implementierung durch eine leere Funktion, die undefined zurückgibt.

Die Konfigurationsoption resetMocks ist verfügbar, um Mocks automatisch vor jedem Test zurückzusetzen.

mockFn.mockRestore()​

Führt alle Aktionen von mockFn.mockReset() durch und stellt zusätzlich die ursprüngliche (nicht-gemockte) Implementierung wieder her.

Dies ist nützlich, wenn du Funktionen in bestimmten Testfällen mocken und in anderen die Originalimplementierung verwenden möchtest.

Die Konfigurationsoption restoreMocks ist verfügbar, um Mocks automatisch vor jedem Test wiederherzustellen.

Hinweis

mockFn.mockRestore() funktioniert nur, wenn der Mock mit jest.spyOn() erstellt wurde. Bei manueller Zuweisung von jest.fn() musst du die Wiederherstellung selbst verwalten.

mockFn.mockImplementation(fn)​

Akzeptiert eine Funktion, die als Implementierung des Mocks verwendet wird. Der Mock zeichnet weiterhin alle Aufrufe und Instanzen auf – der Unterschied ist, dass die übergebene Implementierung bei Aufrufen ausgeführt wird.

Tipp

jest.fn(implementation) ist eine Kurzform für jest.fn().mockImplementation(implementation).

const mockFn = jest.fn(scalar => 42 + scalar);

mockFn(0); // 42
mockFn(1); // 43

mockFn.mockImplementation(scalar => 36 + scalar);

mockFn(2); // 38
mockFn(3); // 39

.mockImplementation() kann auch zum Mocken von Klassenkonstruktoren verwendet werden:

SomeClass.js
module.exports = class SomeClass {
  method(a, b) {}
};
SomeClass.test.js
const SomeClass = require('./SomeClass');

jest.mock('./SomeClass'); // this happens automatically with automocking

const mockMethod = jest.fn();
SomeClass.mockImplementation(() => {
  return {
    method: mockMethod,
  };
});

const some = new SomeClass();
some.method('a', 'b');

console.log('Calls to method:', mockMethod.mock.calls);

mockFn.mockImplementationOnce(fn)​

Akzeptiert eine Funktion, die für genau einen Aufruf der gemockten Funktion als Implementierung dient. Kann verkettet werden, um bei mehreren Aufrufen unterschiedliche Ergebnisse zu liefern.

const mockFn = jest
  .fn()
  .mockImplementationOnce(cb => cb(null, true))
  .mockImplementationOnce(cb => cb(null, false));

mockFn((err, val) => console.log(val)); // true
mockFn((err, val) => console.log(val)); // false

Wenn die mit .mockImplementationOnce() definierten Implementierungen aufgebraucht sind, wird die Standardimplementierung von jest.fn(() => defaultValue) oder .mockImplementation(() => defaultValue) verwendet:

const mockFn = jest
  .fn(() => 'default')
  .mockImplementationOnce(() => 'first call')
  .mockImplementationOnce(() => 'second call');

mockFn(); // 'first call'
mockFn(); // 'second call'
mockFn(); // 'default'
mockFn(); // 'default'

mockFn.mockName(name)​

Akzeptiert einen String, der in Testergebnissen anstelle von 'jest.fn()' angezeigt wird, um den Mock zu identifizieren.

Beispiel:

const mockFn = jest.fn().mockName('mockedFunction');

// mockFn();
expect(mockFn).toHaveBeenCalled();

Erzeugt diesen Fehler:

expect(mockedFunction).toHaveBeenCalled()

Expected number of calls: >= 1
Received number of calls:    0

mockFn.mockReturnThis()​

Kurzform für:

jest.fn(function () {
  return this;
});

mockFn.mockReturnValue(value)​

Kurzform für:

jest.fn().mockImplementation(() => value);

Akzeptiert einen Wert, der bei jedem Aufruf der Mock-Funktion zurückgegeben wird.

const mock = jest.fn();

mock.mockReturnValue(42);
mock(); // 42

mock.mockReturnValue(43);
mock(); // 43

mockFn.mockReturnValueOnce(value)​

Kurzform für:

jest.fn().mockImplementationOnce(() => value);

Akzeptiert einen Wert, der für genau einen Aufruf der Mock-Funktion zurückgegeben wird. Kann verkettet werden, um bei aufeinanderfolgenden Aufrufen unterschiedliche Werte zurückzugeben. Wenn keine mockReturnValueOnce-Werte mehr verfügbar sind, wird der Wert von mockReturnValue verwendet.

const mockFn = jest
  .fn()
  .mockReturnValue('default')
  .mockReturnValueOnce('first call')
  .mockReturnValueOnce('second call');

mockFn(); // 'first call'
mockFn(); // 'second call'
mockFn(); // 'default'
mockFn(); // 'default'

mockFn.mockResolvedValue(value)​

Kurzform für:

jest.fn().mockImplementation(() => Promise.resolve(value));

Praktisch zum Mocken asynchroner Funktionen in asynchronen Tests:

test('async test', async () => {
  const asyncMock = jest.fn().mockResolvedValue(43);

  await asyncMock(); // 43
});

mockFn.mockResolvedValueOnce(value)​

Kurzform für:

jest.fn().mockImplementationOnce(() => Promise.resolve(value));

Nützlich, um bei mehreren asynchronen Aufrufen unterschiedliche Werte aufzulösen:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockResolvedValue('default')
    .mockResolvedValueOnce('first call')
    .mockResolvedValueOnce('second call');

  await asyncMock(); // 'first call'
  await asyncMock(); // 'second call'
  await asyncMock(); // 'default'
  await asyncMock(); // 'default'
});

mockFn.mockRejectedValue(value)​

Kurzform für:

jest.fn().mockImplementation(() => Promise.reject(value));

Nützlich, um asynchrone Mock-Funktionen zu erstellen, die immer ablehnen:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockRejectedValue(new Error('Async error message'));

  await asyncMock(); // throws 'Async error message'
});

mockFn.mockRejectedValueOnce(value)​

Kurzform für:

jest.fn().mockImplementationOnce(() => Promise.reject(value));

Nützlich in Kombination mit .mockResolvedValueOnce() oder um bei mehreren asynchronen Aufrufen unterschiedliche Fehler auszulösen:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockResolvedValueOnce('first call')
    .mockRejectedValueOnce(new Error('Async error message'));

  await asyncMock(); // 'first call'
  await asyncMock(); // throws 'Async error message'
});

mockFn.withImplementation(fn, callback)​

Akzeptiert eine Funktion, die temporär als Implementierung des Mocks verwendet wird, während der Callback ausgeführt wird.

test('test', () => {
  const mock = jest.fn(() => 'outside callback');

  mock.withImplementation(
    () => 'inside callback',
    () => {
      mock(); // 'inside callback'
    },
  );

  mock(); // 'outside callback'
});

mockFn.withImplementation funktioniert unabhängig davon, ob der Callback asynchron ist (ein thenable zurückgibt). Bei asynchronen Callbacks wird ein Promise zurückgegeben. Das Awaiten des Promises wartet auf den Callback und setzt die Implementierung zurück.

test('async test', async () => {
  const mock = jest.fn(() => 'outside callback');

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

  mock(); // 'outside callback'
});

Ersetzte Eigenschaften​

replacedProperty.replaceValue(value)​

Ändert den Wert einer bereits ersetzten Eigenschaft. Dies ist nützlich, wenn Sie Eigenschaften ersetzen und dann den Wert in bestimmten Tests anpassen möchten. Alternativ können Sie jest.replaceProperty() mehrfach für dieselbe Eigenschaft aufrufen.

replacedProperty.restore()​

Stellt den ursprünglichen Wert der Objekteigenschaft wieder her.

Beachten Sie, dass replacedProperty.restore() nur funktioniert, wenn der Eigenschaftswert mit jest.replaceProperty() ersetzt wurde.

Die Konfigurationsoption restoreMocks steht zur Verfügung, um ersetzte Eigenschaften automatisch vor jedem Test zurückzusetzen.

TypeScript-Verwendung​

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Hinweis

Die TypeScript-Beispiele auf dieser Seite funktionieren nur wie dokumentiert, wenn Sie die Jest-APIs explizit importieren:

import {expect, jest, test} from '@jest/globals';

Weitere Details zur Einrichtung von Jest mit TypeScript finden Sie im Leitfaden Erste Schritte.

jest.fn(implementation?)​

Korrekte Mock-Typen werden abgeleitet, wenn eine Implementierung an jest.fn() übergeben wird. In vielen Fällen wird die Implementierung weggelassen. Für Typsicherheit können Sie ein generisches Typargument übergeben (siehe auch Beispiele oben):

import {expect, jest, test} from '@jest/globals';
import type add from './add';
import calculate from './calc';

test('calculate calls add', () => {
  // Create a new mock that can be used in place of `add`.
  const mockAdd = jest.fn<typeof add>();

  // `.mockImplementation()` now can infer that `a` and `b` are `number`
  // and that the returned value is a `number`.
  mockAdd.mockImplementation((a, b) => {
    // Yes, this mock is still adding two numbers but imagine this
    // was a complex function we are mocking.
    return a + b;
  });

  // `mockAdd` is properly typed and therefore accepted by anything
  // requiring `add`.
  calculate(mockAdd, 1, 2);

  expect(mockAdd).toHaveBeenCalledTimes(1);
  expect(mockAdd).toHaveBeenCalledWith(1, 2);
});

jest.Mock<T>​

Konstruiert den Typ einer Mock-Funktion, z.B. den Rückgabetyp von jest.fn(). Nützlich für die Definition rekursiver Mock-Funktionen:

import {jest} from '@jest/globals';

const sumRecursively: jest.Mock<(value: number) => number> = jest.fn(value => {
  if (value === 0) {
    return 0;
  } else {
    return value + fn(value - 1);
  }
});

jest.Mocked<Source>​

Der Utility-Typ jest.Mocked<Source> gibt den Source-Typ verpackt mit Typdefinitionen einer Jest-Mock-Funktion zurück.

import {expect, jest, test} from '@jest/globals';
import type {fetch} from 'node-fetch';

jest.mock('node-fetch');

let mockedFetch: jest.Mocked<typeof fetch>;

afterEach(() => {
  mockedFetch.mockClear();
});

test('makes correct call', () => {
  mockedFetch = getMockedFetch();
  // ...
});

test('returns correct data', () => {
  mockedFetch = getMockedFetch();
  // ...
});

Klassen-, Funktions- oder Objekttypen können als Typargument an jest.Mocked<Source> übergeben werden. Für eingeschränkte Eingabetypen nutzen Sie: jest.MockedClass<Source>, jest.MockedFunction<Source> oder jest.MockedObject<Source>.

jest.Replaced<Source>​

Der Utility-Typ jest.Replaced<Source> gibt den Source-Typ verpackt mit Typdefinitionen von Jest ersetzter Eigenschaften zurück.

src/utils.ts
export function isLocalhost(): boolean {
  return process.env['HOSTNAME'] === 'localhost';
}
src/__tests__/utils.test.ts
import {afterEach, expect, it, jest} from '@jest/globals';
import {isLocalhost} from '../utils';

let replacedEnv: jest.Replaced<typeof process.env> | undefined = undefined;

afterEach(() => {
  replacedEnv?.restore();
});

it('isLocalhost should detect localhost environment', () => {
  replacedEnv = jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});

  expect(isLocalhost()).toBe(true);
});

it('isLocalhost should detect non-localhost environment', () => {
  replacedEnv = jest.replaceProperty(process, 'env', {HOSTNAME: 'example.com'});

  expect(isLocalhost()).toBe(false);
});

jest.mocked(source, options?)​

Die mocked()-Hilfsfunktion umhüllt den source-Objekttyp und seine tief verschachtelten Member mit Mock-Funktionstypdefinitionen. Mit {shallow: true} im options-Argument deaktivieren Sie das tiefe Mock-Verhalten.

Gibt das source-Objekt zurück.

song.ts
export const song = {
  one: {
    more: {
      time: (t: number) => {
        return t;
      },
    },
  },
};
song.test.ts
import {expect, jest, test} from '@jest/globals';
import {song} from './song';

jest.mock('./song');
jest.spyOn(console, 'log');

const mockedSong = jest.mocked(song);
// or through `jest.Mocked<Source>`
// const mockedSong = song as jest.Mocked<typeof song>;

test('deep method is typed correctly', () => {
  mockedSong.one.more.time.mockReturnValue(12);

  expect(mockedSong.one.more.time(10)).toBe(12);
  expect(mockedSong.one.more.time.mock.calls).toHaveLength(1);
});

test('direct usage', () => {
  jest.mocked(console.log).mockImplementation(() => {
    return;
  });

  console.log('one more time');

  expect(jest.mocked(console.log).mock.calls).toHaveLength(1);
});

jest.Spied<Source>​

Konstruiert den Typ einer ausspionierten Klasse oder Funktion (d.h. den Rückgabetyp von jest.spyOn()).

__utils__/setDateNow.ts
import {jest} from '@jest/globals';

export function setDateNow(now: number): jest.Spied<typeof Date.now> {
  return jest.spyOn(Date, 'now').mockReturnValue(now);
}
import {afterEach, expect, type jest, test} from '@jest/globals';
import {setDateNow} from './__utils__/setDateNow';

let spiedDateNow: jest.Spied<typeof Date.now> | undefined = undefined;

afterEach(() => {
  spiedDateNow?.mockReset();
});

test('renders correctly with a given date', () => {
  spiedDateNow = setDateNow(1_482_363_367_071);
  // ...

  expect(spiedDateNow).toHaveBeenCalledTimes(1);
});

Klassen- oder Funktionstypen können als Typargument an jest.Spied<Source> übergeben werden. Für eingeschränkte Eingabetypen nutzen Sie: jest.SpiedClass<Source> oder jest.SpiedFunction<Source>.

Verwenden Sie jest.SpiedGetter<Source> oder jest.SpiedSetter<Source>, um den Typ eines ausspionierten Getters bzw. Setters zu definieren.