Version : Suivant

L'objet Jest

L'objet jest est automatiquement dans la portée dans chaque fichier de test. Les méthodes de l'objet jest aident à créer des simulations et vous permettent de contrôler le comportement global de Jest. Il peut également être importé explicitement par import {jest} from '@jest/globals'.

info

Les exemples TypeScript de cette page ne fonctionneront comme documenté que si vous importez explicitement les API Jest :

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

Veuillez consulter le guide Premiers pas pour plus de détails sur la façon de configurer Jest avec TypeScript.

Modules simulés

`jest.disableAutomock()`

Désactive la simulation automatique dans le chargeur de module.

info

Automatic mocking should be enabled via automock configuration option for this method to have any effect. Also see documentation of the configuration option for more details.

JavaScript
TypeScript

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

module.exports = config;

import type {Config} from 'jest';

const config: Config = {
  automock: true,
};

export default config;

After disableAutomock() is called, all require()s will return the real versions of each module (rather than a mocked version).

utils.js
export default {
  authorize: () => {
    return 'token';
  },
};

__tests__/disableAutomocking.js
import utils from '../utils';

jest.disableAutomock();

test('original implementation', () => {
  // maintenant nous avons l'implémentation originale,
  // même si nous définissons l'auto-simulation dans une configuration de jest
  expect(utils.authorize()).toBe('token');
});

Cela est généralement utile lorsque le nombre de dépendances que vous souhaitez simuler est bien inférieur au nombre de dépendances que vous ne souhaitez pas. Par exemple, si vous écrivez un test pour un module qui utilise un grand nombre de dépendances qui peuvent être raisonnablement classées comme des « détails d'implémentation » du module, alors vous ne voulez probablement pas les simuler.

Examples of dependencies that might be considered "implementation details" are things ranging from language built-ins (e.g. Array.prototype methods) to highly common utility methods (e.g. underscore, lodash, array utilities, etc) and entire libraries like React.js.

Renvoie l'objet jest pour le chaînage.

astuce

When using babel-jest, calls to disableAutomock() will automatically be hoisted to the top of the code block. Use autoMockOff() if you want to explicitly avoid this behavior.

`jest.enableAutomock()`

Active la simulation automatique dans le chargeur de module.

info

For more details on automatic mocking see documentation of automock configuration option.

Exemple :

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

__tests__/enableAutomocking.js
jest.enableAutomock();

import utils from '../utils';

test('original implementation', () => {
  // maintenant nous avons l'implémentation simulée,
  expect(utils.authorize._isMockFunction).toBeTruthy();
  expect(utils.isAuthorized._isMockFunction).toBeTruthy();
});

Renvoie l'objet jest pour le chaînage.

astuce

Lorsque vous utilisez babel-jest, les appels à enableAutomock seront automatiquement remontés en haut du bloc de code. Utilisez autoMockOn si vous voulez éviter explicitement ce comportement.

`jest.createMockFromModule(moduleName)`

Avec le nom d'un module, utilisez le système de simulation automatique pour générer pour vous une version simulée du module.

This is useful when you want to create a manual mock that extends the automatic mock's behavior:

JavaScript
TypeScript

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

utils.ts
export const utils = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: (secret: string) => secret === 'wizard',
};

__tests__/createMockFromModule.test.ts
const {utils} =
  jest.createMockFromModule<typeof import('../utils')>('../utils');

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

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

Voici comment createMockFromModule simulera les types de données suivants :

`Fonction`

Creates a new mock function. La nouvelle fonction n'a pas de paramètres formels et lorsqu'elle est appelée, retournera undefined. Cette fonctionnalité s'applique également aux fonctions async.

`Classe`

Crée une nouvelle classe. L'interface de la classe originale est maintenue, toutes les fonctions et propriétés des membres de la classe seront simulées.

`Objet`

Crée un nouvel objet profondément cloné. Les clés de l'objet sont maintenues et leurs valeurs sont simulées.

`Tableau`

Crée un nouveau tableau vide, ignorant l'original.

`Primitives`

Crée une nouvelle propriété avec la même valeur primitive que la propriété originale.

Exemple :

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: [],
    },
  });

  // crée un nouveau tableau vide, ignorant le tableau original.
  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)`

Simule un module avec une version simulée automatiquement lorsqu'il est exigé. factory et options sont facultatifs. Par exemple :

banana.js
module.exports = () => 'banana';

__tests__/test.js
jest.mock('../banana');

const banana = require('../banana'); // banana sera explicitement simulée.

banana(); // retournera 'undefined' parce que la fonction est auto-simulée.

Le second argument peut être utilisé pour spécifier une factory de modules explicite qui est exécutée au lieu d'utiliser la fonctionnalité de simulation automatique de Jest :

JavaScript
TypeScript

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

// Exécute la fonction spécifiée comme second argument de `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // retournera '42';

// The optional type argument provides typings for the module factory
jest.mock<typeof import('../moduleName')>('../moduleName', () => {
  return jest.fn(() => 42);
});

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

Lors de l'utilisation du paramètre factory pour un module ES6 avec une exportation par défaut, la propriété __esModule : true doit être spécifiée. Cette propriété est normalement générée par Babel / TypeScript, mais ici elle doit être définie manuellement. Lors de l'importation d'une exportation par défaut, c'est une instruction pour importer la propriété nommée default de l'objet d'exportation :

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

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

moduleName(); // Retournera 42
foo(); // Retournera 43

Le troisième argument peut être utilisé pour créer des simulations virtuels - des simulations de modules qui n'existent nulle part dans le système :

jest.mock(
  '../moduleName',
  () => {
    /*
     * Implémentation personnalisée d'un module qui n'existe pas en JS,
     * comme un module généré ou un module natif dans react-native.
     */
  },
  {virtual: true},
);

attention

Importing a module in a setup file (as specified by setupFilesAfterEnv) will prevent mocking for the module in question, as well as all the modules that it imports.

Les modules qui sont simulés avec jest.mock ne sont simulés que pour le fichier qui appelle jest.mock. Un autre fichier qui importe le module obtiendra l'implémentation originale même s'il est exécuté après le fichier de test qui simule le module.

Renvoie l'objet jest pour le chaînage.

astuce

Écriture des tests en TypeScript ? Use the jest.Mocked utility type or the jest.mocked() helper method to have your mocked modules typed.

`jest.Mocked<Source>`

See TypeScript Usage chapter of Mock Functions page for documentation.

`jest.mocked(source, options?)`

See TypeScript Usage chapter of Mock Functions page for documentation.

`jest.unmock(moduleName)`

Indique que le système de modules ne doit jamais retourner une version simulée du module spécifié à partir de require() (par exemple, qu'il doit toujours retourner le module réel).

L'utilisation la plus fréquente de cette API est de spécifier le module qu'un test donné a l'intention de tester (et donc ne veut pas être automatiquement simulé).

Renvoie l'objet jest pour le chaînage.

`jest.deepUnmock(moduleName)`

Indicates that the module system should never return a mocked version of the specified module and its dependencies.

Renvoie l'objet jest pour le chaînage.

`jest.doMock(moduleName, factory, options)`

Lorsque vous utilisez babel-jest, les appels à mock seront automatiquement remontés en haut du bloc de code. Utilisez cette méthode si vous voulez éviter explicitement ce comportement.

Un exemple où cela est utile est lorsque vous voulez simuler un module différemment dans le même fichier :

JavaScript
TypeScript

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

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

test('moduleName 1', () => {
  // The optional type argument provides typings for the module factory
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

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

L'utilisation de jest.doMock() avec les importations ES6 nécessite des étapes supplémentaires. Suivez-les si vous ne voulez pas utiliser require dans vos tests :

Nous devons spécifier la propriété __esModule : true (voir l'API de jest.mock() pour plus d'informations).
Les importations de modules statiques ES6 sont hissées en haut du fichier, donc à la place nous devons les importer dynamiquement en utilisant import().
Enfin, nous avons besoin d'un environnement qui soutienne l'importation dynamique. Veuillez consulter Utilisation de Babel pour la configuration initiale. Ensuite, ajoutez le plugin babel-plugin-dynamic-import-node, ou un équivalent, à votre configuration Babel pour activer l'importation dynamique dans Node.

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

Renvoie l'objet jest pour le chaînage.

`jest.dontMock(moduleName)`

Lorsque vous utilisez babel-jest, les appels à unmock seront automatiquement remontés en haut du bloc de code. Utilisez cette méthode si vous voulez éviter explicitement ce comportement.

Renvoie l'objet jest pour le chaînage.

`jest.setMock(moduleName, moduleExports)`

Fournit explicitement l'objet simulé que le système de module doit retourner pour le module spécifié.

Il arrive parfois que la simulation générée automatiquement par le système de modules ne soit pas suffisante pour vos besoins de test. Normalement, dans ces circonstances, vous devriez écrire une simulation manuelle qui est plus adéquate pour le module en question. Cependant, en de très rares occasions, même une simulation manuelle n'est pas adaptée à vos besoins et vous devez construire la simulation vous-même dans votre test.

Dans ces rares cas, vous pouvez utiliser cette API pour remplir manuellement l'emplacement dans le registre des modules fictifs du système de modules.

Renvoie l'objet jest pour le chaînage.

info

It is recommended to use jest.mock() instead. Le deuxième argument de l'API jest.mock est une factory de module plutôt que l'objet module exporté attendu.

`jest.requireActual(moduleName)`

Renvoie le module réel au lieu d'une simulation, en contournant toutes les vérifications pour savoir si le module doit recevoir une implémentation simulée ou non.

JavaScript
TypeScript

jest.mock('../myModule', () => {
  // Nécessite que le module original ne soit pas simulé...
  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.mock('../myModule', () => {
  // Nécessite que le module original ne soit pas simulé...
  const originalModule =
    jest.requireActual<typeof import('../myModule')>('../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)`

Renvoie un module simulé au lieu du module réel, en contournant toutes les vérifications pour savoir si le module doit être requis normalement ou non.

`jest.resetModules()`

Réinitialise le registre des modules - le cache de tous les modules requis. Ceci est utile pour isoler les modules où l'état local peut entrer en conflit entre les tests.

Exemple :

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Les deux modules sum sont des « instances » distinctes du module sum.)

Exemple dans un test :

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

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

test('fonctionne aussi', () => {
  const sum = require('../sum');
  // sum est une copie différente du module sum du test précédent.
});

Renvoie l'objet jest pour le chaînage.

`jest.isolateModules(fn)`

jest.isolateModules(fn) va un peu plus loin que jest.resetModules() et crée un registre de type bac à sable pour les modules qui sont chargés à l'intérieur de la fonction callback. Ceci est utile pour isoler les modules spécifiques pour chaque test afin que l'état du module local n'entre pas en conflit entre les tests.

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

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync() is the equivalent of jest.isolateModules(), but for async callbacks. The caller is expected to await the completion of isolateModulesAsync.

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

const otherCopyOfMyModule = await import('myModule');

Fonctions simulées

`jest.fn(implementation?)`

Retourne une nouvelle fonction simulée non utilisée. En option, prend une implémentation simulée.

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

// Avec une implémentation simulée :
const returnsTrue = jest.fn(() => true);
console.log(returnsTrue()); // true;

astuce

See the Mock Functions page for details on TypeScript usage.

`jest.isMockFunction(fn)`

Détermine si la fonction donnée est une fonction simulée.

`jest.replaceProperty(object, propertyKey, value)`

Replace object[propertyKey] with a value. The property must already exist on the object. The same property might be replaced multiple times. Returns a Jest replaced property.

remarque

To mock properties that are defined as getters or setters, use jest.spyOn(object, methodName, accessType) instead. To mock functions, use jest.spyOn(object, methodName) instead.

astuce

All properties replaced with jest.replaceProperty could be restored to the original value by calling jest.restoreAllMocks on afterEach method.

Exemple :

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

module.exports = utils;

Exemple de test :

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)`

Crée une fonction simulée similaire à jest.fn mais qui surveille également les appels à objet[methodName]. Retourne une fonction simulée de Jest.

remarque

Par défaut, jest.spyOn appelle également la méthode spied. Ceci est un comportement différent de la plupart des autres bibliothèques de test. If you want to overwrite the original function, you can use jest.spyOn(object, methodName).mockImplementation(() => customImplementation) or object[methodName] = jest.fn(() => customImplementation).

astuce

Since jest.spyOn is a mock, you could restore the initial state by calling jest.restoreAllMocks in the body of the callback passed to the afterEach hook.

Exemple :

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

module.exports = video;

Exemple de test :

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

afterEach(() => {
  // restaure l'espion créé avec spyOn
  jest.restoreAllMocks();
});

test('lit la vidéo', () => {
  const spy = jest.spyOn(video, 'play');
  const isPlaying = video.play();

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

Spied methods and the `using` keyword

If your codebase is set up to transpile the "explicit resource management" (e.g. if you are using TypeScript >= 5.2 or the @babel/plugin-proposal-explicit-resource-management plugin), you can use spyOn in combination with the using keyword:

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

That code is semantically equal to

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

That way, your spy will automatically be restored to the original value once the current code block is left.

You can even go a step further and use a code block to restrict your mock to only a part of your test without hurting readability.

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

remarque

If you get a warning that Symbol.dispose does not exist, you might need to polyfill that, e.g. with this code:

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

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

Depuis Jest 22.1.0+, la méthode jest.spyOn prend un troisième argument optionnel de type accessType qui peut être soit 'get' ou 'set', qui s'avère utile lorsque vous voulez espionner respectivement un getter ou un setter.

Exemple :

const video = {
  // c'est un getter !
  get play() {
    return true;
  },
};

module.exports = video;

const audio = {
  _volume: false,
  // c'est un setter !
  set volume(value) {
    this._volume = value;
  },
  get volume() {
    return this._volume;
  },
};

module.exports = audio;

Exemple de test :

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

afterEach(() => {
  // restaure l'espion créé avec spyOn
  jest.restoreAllMocks();
});

test('lit la vidéo', () => {
  const spy = jest.spyOn(video, 'play', 'get'); // nous passons 'get'
  const isPlaying = video.play;

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

test('lit l\'audio', () => {
  const spy = jest.spyOn(audio, 'volume', 'set'); // nous passons 'set'
  audio.volume = 100;

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

`jest.Replaced<Source>`

See TypeScript Usage chapter of Mock Functions page for documentation.

`jest.Spied<Source>`

See TypeScript Usage chapter of Mock Functions page for documentation.

`jest.clearAllMocks()`

Efface les propriétés mock.calls, mock.instances, mock.contexts et mock.results de toutes les simulations. Equivalent aux appels de .mockClear() sur chaque fonction simulée.

Renvoie l'objet jest pour le chaînage.

`jest.resetAllMocks()`

Réinitialise l'état de toutes les simulations. Equivalent aux appels de .mockReset() sur chaque fonction simulée.

Renvoie l'objet jest pour le chaînage.

`jest.restoreAllMocks()`

Restores all mocks and replaced properties back to their original value. Equivalent to calling .mockRestore() on every mocked function and .restore() on every replaced property. Beware that jest.restoreAllMocks() only works for mocks created with jest.spyOn() and properties replaced with jest.replaceProperty(); other mocks will require you to manually restore them.

Faux temporisateurs

`jest.useFakeTimers(fakeTimersConfig?)`

Indique à Jest d'utiliser des versions fictives des API globales de date, de performance, de temps et de temporisation. L'implémentation des faux temporisateurs est garantie par @sinonjs/fake-timers.

Les faux temporisateurs vont remplacer Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() avec une implémentation qui obtient son heure à partir d'une horloge factice.

Dans l'environnement Node process.hrtime, process.nextTick() et dans l'environnement JSDOM requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() seront également remplacés.

Options de configuration :

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

type FakeTimersConfig = {
  /**
   * Si défini à `true` tous les temporisateurs seront automatiquement avancés de 20 millisecondes
   * toutes les 20 millisecondes. Un delta de temps personnalisé peut être fourni en passant un nombre.
   * La valeur par défaut est `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * Liste des noms des APIs qui ne doivent pas être falsifiés. La valeur par défaut est `[]`, ce qui signifie que
   * toutes les APIs sont falsifiées.
   */
  doNotFake?: Array<FakeableAPI>;
  /**
   * Utilise l'ancienne implémentation des faux temporisateurs au lieu de celle supportée par `@sinonjs/fake-timers`.
   * La valeur par défaut est `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. La valeur par défaut est `Date.now()`. */
  now?: number | Date;
  /**
   * Le nombre maximum de temporisateurs récursifs qui seront exécutés lors de l'appel de `jest.runAllTimers()`.
   * La valeur par défaut est `100_000` temporisateurs.
   */
  timerLimit?: number;
};

L'appel de jest.useFakeTimers() utilisera des faux temporisateurs pour tous les tests du fichier, jusqu'à ce que les temporisateurs originaux soient restaurés avec jest.useRealTimers().

Vous pouvez appeler jest.useFakeTimers() ou jest.useRealTimers() de n'importe où : niveau supérieur, à l'intérieur d'un bloc test, etc. Gardez à l'esprit qu'il s'agit d'une opération globale et affectera les autres tests dans le même fichier. L'appel de jest.useFakeTimers() une fois de plus dans le même fichier de test réinitialiserait l'état interne (par exemple le nombre de temporisateurs) et réinstallerait les faux temporisateurs en utilisant les options fournies :

test('avance les minuteurs automatiquement', () => {
  jest.useFakeTimers({advanceTimers: true});
  // ...
});

test('n\'avance pas les temporisateurs et ne fausse pas `performance`', () => {
  jest.useFakeTimers({doNotFake: ['performance']});
  // ...
});

test('désinstalle les faux temporisateurs pour le reste des tests dans le fichier', () => {
  jest.useRealTimers();
  // ...
});

Les anciens faux temporisateurs

Pour certaines raisons, il se peut que vous deviez utiliser une ancienne implémentation de faux temporisateurs. Elle peut être activée comme ceci (les options supplémentaires ne sont pas supportées) :

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

Les anciens faux temporisateurs vont remplacer setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() avec les fonctions simulées de Jest. Dans l'environnement Node process.nextTick() et dans l'environnement JSDOM requestAnimationFrame(), cancelAnimationFrame() seront également remplacés.

Renvoie l'objet jest pour le chaînage.

`jest.useRealTimers()`

Indique à Jest de restaurer les implémentations originales de la date globale, de la performance, de l'heure et des API de temporisation. Par exemple, vous pouvez appeler jest.useRealTimers() à l'intérieur du hook afterEach pour restaurer les temporisateurs après chaque test :

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

test('faire quelque chose avec de faux temporisateurs', () => {
  jest.useFakeTimers();
  // ...
});

test('faire quelque chose avec des temporisateurs réels', () => {
  // ...
});

Renvoie l'objet jest pour le chaînage.

`jest.runAllTicks()`

Libère la file d'attente des micro-tâches (généralement interfacée dans node via process.nextTick).

Lorsque cette API est appelée, toutes les micro-tâches en attente qui ont été mises en file d'attente via process.nextTick seront exécutées. En outre, si ces micro-tâches elles-mêmes planifient de nouvelles micro-tâches, elles seront continuellement libérées jusqu'à ce qu'il n'y ait plus de micro-tâches dans la file d'attente.

`jest.runAllTimers()`

Libère la file d'attente macro-tâche (par exemple toutes les tâches mises en file d'attente par setTimeout(), setInterval() et setImmediate()) et la file d'attente micro-tâche (généralement interfacée dans node via le processus process.nextTick).

Lorsque cette API est appelée, toutes les macro-tâches et les micro-tâches en attente seront exécutées. Si ces tâches elles-mêmes planifient de nouvelles tâches, elles seront continuellement libérées jusqu'à ce qu'il n'y ait plus de tâches dans la file d'attente.

Ceci est souvent utile pour exécuter les setTimeout de façon synchrone pendant un test afin d'affirmer de façon synchrone un comportement qui ne se produirait qu'après que les callbacks setTimeout() ou setInterval() soient exécutées. Consultez la doc des simulateurs de temporisation pour plus d'informations.

`jest.runAllTimersAsync()`

Asynchronous equivalent of jest.runAllTimers(). It allows any scheduled promise callbacks to execute before running the timers.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.runAllImmediates()`

Libère toutes les tâches mises en file d'attente par setImmediate().

info

Cette fonction est disponible uniquement lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.advanceTimersByTime(msToRun)`

Exécute uniquement la file d'attente macro (c'est-à-dire toutes les tâches mises en file d'attente par setTimeout() ou setInterval() et setImmediate()).

Lorsque cette API est appelée, tous les temporisateurs sont avancés de msToRun millisecondes. Toutes les « macro-tâches » en attente qui ont été mises en file d'attente via setTimeout() ou setInterval(), et qui devraient être exécutées pendant ce laps de temps, seront exécutées. En plus, si ces macro-tâches planifient de nouvelles macro-tâches qui devraient être exécutées dans le même laps de temps, celles-ci seront exécutées jusqu'à ce qu'il ne reste plus de macro-tâches dans la file d'attente qui doivent être exécutées dans les msToRun millisecondes.

`jest.advanceTimersByTimeAsync(msToRun)`

Asynchronous equivalent of jest.advanceTimersByTime(msToRun). It allows any scheduled promise callbacks to execute before running the timers.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.runOnlyPendingTimers()`

Exécute uniquement les macro-tâches qui sont actuellement en attente (par exemple seules les tâches qui ont été mises en file d'attente par setTimeout() ou setInterval() jusqu'à ce point). Si l'une des macro-tâches en cours planifie de nouvelles macro-tâches, ces nouvelles tâches ne seront pas exécutées par cet appel.

Ceci est utile pour des scénarios tels que celui où le module testé planifie un setTimeout() dont le callback planifie un autre setTimeout() récursivement (ce qui signifie que la planification ne s'arrête jamais). Dans ces scénarios, il est utile de pouvoir avancer dans le temps d'une seule étape à la fois.

`jest.runOnlyPendingTimersAsync()`

Asynchronous equivalent of jest.runOnlyPendingTimers(). It allows any scheduled promise callbacks to execute before running the timers.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.advanceTimersToNextTimer(steps)`

Avance tous les temporisateurs en millisecondes nécessaires pour que seuls les prochains timeouts/intervals s'exécutent.

En option, vous pouvez fournir steps, afin qu'il exécute le nombre de steps des prochains timeouts/intervals.

`jest.advanceTimersToNextTimerAsync(steps)`

Asynchronous equivalent of jest.advanceTimersToNextTimer(steps). It allows any scheduled promise callbacks to execute before running the timers.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.advanceTimersToNextFrame()`

Advances all timers by the needed milliseconds to execute callbacks currently scheduled with requestAnimationFrame. advanceTimersToNextFrame() is a helpful way to execute code that is scheduled using requestAnimationFrame.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.clearAllTimers()`

Supprime tous les temporisateurs en attente du système de temporisation.

Cela signifie que si des temporisateurs ont été programmés (mais n'ont pas encore été exécutés), ils seront effacés et n'auront jamais la possibilité de s'exécuter à l'avenir.

`jest.getTimerCount()`

Retourne le nombre de temporisateurs fictifs qui restent à exécuter.

`jest.now()`

Returns the time in ms of the current clock. This is equivalent to Date.now() if real timers are in use, or if Date is mocked. In other cases (such as legacy timers) it may be useful for implementing custom mocks of Date.now(), performance.now(), etc.

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

Définit l'heure actuelle du système utilisée par les temporisateurs fictifs. Simule un utilisateur qui change l'horloge du système pendant que votre programme fonctionne. Cela affecte l'heure actuelle mais ne provoque pas en soi par exemple le déclenchement de temporisateurs; ils se déclencheront exactement comme ils l'auraient fait sans l'appel à jest.setSystemTime().

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

`jest.getRealSystemTime()`

Lors de simulation de temps, Date.now() sera également simulée. Si vous avez besoin pour une raison quelconque d'avoir accès à l'heure réelle, vous pouvez appeler cette fonction.

info

Cette fonction n'est pas disponible lors de l'utilisation de l'ancienne implémentation des faux temporisateurs.

Divers

`jest.getSeed()`

Every time Jest runs a seed value is randomly generated which you could use in a pseudorandom number generator or anywhere else.

astuce

Use the --showSeed flag to print the seed in the test report summary. To manually set the value of the seed use --seed=<num> CLI argument.

`jest.isEnvironmentTornDown()`

Returns true if test environment has been torn down.

`jest.retryTimes(numRetries, options?)`

Exécute les tests échoués n-fois jusqu'à ce qu'ils passent ou jusqu'à ce que le nombre maximum de tentatives soit épuisé.

jest.retryTimes(3);

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

If logErrorsBeforeRetry option is enabled, error(s) that caused the test to fail will be logged to the console.

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

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

waitBeforeRetry is the number of milliseconds to wait before retrying.

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

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

retryImmediately option is used to retry the failed test immediately after the failure. If this option is not specified, the tests are retried after Jest is finished running all other tests in the file.

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

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

Renvoie l'objet jest pour le chaînage.

attention

jest.retryTimes() must be declared at the top level of a test file or in a describe block.

info

This function is only available with the default jest-circus runner.

`jest.setTimeout(timeout)`

Définit l'intervalle de temps par défaut (en millisecondes) pour tous les tests et avant/après les hooks dans le fichier de test. Cela n'affecte que le fichier de test à partir duquel cette fonction est appelée. The default timeout interval is 5 seconds if this method is not called.

Exemple :

jest.setTimeout(1000); // 1 seconde

astuce

Pour définir des intervalles de temps sur des tests différents dans le même fichier, utilisez l'option timeout sur chaque test individuel.

If you want to set the timeout for all test files, use testTimeout configuration option.

Méthodes
Modules simulés
Fonctions simulées
Faux temporisateurs
Divers

Méthodes​

Modules simulés​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Fonction​

Classe​

Objet​

Tableau​

Primitives​

jest.mock(moduleName, factory, options)​

jest.Mocked<Source>​

jest.mocked(source, options?)​

jest.unmock(moduleName)​

jest.deepUnmock(moduleName)​

jest.doMock(moduleName, factory, options)​

jest.dontMock(moduleName)​

jest.setMock(moduleName, moduleExports)​

jest.requireActual(moduleName)​

jest.requireMock(moduleName)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

Fonctions simulées​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

Spied methods and the using keyword​

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

jest.Replaced<Source>​

jest.Spied<Source>​

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

Faux temporisateurs​

jest.useFakeTimers(fakeTimersConfig?)​

jest.useRealTimers()​

jest.runAllTicks()​

jest.runAllTimers()​

jest.runAllTimersAsync()​

jest.runAllImmediates()​

jest.advanceTimersByTime(msToRun)​

jest.advanceTimersByTimeAsync(msToRun)​

jest.runOnlyPendingTimers()​

jest.runOnlyPendingTimersAsync()​

jest.advanceTimersToNextTimer(steps)​

jest.advanceTimersToNextTimerAsync(steps)​

jest.advanceTimersToNextFrame()​

jest.clearAllTimers()​

jest.getTimerCount()​

jest.now()​

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

jest.getRealSystemTime()​

Divers​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Méthodes

Modules simulés

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Fonction`

`Classe`

`Objet`

`Tableau`

`Primitives`

`jest.mock(moduleName, factory, options)`

`jest.Mocked<Source>`

`jest.mocked(source, options?)`

`jest.unmock(moduleName)`

`jest.deepUnmock(moduleName)`

`jest.doMock(moduleName, factory, options)`

`jest.dontMock(moduleName)`

`jest.setMock(moduleName, moduleExports)`

`jest.requireActual(moduleName)`

`jest.requireMock(moduleName)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

Fonctions simulées

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

`jest.replaceProperty(object, propertyKey, value)`

`jest.spyOn(object, methodName)`

Spied methods and the `using` keyword

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

`jest.Replaced<Source>`

`jest.Spied<Source>`

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

Faux temporisateurs

`jest.useFakeTimers(fakeTimersConfig?)`

`jest.useRealTimers()`

`jest.runAllTicks()`

`jest.runAllTimers()`

`jest.runAllTimersAsync()`

`jest.runAllImmediates()`

`jest.advanceTimersByTime(msToRun)`

`jest.advanceTimersByTimeAsync(msToRun)`

`jest.runOnlyPendingTimers()`

`jest.runOnlyPendingTimersAsync()`

`jest.advanceTimersToNextTimer(steps)`

`jest.advanceTimersToNextTimerAsync(steps)`

`jest.advanceTimersToNextFrame()`

`jest.clearAllTimers()`

`jest.getTimerCount()`

`jest.now()`

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

`jest.getRealSystemTime()`

Divers

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`