Zum Hauptinhalt springen
Version: 30.0

Das Jest-Objekt

Inoffizielle Beta-Übersetzung

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

Das jest-Objekt ist automatisch in jedem Testfile verfügbar. Die Methoden des jest-Objekts helfen beim Erstellen von Mocks und ermöglichen die Steuerung des Jest-Verhaltens. Es kann auch explizit importiert werden via import {jest} from '@jest/globals'.

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​

Module mocken​

jest.disableAutomock()​

Deaktiviert automatisches Mocking im Modullader.

Hinweis

Automatisches Mocking muss über die automock-Konfigurationsoption aktiviert sein, damit diese Methode wirkt. Weitere Details siehe Dokumentation der Konfigurationsoption.

/** @type {import('jest').Config} */
const config = {
  automock: true,
};

module.exports = config;

Nach Aufruf von disableAutomock() liefern alle require()-Aufrufe die echten Modulversionen (statt gemockter Versionen).

utils.js
export default {
  authorize: () => {
    return 'token';
  },
};
__tests__/disableAutomocking.js
import utils from '../utils';

jest.disableAutomock();

test('original implementation', () => {
  // now we have the original implementation,
  // even if we set the automocking in a jest configuration
  expect(utils.authorize()).toBe('token');
});

Nützlich, wenn deutlich weniger Abhängigkeiten gemockt werden sollen als nicht gemockt bleiben. Beispiel: Beim Testen eines Moduls mit vielen Abhängigkeiten, die als "Implementierungsdetails" betrachtet werden können, sollten diese nicht gemockt werden.

Typische "Implementierungsdetails": Sprachfeatures (z.B. Array.prototype-Methoden), Utility-Methoden (z.B. underscore, lodash) oder Bibliotheken wie React.js.

Gibt das jest-Objekt für Methodenverkettung zurück.

Tipp

Bei Verwendung von babel-jest werden Aufrufe von disableAutomock() automatisch an den Codeblockanfang verschoben. Verwende autoMockOff(), um dies explizit zu vermeiden.

jest.enableAutomock()​

Aktiviert automatisches Mocking im Modullader.

Hinweis

Details zum automatischen Mocking siehe Dokumentation der automock-Konfigurationsoption.

Beispiel:

utils.js
export default {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};
__tests__/enableAutomocking.js
jest.enableAutomock();

import utils from '../utils';

test('original implementation', () => {
  // now we have the mocked implementation,
  expect(utils.authorize._isMockFunction).toBeTruthy();
  expect(utils.isAuthorized._isMockFunction).toBeTruthy();
});

Gibt das jest-Objekt für Methodenverkettung zurück.

Tipp

Bei Verwendung von babel-jest werden Aufrufe von enableAutomock automatisch an den Codeblockanfang verschoben. Verwende autoMockOn, um dies explizit zu vermeiden.

jest.createMockFromModule(moduleName)​

Erzeugt automatisch eine gemockte Version des angegebenen Moduls.

Praktisch für manuelle Mocks, die automatisches Mocking erweitern:

utils.js
module.exports = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};
__tests__/createMockFromModule.test.js
const utils = jest.createMockFromModule('../utils');

utils.isAuthorized = jest.fn(secret => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

So behandelt createMockFromModule verschiedene Datentypen:

Function​

Erstellt eine neue Mock-Funktion ohne Parameter, die bei Aufruf undefined zurückgilt. Gilt auch für async-Funktionen.

Class​

Erstellt eine neue Klasse mit originaler Schnittstelle, aber allen gemockten Methoden und Eigenschaften.

Object​

Erstellt ein tief geklontes Objekt mit originalen Keys aber gemockten Werten.

Array​

Erstellt ein leeres neues Array (ignoriert Originalinhalt).

Primitives​

Erstellt eine neue Eigenschaft mit identischem primitiven Wert wie im Original.

Beispiel:

example.js
module.exports = {
  function: function square(a, b) {
    return a * b;
  },
  asyncFunction: async function asyncSquare(a, b) {
    const result = (await a) * b;
    return result;
  },
  class: new (class Bar {
    constructor() {
      this.array = [1, 2, 3];
    }
    foo() {}
  })(),
  object: {
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [1, 2, 3],
    },
  },
  array: [1, 2, 3],
  number: 123,
  string: 'baz',
  boolean: true,
  symbol: Symbol.for('a.b.c'),
};
__tests__/example.test.js
const example = jest.createMockFromModule('../example');

test('should run example code', () => {
  // creates a new mocked function with no formal arguments.
  expect(example.function.name).toBe('square');
  expect(example.function).toHaveLength(0);

  // async functions get the same treatment as standard synchronous functions.
  expect(example.asyncFunction.name).toBe('asyncSquare');
  expect(example.asyncFunction).toHaveLength(0);

  // creates a new class with the same interface, member functions and properties are mocked.
  expect(example.class.constructor.name).toBe('Bar');
  expect(example.class.foo.name).toBe('foo');
  expect(example.class.array).toHaveLength(0);

  // creates a deeply cloned version of the original object.
  expect(example.object).toEqual({
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [],
    },
  });

  // creates a new empty array, ignoring the original array.
  expect(example.array).toHaveLength(0);

  // creates a new property with the same primitive value as the original property.
  expect(example.number).toBe(123);
  expect(example.string).toBe('baz');
  expect(example.boolean).toBe(true);
  expect(example.symbol).toEqual(Symbol.for('a.b.c'));
});

jest.mock(moduleName, factory, options)​

Mockt ein Modul mit einer automatisch generierten Mock-Version, wenn es mit require importiert wird. factory und options sind optional. Beispiel:

banana.js
module.exports = () => 'banana';
__tests__/test.js
jest.mock('../banana');

const banana = require('../banana'); // banana will be explicitly mocked.

banana(); // will return 'undefined' because the function is auto-mocked.

Das zweite Argument kann verwendet werden, um explizit eine Modulfabrik zu definieren, die anstelle von Jests Automocking-Funktion ausgeführt wird:

jest.mock('../moduleName', () => {
  return jest.fn(() => 42);
});

// This runs the function specified as second argument to `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // Will return '42';

Bei Verwendung des factory-Parameters für ein ES6-Modul mit einem Default-Export muss die Eigenschaft __esModule: true angegeben werden. Diese wird normalerweise von Babel/TypeScript generiert, muss hier aber manuell gesetzt werden. Beim Import eines Default-Exports ist dies eine Anweisung, die Eigenschaft default vom Exportobjekt zu importieren:

import moduleName, {foo} from '../moduleName';

jest.mock('../moduleName', () => {
  return {
    __esModule: true,
    default: jest.fn(() => 42),
    foo: jest.fn(() => 43),
  };
});

moduleName(); // Will return 42
foo(); // Will return 43

Das dritte Argument kann verwendet werden, um virtuelle Mocks zu erstellen – Mocks von Modulen, die nirgendwo im System existieren:

jest.mock(
  '../moduleName',
  () => {
    /*
     * Custom implementation of a module that doesn't exist in JS,
     * like a generated module or a native module in react-native.
     */
  },
  {virtual: true},
);
Vorsicht

Das Importieren eines Moduls in einer Setup-Datei (wie unter setupFilesAfterEnv definiert) verhindert das Mocking für dieses Modul und alle von ihm importierten Module.

Module, die mit jest.mock gemockt werden, sind nur für die Datei gemockt, die jest.mock aufruft. Eine andere Datei, die das Modul importiert, erhält die originale Implementierung – selbst wenn sie nach der Testdatei ausgeführt wird, die das Modul mockt.

Gibt das jest-Objekt für Methodenverkettung zurück.

Tipp

Schreiben Sie Tests in TypeScript? Verwenden Sie den jest.Mocked-Hilfstyp oder die jest.mocked()-Hilfsfunktion, um typisierte Mock-Module zu erhalten.

jest.Mocked<Source>​

Siehe Kapitel TypeScript-Nutzung auf der Mock-Funktionen-Seite für Dokumentation.

jest.mocked(source, options?)​

Siehe Kapitel TypeScript-Nutzung auf der Mock-Funktionen-Seite für Dokumentation.

jest.unmock(moduleName)​

Weist an, dass das Modulsystem niemals eine gemockte Version des angegebenen Moduls aus require() zurückgeben soll (d.h. es soll immer das echte Modul zurückgegeben werden).

Die häufigste Nutzung dieser API ist die Spezifikation des Moduls, das ein bestimmter Test prüfen soll (und daher nicht automatisch gemockt werden soll).

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.deepUnmock(moduleName)​

Weist an, dass das Modulsystem niemals eine gemockte Version des angegebenen Moduls und seiner Abhängigkeiten zurückgeben soll.

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.doMock(moduleName, factory, options)​

Bei Verwendung von babel-jest werden mock-Aufrufe automatisch an den Anfang des Codeblocks verschoben. Verwenden Sie diese Methode, wenn Sie dieses Verhalten explizit vermeiden möchten.

Ein Beispiel, wann dies nützlich ist: wenn Sie ein Modul innerhalb derselben Datei unterschiedlich mocken möchten:

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 2);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(2);
});

Die Verwendung von jest.doMock() mit ES6-Imports erfordert zusätzliche Schritte. Gehen Sie wie folgt vor, wenn Sie require in Ihren Tests vermeiden möchten:

  • Wir müssen die Eigenschaft __esModule: true angeben (siehe jest.mock()-API für Details).

  • Statische ES6-Modulimports werden an den Dateianfang verschoben, daher müssen wir stattdessen dynamische Imports mit import() verwenden.

  • Schließlich benötigen wir eine Umgebung, die dynamische Imports unterstützt. Siehe Babel-Nutzung für die Erstkonfiguration. Fügen Sie dann das Plugin babel-plugin-dynamic-import-node oder ein Äquivalent zu Ihrer Babel-Konfiguration hinzu, um dynamische Imports in Node zu aktivieren.

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default1',
      foo: 'foo1',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default1');
    expect(moduleName.foo).toBe('foo1');
  });
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default2',
      foo: 'foo2',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default2');
    expect(moduleName.foo).toBe('foo2');
  });
});

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.dontMock(moduleName)​

Bei Verwendung von babel-jest werden Aufrufe von unmock automatisch an den Anfang des Codeblocks verschoben. Verwenden Sie diese Methode, wenn Sie dieses Verhalten explizit vermeiden möchten.

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.setMock(moduleName, moduleExports)​

Stellt explizit das Mock-Objekt bereit, das das Modulsystem für das angegebene Modul zurückgeben soll.

Gelegentlich ist der automatisch generierte Mock, den das Modulsystem normalerweise bereitstellt, für Ihre Testanforderungen nicht ausreichend. In solchen Fällen sollten Sie normalerweise einen manuellen Mock erstellen, der besser für das betreffende Modul geeignet ist. In äußerst seltenen Fällen ist jedoch selbst ein manueller Mock ungeeignet, und Sie müssen den Mock direkt in Ihrem Test aufbauen.

In diesen seltenen Szenarien können Sie mit dieser API manuell den Eintrag im Mock-Modul-Registry des Modulsystems befüllen.

Gibt das jest-Objekt für Methodenverkettung zurück.

Hinweis

Es wird empfohlen, stattdessen jest.mock() zu verwenden. Das zweite Argument der jest.mock-API ist eine Modulfabrik anstelle des erwarteten exportierten Modulobjekts.

jest.requireActual(moduleName)​

Gibt das tatsächliche Modul anstelle eines Mocks zurück und umgeht dabei alle Prüfungen, ob eine Mock-Implementierung verwendet werden sollte.

jest.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule = jest.requireActual('../myModule');

  return {
    __esModule: true, // Use it when dealing with esModules
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

const getRandom = require('../myModule').getRandom;

getRandom(); // Always returns 10

jest.requireMock(moduleName)​

Gibt ein Mock-Modul anstelle des tatsächlichen Moduls zurück und umgeht alle Prüfungen, ob das Modul normal geladen werden sollte.

jest.onGenerateMock(cb)​

Registriert eine Callback-Funktion, die aufgerufen wird, wenn Jest einen Mock für ein Modul generiert. Dieser Callback ermöglicht die Modifikation des Mocks, bevor er an Ihre Tests zurückgegeben wird.

Parameter für den Callback:

  1. modulePath: string - Der absolute Pfad zum Modul, das gemockt wird.

  2. moduleMock: T - Das von Jest generierte Mock-Objekt für das Modul. Dieses Objekt kann vor der Rückgabe modifiziert oder ersetzt werden.

Verhalten:

  • Bei mehreren über aufeinanderfolgende onGenerateMock-Aufrufe registrierten Callbacks werden diese in der Reihenfolge ihrer Registrierung aufgerufen.

  • Jeder Callback erhält die Ausgabe des vorherigen Callbacks als moduleMock. Dadurch können mehrere Transformationsebenen auf denselben Mock angewendet werden.

jest.onGenerateMock((modulePath, moduleMock) => {
  // Inspect the module name and decide how to transform the mock
  if (modulePath.includes('Database')) {
    // For demonstration, let's replace a method with our own custom mock
    moduleMock.connect = jest.fn().mockImplementation(() => {
      console.log('Connected to mock DB');
    });
  }

  // Return the (potentially modified) mock
  return moduleMock;
});

// Apply mock for module
jest.mock('./Database');

// Later in your tests
import Database from './Database';
// The `Database` mock now has any transformations applied by our callback
Hinweis

Der onGenerateMock-Callback wird nicht für manuell erstellte Mocks aufgerufen, wie:

  • Mocks im __mocks__-Ordner
  • Explizite Fabriken via jest.mock('moduleName', () => { ... })

jest.resetModules()​

Setzt die Modulregistry zurück - den Cache aller geladenen Module. Dies ist nützlich, um Module zu isolieren, deren lokaler Zustand zwischen Tests in Konflikt stehen könnte.

Beispiel:

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Both sum modules are separate "instances" of the sum module.)

Beispiel in einem Test:

beforeEach(() => {
  jest.resetModules();
});

test('works', () => {
  const sum = require('../sum');
});

test('works too', () => {
  const sum = require('../sum');
  // sum is a different copy of the sum module from the previous test.
});

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.isolateModules(fn)​

jest.isolateModules(fn) geht weiter als jest.resetModules() und erstellt eine Sandbox-Registry für Module, die innerhalb der Callback-Funktion geladen werden. Dies isoliert spezifische Module pro Test, um Konflikte im lokalen Modulzustand zu vermeiden.

let myModule;
jest.isolateModules(() => {
  myModule = require('myModule');
});

const otherCopyOfMyModule = require('myModule');

jest.isolateModulesAsync(fn)​

jest.isolateModulesAsync() entspricht jest.isolateModules(), jedoch für asynchrone Callbacks. Der Aufrufer muss den Abschluss von isolateModulesAsync mit await abwarten.

let myModule;
await jest.isolateModulesAsync(async () => {
  myModule = await import('myModule');
  // do async stuff here
});

const otherCopyOfMyModule = await import('myModule');

Mock-Funktionen​

jest.fn(implementation?)​

Gibt eine neue, unbenutzte Mock-Funktion zurück. Nimmt optional eine Mock-Implementierung entgegen.

const mockFn = jest.fn();
mockFn();
expect(mockFn).toHaveBeenCalled();

// With a mock implementation:
const returnsTrue = jest.fn(() => true);
console.log(returnsTrue()); // true;
Tipp

Weitere Details zur TypeScript-Verwendung findest du im Kapitel Mock-Funktionen.

jest.isMockFunction(fn)​

Bestimmt, ob die übergebene Funktion eine Mock-Funktion ist.

jest.replaceProperty(object, propertyKey, value)​

Ersetzt object[propertyKey] durch den angegebenen value. Die Eigenschaft muss bereits im Objekt existieren. Dieselbe Eigenschaft kann mehrfach ersetzt werden. Gibt ein Jest-ersetztes Property zurück.

Hinweis

Um Properties zu mocken, die als Getter oder Setter definiert sind, verwende stattdessen jest.spyOn(object, methodName, accessType). Um Funktionen zu mocken, verwende stattdessen jest.spyOn(object, methodName).

Tipp

Alle mit jest.replaceProperty ersetzten Properties können durch Aufruf von jest.restoreAllMocks in der afterEach-Methode auf ihre Originalwerte zurückgesetzt werden.

Beispiel:

const utils = {
  isLocalhost() {
    return process.env.HOSTNAME === 'localhost';
  },
};

module.exports = utils;

Beispieltest:

const utils = require('./utils');

afterEach(() => {
  // restore replaced property
  jest.restoreAllMocks();
});

test('isLocalhost returns true when HOSTNAME is localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});
  expect(utils.isLocalhost()).toBe(true);
});

test('isLocalhost returns false when HOSTNAME is not localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'not-localhost'});
  expect(utils.isLocalhost()).toBe(false);
});

jest.spyOn(object, methodName)​

Erstellt eine Mock-Funktion ähnlich wie jest.fn, protokolliert aber zusätzlich Aufrufe von object[methodName]. Gibt eine Jest-Mock-Funktion zurück.

Hinweis

Standardmäßig ruft jest.spyOn die ausspionierte Methode tatsächlich auf. Dieses Verhalten unterscheidet sich von den meisten anderen Test-Bibliotheken. Um die Originalfunktion zu überschreiben, kannst du jest.spyOn(object, methodName).mockImplementation(() => customImplementation) oder object[methodName] = jest.fn(() => customImplementation) verwenden.

Tipp

Da jest.spyOn einen Mock erstellt, kannst du den ursprünglichen Zustand durch Aufruf von jest.restoreAllMocks im Callback der afterEach-Hook wiederherstellen.

Beispiel:

const video = {
  play() {
    return true;
  },
};

module.exports = video;

Beispieltest:

const video = require('./video');

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

test('plays video', () => {
  const spy = jest.spyOn(video, 'play');
  const isPlaying = video.play();

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);
});

Ausspionierte Methoden und das Schlüsselwort using​

Wenn deine Codebasis "explizites Ressourcen-Management" transpiliert (z.B. bei Verwendung von TypeScript ≥ 5.2 oder dem @babel/plugin-proposal-explicit-resource-management-Plugin), kannst du spyOn mit dem Schlüsselwort using kombinieren:

test('logs a warning', () => {
  using spy = jest.spyOn(console, 'warn');
  doSomeThingWarnWorthy();
  expect(spy).toHaveBeenCalled();
});

Dieser Code ist semantisch äquivalent zu:

test('logs a warning', () => {
  let spy;
  try {
    spy = jest.spyOn(console, 'warn');
    doSomeThingWarnWorthy();
    expect(spy).toHaveBeenCalled();
  } finally {
    spy.mockRestore();
  }
});

Auf diese Weise wird dein Spy automatisch auf den Originalwert zurückgesetzt, sobald der aktuelle Codeblock verlassen wird.

Du kannst sogar noch einen Schritt weitergehen und einen Codeblock verwenden, um deinen Mock auf einen Teil deines Tests zu beschränken, ohne die Lesbarkeit zu beeinträchtigen.

test('testing something', () => {
  {
    using spy = jest.spyOn(console, 'warn');
    setupStepThatWillLogAWarning();
  }
  // here, console.warn is already restored to the original value
  // your test can now continue normally
});
Hinweis

Wenn du eine Warnung erhältst, dass Symbol.dispose nicht existiert, benötigst du möglicherweise ein Polyfill, z.B. mit diesem Code:

if (!Symbol.dispose) {
  Object.defineProperty(Symbol, 'dispose', {
    get() {
      return Symbol.for('nodejs.dispose');
    },
  });
}

jest.spyOn(object, methodName, accessType?)​

Seit Jest 22.1.0+ akzeptiert jest.spyOn ein optionales drittes Argument accessType (entweder 'get' oder 'set'), was besonders nützlich ist, um Getter bzw. Setter auszuspionieren.

Beispiel:

const video = {
  // it's a getter!
  get play() {
    return true;
  },
};

module.exports = video;

const audio = {
  _volume: false,
  // it's a setter!
  set volume(value) {
    this._volume = value;
  },
  get volume() {
    return this._volume;
  },
};

module.exports = audio;

Beispieltest:

const audio = require('./audio');
const video = require('./video');

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

test('plays video', () => {
  const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
  const isPlaying = video.play;

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);
});

test('plays audio', () => {
  const spy = jest.spyOn(audio, 'volume', 'set'); // we pass 'set'
  audio.volume = 100;

  expect(spy).toHaveBeenCalled();
  expect(audio.volume).toBe(100);
});

jest.Replaced<Source>​

Siehe Kapitel TypeScript-Verwendung auf der Mock-Funktionen-Seite für die Dokumentation.

jest.Spied<Source>​

Siehe Kapitel TypeScript-Verwendung auf der Mock-Funktionen-Seite für die Dokumentation.

jest.clearAllMocks()​

Löscht die Eigenschaften mock.calls, mock.instances, mock.contexts und mock.results aller Mocks. Entspricht dem Aufruf von .mockClear() für jede gemockte Funktion.

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.resetAllMocks()​

Setzt den Zustand aller Mocks zurück. Entspricht dem Aufruf von .mockReset() für jede gemockte Funktion.

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.restoreAllMocks()​

Stellt alle Mocks und ersetzten Eigenschaften auf ihre Originalwerte zurück. Entspricht dem Aufruf von .mockRestore() für jede gemockte Funktion und .restore() für jede ersetzte Eigenschaft. Beachte: jest.restoreAllMocks() funktioniert nur für Mocks, die mit jest.spyOn() erstellt wurden, und Eigenschaften, die mit jest.replaceProperty() ersetzt wurden. Andere Mocks müssen manuell zurückgesetzt werden.

Falsche Zeitgeber​

jest.useFakeTimers(fakeTimersConfig?)​

Weist Jest an, gefälschte Versionen der globalen Date-, Performance-, Time- und Timer-APIs zu verwenden. Die Implementierung basiert auf @sinonjs/fake-timers.

Fake-Timer ersetzen Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout() und clearTimeout() durch eine Implementierung, die ihre Zeit von der künstlichen Uhr bezieht.

In Node.js-Umgebungen werden zusätzlich process.hrtime und process.nextTick() ersetzt, in JSDOM-Umgebungen außerdem requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback() und cancelIdleCallback().

Konfigurationsoptionen:

type FakeableAPI =
  | 'Date'
  | 'hrtime'
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

type FakeTimersConfig = {
  /**
   * If set to `true` all timers will be advanced automatically by 20 milliseconds
   * every 20 milliseconds. A custom time delta may be provided by passing a number.
   * The default is `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * List of names of APIs that should not be faked. The default is `[]`, meaning
   * all APIs are faked.
   */
  doNotFake?: Array<FakeableAPI>;
  /**
   * Use the old fake timers implementation instead of one backed by `@sinonjs/fake-timers`.
   * The default is `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. The default is `Date.now()`. */
  now?: number | Date;
  /**
   * The maximum number of recursive timers that will be run when calling `jest.runAllTimers()`.
   * The default is `100_000` timers.
   */
  timerLimit?: number;
};

Der Aufruf von jest.useFakeTimers() aktiviert gefälschte Zeitgeber für alle Tests in der Datei, bis originale Timer mit jest.useRealTimers() wiederhergestellt werden.

Du kannst jest.useFakeTimers() oder jest.useRealTimers() überall aufrufen: auf oberster Ebene, innerhalb eines test-Blocks usw. Beachte, dass dies ein globaler Vorgang ist und andere Tests in derselben Datei beeinflusst. Ein erneuter Aufruf von jest.useFakeTimers() in derselben Testdatei setzt den internen Zustand (z.B. Timer-Zähler) zurück und installiert die Fake-Timer mit den angegebenen Optionen neu:

test('advance the timers automatically', () => {
  jest.useFakeTimers({advanceTimers: true});
  // ...
});

test('do not advance the timers and do not fake `performance`', () => {
  jest.useFakeTimers({doNotFake: ['performance']});
  // ...
});

test('uninstall fake timers for the rest of tests in the file', () => {
  jest.useRealTimers();
  // ...
});
Veraltete Fake-Timer

In bestimmten Fällen musst du möglicherweise die veraltete Implementierung von Fake-Timern verwenden. Dies kann wie folgt aktiviert werden (zusätzliche Optionen werden nicht unterstützt):

jest.useFakeTimers({
  legacyFakeTimers: true,
});

Veraltete Fake-Timer ersetzen setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout() und clearTimeout() durch Jest-Mockfunktionen. In Node.js-Umgebungen wird zusätzlich process.nextTick() ersetzt, in JSDOM-Umgebungen außerdem requestAnimationFrame() und cancelAnimationFrame().

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.useRealTimers()​

Weist Jest an, die originalen Implementierungen der globalen Date-, Performance-, Time- und Timer-APIs wiederherzustellen. Du kannst beispielsweise jest.useRealTimers() im afterEach-Hook aufrufen, um Timer nach jedem Test zurückzusetzen:

afterEach(() => {
  jest.useRealTimers();
});

test('do something with fake timers', () => {
  jest.useFakeTimers();
  // ...
});

test('do something with real timers', () => {
  // ...
});

Gibt das jest-Objekt für Methodenverkettung zurück.

jest.runAllTicks()​

Leert die Mikro-Task-Warteschlange (normalerweise in Node über process.nextTick angesprochen).

Wenn diese API aufgerufen wird, werden alle ausstehenden Micro-Tasks, die über process.nextTick in die Warteschlange gestellt wurden, ausgeführt. Falls diese Micro-Tasks selbst neue Micro-Tasks planen, werden diese kontinuierlich abgearbeitet, bis keine Micro-Tasks mehr in der Warteschlange vorhanden sind.

jest.runAllTimers()​

Bearbeitet sowohl die Makro-Task-Warteschlange (d.h. alle Tasks, die durch setTimeout(), setInterval() und setImmediate() in die Warteschlange gestellt wurden) als auch die Mikro-Task-Warteschlange (typischerweise in Node über process.nextTick verarbeitet).

Bei Aufruf dieser API werden alle ausstehenden Makro-Tasks und Mikro-Tasks ausgeführt. Wenn diese Tasks selbst neue Tasks planen, werden diese kontinuierlich abgearbeitet, bis keine Tasks mehr in der Warteschlange vorhanden sind.

Dies ist besonders nützlich, um setTimeouts während eines Tests synchron auszuführen und so Verhaltensweisen zu testen, die erst nach Ausführung der setTimeout()- oder setInterval()-Callbacks auftreten. Weitere Informationen finden Sie in der Dokumentation Timer Mocks.

jest.runAllTimersAsync()​

Asynchrones Äquivalent zu jest.runAllTimers(). Ermöglicht die Ausführung geplanter Promise-Callbacks, bevor die Timer gestartet werden.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.runAllImmediates()​

Bearbeitet alle Tasks, die durch setImmediate() in die Warteschlange gestellt wurden.

Hinweis

Diese Funktion ist nur bei Verwendung der Legacy-Fake-Timers-Implementierung verfügbar.

jest.advanceTimersByTime(msToRun)​

Führt ausschließlich die Makro-Task-Warteschlange aus (d.h. alle Tasks, die durch setTimeout(), setInterval() oder setImmediate() in die Warteschlange gestellt wurden).

Bei Aufruf dieser API werden alle Timer um msToRun Millisekunden vorgerückt. Alle ausstehenden "Makro-Tasks", die über setTimeout() oder setInterval() in die Warteschlange gestellt wurden und in diesem Zeitraum ausgeführt werden sollen, werden ausgeführt. Falls diese Makro-Tasks neue Makro-Tasks planen, die innerhalb desselben Zeitraums ausgeführt werden sollen, werden diese ebenfalls abgearbeitet, bis keine Makro-Tasks mehr in der Warteschlange vorhanden sind, die innerhalb von msToRun Millisekunden ausgeführt werden sollten.

jest.advanceTimersByTimeAsync(msToRun)​

Asynchrones Äquivalent zu jest.advanceTimersByTime(msToRun). Ermöglicht die Ausführung geplanter Promise-Callbacks, bevor die Timer gestartet werden.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.runOnlyPendingTimers()​

Führt ausschließlich die derzeit ausstehenden Makro-Tasks aus (d.h. nur Tasks, die bis zu diesem Zeitpunkt durch setTimeout() oder setInterval() in die Warteschlange gestellt wurden). Falls diese Tasks neue Makro-Tasks planen, werden diese neuen Tasks durch diesen Aufruf nicht ausgeführt.

Nützlich für Szenarien, in denen ein Modul einen setTimeout() plant, dessen Callback rekursiv einen weiteren setTimeout() plant (ohne jemals zu stoppen). In solchen Fällen ist es hilfreich, schrittweise im Zeitverlauf voranschreiten zu können.

jest.runOnlyPendingTimersAsync()​

Asynchrones Äquivalent zu jest.runOnlyPendingTimers(). Ermöglicht die Ausführung geplanter Promise-Callbacks, bevor die Timer gestartet werden.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.advanceTimersToNextTimer(steps)​

Stellt alle Timer um die benötigten Millisekunden vor, sodass ausschließlich die nächsten Timeouts/Intervalle ausgeführt werden.

Optional kann steps angegeben werden, um steps Anzahl der nächsten Timeouts/Intervalle auszuführen.

jest.advanceTimersToNextTimerAsync(steps)​

Asynchrone Entsprechung von jest.advanceTimersToNextTimer(steps). Ermöglicht, dass alle geplanten Promise-Callbacks ausgeführt werden, bevor die Timer ausgelöst werden.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.advanceTimersToNextFrame()​

Setzt alle Timer um die benötigten Millisekunden voran, um Callbacks auszuführen, die aktuell mit requestAnimationFrame geplant sind. advanceTimersToNextFrame() ist eine hilfreiche Methode, um Code auszuführen, der mit requestAnimationFrame geplant wurde.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.clearAllTimers()​

Entfernt alle ausstehenden Timer aus dem Timer-System.

Das bedeutet: Wenn Timer geplant wurden (aber noch nicht ausgelöst), werden sie gelöscht und haben keine Möglichkeit mehr, in Zukunft ausgeführt zu werden.

jest.getTimerCount()​

Gibt die Anzahl der Fake-Timer zurück, die noch ausgeführt werden müssen.

jest.now()​

Gibt die aktuelle Zeit in ms der Systemuhr zurück. Entspricht Date.now(), wenn echte Timer verwendet werden oder Date gemockt ist. In anderen Fällen (z.B. Legacy-Timern) kann dies nützlich sein, um eigene Mocks für Date.now(), performance.now() etc. zu implementieren.

jest.setSystemTime(now?: number | Date)​

Setzt die aktuelle Systemzeit für Fake-Timer. Simuliert eine Änderung der Systemuhr während des Programmbetriebs. Beeinflusst die aktuelle Zeit, löst aber nicht direkt Timer aus; diese werden genau wie ohne Aufruf von jest.setSystemTime() ausgelöst.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

jest.getRealSystemTime()​

Bei aktiviertem Time-Mocking wird auch Date.now() gemockt. Bei Bedarf an der echten Systemzeit können Sie diese Funktion aufrufen.

Hinweis

Diese Funktion ist nicht verfügbar, wenn die Legacy-Implementierung für Fake-Timer verwendet wird.

Verschiedenes​

jest.getSeed()​

Bei jedem Jest-Lauf wird ein zufälliger Seed-Wert generiert, den Sie in Pseudozufallszahlengeneratoren oder ähnlichem verwenden können.

Tipp

Verwenden Sie das Flag --showSeed zur Anzeige des Seeds in Testzusammenfassungen. Zum manuellen Setzen nutzen Sie das CLI-Argument --seed=<num>.

jest.isEnvironmentTornDown()​

Gibt true zurück, wenn die Testumgebung abgebaut wurde.

jest.retryTimes(numRetries, options?)​

Führt fehlgeschlagene Tests n-mal erneut aus, bis sie bestehen oder die maximale Wiederholungsanzahl erreicht ist.

jest.retryTimes(3);

test('will fail', () => {
  expect(true).toBe(false);
});

Bei aktivierter Option logErrorsBeforeRetry werden fehlerverursachende Meldungen vor Wiederholung in der Konsole protokolliert.

jest.retryTimes(3, {logErrorsBeforeRetry: true});

test('will fail', () => {
  expect(true).toBe(false);
});

waitBeforeRetry definiert die Wartezeit in Millisekunden vor Wiederholung.

jest.retryTimes(3, {waitBeforeRetry: 1000});

test('will fail', () => {
  expect(true).toBe(false);
});

retryImmediately führt fehlgeschlagene Tests direkt nach Fehler erneut aus. Ohne diese Option erfolgt die Wiederholung erst nach Abschluss aller anderen Tests in der Datei.

jest.retryTimes(3, {retryImmediately: true});

test('will fail', () => {
  expect(true).toBe(false);
});

Gibt das jest-Objekt für Methodenverkettung zurück.

Vorsicht

jest.retryTimes() muss auf oberster Ebene einer Testdatei oder in einem describe-Block deklariert werden.

Hinweis

Diese Funktion ist nur mit dem Standard-Runner jest-circus verfügbar.

jest.setTimeout(timeout)​

Legt das Standard-Zeitlimit (in Millisekunden) für alle Tests sowie Before/After-Hooks in der Testdatei fest. Dies wirkt sich nur auf die Testdatei aus, von der diese Funktion aufgerufen wird. Das Standard-Zeitlimit beträgt 5 Sekunden, wenn diese Methode nicht aufgerufen wird.

Beispiel:

jest.setTimeout(1000); // 1 second
Tipp

Um unterschiedliche Zeitlimits für verschiedene Tests in derselben Datei festzulegen, verwende die timeout-Option für einzelne Tests.

Wenn du das Zeitlimit für alle Testdateien festlegen möchtest, verwende die Konfigurationsoption testTimeout.