Version : Suivant

L'objet Jest

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

L'objet jest est automatiquement disponible dans chaque fichier de test. Les méthodes de l'objet jest permettent de créer des mocks et de contrôler le comportement global de Jest. Il peut aussi être importé explicitement via import {jest} from '@jest/globals'.

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

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

Consultez le guide Premiers pas pour plus de détails sur la configuration de Jest avec TypeScript.

Modules Mock

`jest.disableAutomock()`

Désactive le mock automatique dans le chargeur de modules.

info

Le mock automatique doit être activé via l'option de configuration automock pour que cette méthode soit efficace. Consultez aussi la documentation de cette option pour plus de détails.

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;

Après l'appel à disableAutomock(), tous les require() renverront les versions réelles des modules (plutôt que des versions mockées).

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

C'est particulièrement utile quand le nombre de dépendances à mocker est bien inférieur à celles qu'on ne veut pas mocker. Par exemple, lorsque vous testez un module utilisant de nombreuses dépendances considérées comme des "détails d'implémentation", vous ne voudrez probablement pas les mocker.

Les dépendances typiquement considérées comme "détails d'implémentation" incluent : éléments natifs du langage (ex. méthodes d'Array.prototype), utilitaires courants (ex. underscore, lodash, fonctions de manipulation de tableaux), ou bibliothèques complètes comme React.js.

Retourne l'objet jest pour le chaînage.

astuce

Avec babel-jest, les appels à disableAutomock() sont automatiquement remontés en haut du bloc de code. Utilisez autoMockOff() pour éviter explicitement ce comportement.

`jest.enableAutomock()`

Active le mock automatique dans le chargeur de modules.

info

Pour plus de détails sur le mock automatique, consultez la documentation de l'option automock.

Exemple :

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

Retourne l'objet jest pour le chaînage.

astuce

Avec babel-jest, les appels à enableAutomock sont automatiquement remontés en haut du bloc de code. Utilisez autoMockOn pour éviter explicitement ce comportement.

`jest.createMockFromModule(moduleName)`

Génère une version mockée d'un module via le système de mock automatique.

Utile pour créer un mock manuel étendant le comportement du mock automatique :

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 mocke les types de données :

`Function`

Crée une nouvelle fonction mock sans paramètres qui renvoie undefined. S'applique aussi aux fonctions async.

`Class`

Crée une nouvelle classe conservant l'interface d'origine, avec toutes ses méthodes et propriétés mockées.

`Object`

Crée un nouvel objet cloné en profondeur : les clés sont conservées, les valeurs mockées.

`Array`

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

`Primitives`

Crée une nouvelle propriété avec la valeur primitive d'origine.

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

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

Simule un module avec une version automockée lorsqu'il est importé. Les paramètres factory et options sont optionnels. Par exemple :

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.

Le second argument permet de spécifier une fabrique de module explicite qui sera exécutée à la place de la fonctionnalité d'auto-simulation de Jest :

JavaScript
TypeScript

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

// 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(); // Will return '42';

Lorsqu'on utilise le paramètre factory pour un module ES6 avec un export 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 doit être définie manuellement ici. Lors de l'importation d'un export par défaut, cela indique d'importer la propriété nommée default de l'objet exporté :

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

Le troisième argument permet de créer des simulations virtuelles – des mocks de modules qui n'existent nulle part dans le système :

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

attention

L'importation d'un module dans un fichier de configuration (spécifié par setupFilesAfterEnv) empêchera la simulation de ce module ainsi que de tous les modules qu'il importe.

Les modules simulés avec jest.mock sont mockés uniquement pour le fichier appelant jest.mock. Un autre fichier important le module récupérera l'implémentation originale même s'il s'exécute après le fichier de test simulant le module.

Retourne l'objet jest pour le chaînage.

astuce

Vous écrivez des tests en TypeScript ? Utilisez le type utilitaire jest.Mocked ou la méthode d'aide jest.mocked() pour typer vos modules simulés.

`jest.Mocked<Source>`

Voir le chapitre Utilisation avec TypeScript de la page sur les fonctions mockées pour la documentation.

`jest.mocked(source, options?)`

Voir le chapitre Utilisation avec TypeScript de la page sur les fonctions mockées pour la documentation.

`jest.unmock(moduleName)`

Indique que le système de modules ne doit jamais retourner une version simulée du module spécifié depuis require() (c'est-à-dire qu'il doit toujours retourner le module réel).

L'usage principal de cette API est de spécifier le module qu'un test donné veut tester (et qu'il ne souhaite donc pas voir automocké).

Retourne l'objet jest pour le chaînage.

`jest.deepUnmock(moduleName)`

Indique que le système de modules ne doit jamais retourner une version simulée du module spécifié et de ses dépendances.

Retourne l'objet jest pour le chaînage.

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

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

Un exemple où cela est utile est lorsque vous souhaitez simuler différemment un module 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 des imports ES6 nécessite des étapes supplémentaires. Suivez ces instructions si vous ne voulez pas utiliser require dans vos tests :

Nous devons spécifier la propriété __esModule: true (voir l'API jest.mock() pour plus d'informations).
Les imports statiques de modules ES6 sont remontés en haut du fichier, nous devons donc les importer dynamiquement avec import().
Enfin, nous avons besoin d'un environnement supportant l'importation dynamique. Consultez Utilisation de Babel pour la configuration initiale. Ajoutez ensuite 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');
  });
});

Retourne l'objet jest pour le chaînage.

`jest.dontMock(moduleName)`

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

Retourne l'objet jest pour le chaînage.

`jest.setMock(moduleName, moduleExports)`

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

Dans certains cas, le mock généré automatiquement par le système de modules ne convient pas à vos besoins de test. Normalement, dans ces situations, vous devriez créer un mock manuel plus adapté au module concerné. Cependant, dans de très rares occasions, même un mock manuel ne convient pas et vous devez construire le mock vous-même dans votre test.

Dans ces scénarios exceptionnels, vous pouvez utiliser cette API pour remplir manuellement l'emplacement correspondant dans le registre des mocks du système de modules.

Retourne l'objet jest pour le chaînage.

info

Il est recommandé d'utiliser jest.mock() à la place. Le deuxième argument de l'API jest.mock est une fabrique de module plutôt que l'objet module exporté attendu.

`jest.requireActual(moduleName)`

Renvoie le module réel au lieu d'un mock, contournant toutes les vérifications sur l'application d'une implémentation mockée au module.

JavaScript
TypeScript

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.mock('../myModule', () => {
  // Require the original module to not be mocked...
  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 mock de module au lieu du module réel, contournant toutes les vérifications sur l'importation normale du module.

`jest.onGenerateMock(cb)`

Enregistre une fonction de rappel invoquée chaque fois que Jest génère un mock pour un module. Ce rappel vous permet de modifier le mock avant qu'il ne soit renvoyé au reste de vos tests.

Paramètres du rappel :

modulePath: string - Le chemin absolu vers le module en cours de mock.
moduleMock: T - L'objet mock généré par Jest pour le module. Cet objet peut être modifié ou remplacé avant le retour.

Comportement :

Si plusieurs rappels sont enregistrés via des appels consécutifs à onGenerateMock, ils seront invoqués dans l'ordre de leur ajout.
Chaque rappel reçoit en entrée la sortie du rappel précédent comme moduleMock. Cela permet d'appliquer plusieurs couches de transformations au même mock.

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

note

Le rappel onGenerateMock n'est pas appelé pour les mocks créés manuellement, tels que :

Les mocks définis dans un dossier __mocks__
Les fabriques explicites fournies via jest.mock('moduleName', () => { ... })

`jest.resetModules()`

Réinitialise le registre des modules - le cache de tous les modules importés. Utile pour isoler des modules où un état local pourrait entrer en conflit entre les tests.

Exemple :

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

Exemple dans un 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.
});

Retourne l'objet jest pour le chaînage.

`jest.isolateModules(fn)`

jest.isolateModules(fn) va plus loin que jest.resetModules() en créant un registre sandbox pour les modules chargés à l'intérieur de la fonction de rappel. Utile pour isoler des modules spécifiques à chaque test afin que leur état local n'entre pas en conflit.

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

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync() est l'équivalent asynchrone de jest.isolateModules(). L'appelant doit await la complétion de isolateModulesAsync.

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

const otherCopyOfMyModule = await import('myModule');

Fonctions Mock

`jest.fn(implementation?)`

Renvoie une nouvelle fonction mock inutilisée. Accepte optionnellement une implémentation mock.

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

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

astuce

Consultez la page Fonctions Mock pour plus de détails sur l'utilisation de TypeScript.

`jest.isMockFunction(fn)`

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

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

Remplace object[propertyKey] par une value. La propriété doit déjà exister sur l'objet. La même propriété peut être remplacée plusieurs fois. Retourne une propriété remplacée Jest.

note

Pour mocker des propriétés définies comme getters ou setters, utilisez plutôt jest.spyOn(object, methodName, accessType). Pour mocker des fonctions, utilisez plutôt jest.spyOn(object, methodName).

astuce

Toutes les propriétés remplacées avec jest.replaceProperty peuvent être restaurées à leur valeur d'origine en appelant jest.restoreAllMocks dans la méthode afterEach.

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 mock similaire à jest.fn tout en traçant les appels à object[methodName]. Retourne une fonction mock Jest.

note

Par défaut, jest.spyOn appelle aussi la méthode espionnée. Ce comportement diffère de la plupart des autres bibliothèques de test. Si vous souhaitez remplacer la fonction originale, utilisez jest.spyOn(object, methodName).mockImplementation(() => customImplementation) ou object[methodName] = jest.fn(() => customImplementation).

astuce

Comme jest.spyOn est un mock, vous pouvez restaurer l'état initial en appelant jest.restoreAllMocks dans le corps de la fonction de rappel passée au hook afterEach.

Exemple :

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

module.exports = video;

Exemple de test :

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

Méthodes espionnées et le mot-clé `using`

Si votre base de code est configurée pour transpiler la "gestion explicite des ressources" (ex: avec TypeScript ≥ 5.2 ou le plugin @babel/plugin-proposal-explicit-resource-management), vous pouvez utiliser spyOn avec le mot-clé using :

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

Ce code est sémantiquement équivalent à :

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

Ainsi, votre espion sera automatiquement restauré à sa valeur d'origine en sortant du bloc de code courant.

Vous pouvez même aller plus loin en utilisant un bloc de code pour limiter votre mock à une partie spécifique du test sans compromettre la lisibilité.

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

note

Si vous obtenez un avertissement indiquant que Symbol.dispose n'existe pas, vous devrez peut-être implémenter un polyfill, par exemple avec ce 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 accepte un troisième argument optionnel accessType pouvant être 'get' ou 'set', utile pour espionner respectivement un getter ou un setter.

Exemple :

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;

Exemple de test :

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

Voir le chapitre Utilisation avec TypeScript de la page Fonctions Mock pour la documentation.

`jest.Spied<Source>`

Voir le chapitre Utilisation avec TypeScript de la page Fonctions Mock pour la documentation.

`jest.clearAllMocks()`

Réinitialise les propriétés mock.calls, mock.instances, mock.contexts et mock.results de tous les mocks. Équivalent à appeler .mockClear() sur chaque fonction mockée.

Retourne l'objet jest pour le chaînage.

`jest.resetAllMocks()`

Réinitialise l'état de tous les mocks. Équivalent à appeler .mockReset() sur chaque fonction mockée.

Retourne l'objet jest pour le chaînage.

`jest.restoreAllMocks()`

Restaure tous les mocks et propriétés remplacées à leur valeur d'origine. Équivalent à appeler .mockRestore() sur chaque fonction mockée et .restore() sur chaque propriété remplacée. Attention : jest.restoreAllMocks() fonctionne uniquement pour les mocks créés avec jest.spyOn() et les propriétés remplacées avec jest.replaceProperty() ; les autres mocks nécessiteront une restauration manuelle.

Horloges fictives

`jest.useFakeTimers(fakeTimersConfig?)`

Instruct Jest d'utiliser des versions fictives des API globales de date, performance, temps et minuteries. L'implémentation repose sur @sinonjs/fake-timers.

Les horloges fictives remplaceront Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() par une implémentation dont le temps provient de l'horloge fictive.

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

Options de configuration :

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

Appeler jest.useFakeTimers() activera les horloges fictives pour tous les tests du fichier, jusqu'à ce que les minuteries originales soient restaurées avec jest.useRealTimers().

Vous pouvez appeler jest.useFakeTimers() ou jest.useRealTimers() n'importe où : au niveau supérieur, dans un bloc test, etc. Notez qu'il s'agit d'une opération globale affectant les autres tests du même fichier. Rappeler jest.useFakeTimers() dans le même fichier réinitialisera l'état interne (ex: compteur de minuteries) et réinstallera les horloges fictives avec les options fournies :

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();
  // ...
});

Minuteries fictives héritées

Dans certains cas, vous devrez peut-être utiliser l'implémentation héritée des minuteries fictives. Elle peut être activée ainsi (les options supplémentaires ne sont pas supportées) :

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

Les minuteries fictives héritées remplaceront setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() par des fonctions mock de Jest. Dans un environnement Node, process.nextTick() sera aussi remplacé, et dans JSDOM, requestAnimationFrame(), cancelAnimationFrame() le seront également.

Retourne l'objet jest pour le chaînage.

`jest.useRealTimers()`

Instruct Jest de restaurer les implémentations originales des API globales de date, performance, temps et minuteries. Par exemple, vous pouvez appeler jest.useRealTimers() dans un hook afterEach pour restaurer les minuteries après chaque test :

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

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

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

Retourne l'objet jest pour le chaînage.

`jest.runAllTicks()`

Épuise 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. De plus, si ces micro-tâches planifient elles-mêmes de nouvelles micro-tâches, celles-ci seront traitées continuellement jusqu'à ce qu'il ne reste plus aucune micro-tâche dans la file.

`jest.runAllTimers()`

Traite à la fois la file de tâches macro (c'est-à-dire toutes les tâches mises en file d'attente par setTimeout(), setInterval() et setImmediate()) et la file de tâches micro (généralement gérée dans Node.js via process.nextTick).

Lorsque cette API est appelée, toutes les macro-tâches et micro-tâches en attente sont exécutées. Si ces tâches planifient elles-mêmes de nouvelles tâches, celles-ci seront traitées continuellement jusqu'à ce qu'il ne reste plus aucune tâche dans la file.

Cela est souvent utile pour exécuter de manière synchrone des setTimeouts pendant un test, afin de vérifier de manière synchrone un comportement qui ne se produirait qu'après l'exécution des callbacks de setTimeout() ou setInterval(). Consultez la documentation Timer mocks pour plus d'informations.

`jest.runAllTimersAsync()`

Équivalent asynchrone de jest.runAllTimers(). Il permet à toutes les callbacks de promesses planifiées de s'exécuter avant le déclenchement des minuteries.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.runAllImmediates()`

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

info

Cette fonction n'est disponible qu'avec l'ancienne implémentation des faux minuteries (legacy fake timers).

`jest.advanceTimersByTime(msToRun)`

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

Lorsque cette API est appelée, toutes les minuteries sont avancées 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 s'exécuter dans cet intervalle de temps, seront exécutées. De plus, si ces macro-tâches planifient de nouvelles macro-tâches qui devraient s'exécuter dans le même intervalle, celles-ci seront traitées jusqu'à ce qu'il ne reste plus de macro-tâches dans la file devant être exécutées dans les msToRun millisecondes.

`jest.advanceTimersByTimeAsync(msToRun)`

Équivalent asynchrone de jest.advanceTimersByTime(msToRun). Il permet à toutes les callbacks de promesses planifiées de s'exécuter avant le déclenchement des minuteries.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.runOnlyPendingTimers()`

Exécute uniquement les macro-tâches actuellement en attente (c'est-à-dire uniquement les tâches mises en file d'attente par setTimeout() ou setInterval() jusqu'à ce point). Si l'une des macro-tâches en attente planifie de nouvelles macro-tâches, celles-ci ne seront pas exécutées par cet appel.

Cela est utile dans des scénarios où le module testé planifie un setTimeout() dont le callback planifie récursivement un autre setTimeout() (ce qui signifie que la planification ne s'arrête jamais). Dans ces cas, il est utile de pouvoir avancer dans le temps étape par étape.

`jest.runOnlyPendingTimersAsync()`

Équivalent asynchrone de jest.runOnlyPendingTimers(). Il permet à toutes les callbacks de promesses planifiées de s'exécuter avant le déclenchement des minuteries.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.advanceTimersToNextTimer(steps)`

Avance toutes les minuteries du nombre de millisecondes nécessaire pour que seuls les prochains timeouts/intervals soient déclenchés.

Optionnellement, vous pouvez fournir un nombre steps, ce qui exécutera steps quantités de prochains timeouts/intervals.

`jest.advanceTimersToNextTimerAsync(steps)`

Équivalent asynchrone de jest.advanceTimersToNextTimer(steps). Il permet à toutes les fonctions de rappel de promesses planifiées de s'exécuter avant l'exécution des temporisateurs.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.advanceTimersToNextFrame()`

Avance tous les temporisateurs du nombre de millisecondes nécessaire pour exécuter les fonctions de rappel actuellement planifiées avec requestAnimationFrame. advanceTimersToNextFrame() est un moyen pratique d'exécuter du code planifié avec requestAnimationFrame.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.clearAllTimers()`

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

Cela signifie que si des temporisateurs ont été planifiés (mais pas encore exécutés), ils seront effacés et n'auront plus jamais l'opportunité de s'exécuter.

`jest.getTimerCount()`

Retourne le nombre de faux temporisateurs restant à exécuter.

`jest.now()`

Retourne l'heure actuelle en ms. C'est équivalent à Date.now() si les temporisateurs réels sont utilisés, ou si Date est simulé. Dans d'autres cas (comme les temporisateurs hérités), cela peut être utile pour implémenter des simulations personnalisées de Date.now(), performance.now(), etc.

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

Définit l'heure système actuelle utilisée par les faux temporisateurs. Simule un utilisateur modifiant l'horloge système pendant l'exécution de votre programme. Cela affecte l'heure actuelle mais ne déclenche pas directement les temporisateurs ; ils se déclencheront exactement comme ils l'auraient fait sans l'appel à jest.setSystemTime().

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.setTimerTickMode(mode)`

Permet de configurer le mode d'avancement des simulateurs de temps (fake timers).

Options de configuration :

type TimerTickMode =
  | {mode: 'manual'}
  | {mode: 'nextAsync'}
  | {mode: 'interval'; delta?: number};

manual : Les minuteries n'avancent pas sans appels manuels explicites aux API de tick (jest.advanceTimersByTime(ms), jest.runAllTimers(), etc).
nextAsync : L'horloge interrompt continuellement la boucle d'événements, puis exécute la minuterie suivante jusqu'au changement de mode.
interval : Équivalent à spécifier advanceTimers: true avec un advanceTimeDelta. Si le delta n'est pas précisé, 20 sera utilisé par défaut.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

`jest.getRealSystemTime()`

Lorsque le temps est simulé, Date.now() sera également simulé. Si vous avez besoin d'accéder au temps réel actuel pour une raison quelconque, vous pouvez appeler cette fonction.

info

Cette fonction n'est pas disponible avec l'implémentation héritée des faux temporisateurs.

Divers

`jest.getSeed()`

À chaque exécution de Jest, une valeur d'amorçage est générée aléatoirement, que vous pouvez utiliser dans un générateur de nombres pseudo-aléatoires ou ailleurs.

astuce

Utilisez le flag --showSeed pour afficher la graine dans le résumé du rapport de test. Pour définir manuellement la valeur de la graine, utilisez l'argument CLI --seed=<num>.

`jest.isEnvironmentTornDown()`

Retourne true si l'environnement de test a été déconstruit.

`jest.retryTimes(numRetries, options?)`

Relance les tests échoués n fois jusqu'à ce qu'ils réussissent ou que le nombre maximum de tentatives soit épuisé.

jest.retryTimes(3);

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

Si l'option logErrorsBeforeRetry est activée, les erreurs ayant causé l'échec du test seront journalisées dans la console.

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

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

waitBeforeRetry est le nombre de millisecondes à attendre avant de relancer.

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

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

L'option retryImmediately sert à relancer le test échoué immédiatement après l'échec. Si cette option n'est pas spécifiée, les tests sont relancés après que Jest a fini d'exécuter tous les autres tests du fichier.

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

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

Retourne l'objet jest pour le chaînage.

attention

jest.retryTimes() doit être déclaré au niveau supérieur d'un fichier de test ou dans un bloc describe.

info

Cette fonction n'est disponible qu'avec le runner par défaut jest-circus.

`jest.setTimeout(timeout)`

Définit le délai d'expiration par défaut (en millisecondes) pour tous les tests et les hooks before/after dans le fichier de test. Cela affecte uniquement le fichier de test d'où cette fonction est appelée. Le délai d'expiration par défaut est de 5 secondes si cette méthode n'est pas utilisée.

Exemple :

jest.setTimeout(1000); // 1 second

astuce

Pour définir des délais différents sur plusieurs tests d'un même fichier, utilisez l'option timeout sur chaque test individuel.

Si vous souhaitez définir le délai d'expiration pour tous les fichiers de test, utilisez l'option de configuration testTimeout.

Méthodes
Modules Mock
Fonctions Mock
Horloges fictives
Divers

Méthodes​

Modules Mock​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Function​

Class​

Object​

Array​

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.onGenerateMock(cb)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

Fonctions Mock​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

Méthodes espionnées et le mot-clé using​

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

jest.Replaced<Source>​

jest.Spied<Source>​

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

Horloges fictives​

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.setTimerTickMode(mode)​

jest.getRealSystemTime()​

Divers​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Méthodes

Modules Mock

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Function`

`Class`

`Object`

`Array`

`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.onGenerateMock(cb)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

Fonctions Mock

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

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

`jest.spyOn(object, methodName)`

Méthodes espionnées et le mot-clé `using`

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

`jest.Replaced<Source>`

`jest.Spied<Source>`

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

Horloges fictives

`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.setTimerTickMode(mode)`

`jest.getRealSystemTime()`

Divers

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`