Aller au contenu principal
Version: 27.0

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

Méthodes#


Modules simulés#

jest.disableAutomock()#

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

Consultez la section automock de configuration pour plus d'informations

Une fois cette méthode appelée, tous les require()s retourneront les versions réelles de chaque module (plutôt qu'une version simulée).

Configuration de Jest :

{
"automock": true
}

Exemple :

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

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.

Les exemples de dépendances qui peuvent être considérées comme des « détails d'implémentation » sont des choses allant des modules intégrés au langage (par exemple, les méthodes Array.prototype) aux méthodes utilitaires très courantes (par exemple, underscore/lo-dash, utilitaires de tableau, etc.) et aux bibliothèques entières comme React.js.

Renvoie l'objet jest pour le chaînage.

Remarque : cette méthode était auparavant appelée autoMockOff. Lorsque vous utilisez babel-jest, les appels à disableAutomock seront automatiquement remontés en haut du bloc de code. Utilisez autoMockOff si vous voulez éviter explicitement ce comportement.

jest.enableAutomock()#

Active la simulation automatique dans le chargeur de module.

Renvoie l'objet jest pour le chaînage.

Consultez la section automock de configuration pour plus d'informations

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

Remarque : cette méthode était auparavant appelée autoMockOn. 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)#

renommé dans Jest 26.0.0+#

Aussi sous l'alias : .genMockFromModule(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.

Ceci est utile lorsque vous voulez créer un simulation manuelle qui étend le comportement de la simulation automatique.

Exemple :

utils.js
export default {
authorize: () => {
return 'token';
},
isAuthorized: secret => secret === 'wizard',
};
__tests__/createMockFromModule.test.js
const utils = jest.createMockFromModule('../utils').default;
utils.isAuthorized = jest.fn(secret => secret === 'not wizard');
test('implementation created by jest.createMockFromModule', () => {
expect(utils.authorize.mock).toBeTruthy();
expect(utils.isAuthorized('not wizard')).toEqual(true);
});

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

Fonction#

Crée une nouvelle fonction simulée. 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).toEqual('square');
expect(example.function.length).toEqual(0);
// les fonctions asynchrones reçoivent le même traitement que les fonctions synchrones standard.
expect(example.asyncFunction.name).toEqual('asyncSquare');
expect(example.asyncFunction.length).toEqual(0);
// crée une nouvelle classe avec la même interface, les fonctions membres et les propriétés sont simulées.
expect(example.class.constructor.name).toEqual('Bar');
expect(example.class.foo.name).toEqual('foo');
expect(example.class.array.length).toEqual(0);
// crée une version profondément clonée de l'objet original.
expect(example.object).toEqual({
baz: 'foo',
bar: {
fiz: 1,
buzz: [],
},
});
// crée un nouveau tableau vide, ignorant le tableau original.
expect(example.array.length).toEqual(0);
// crée une nouvelle propriété avec la même valeur primitive que la propriété originale.
expect(example.number).toEqual(123);
expect(example.string).toEqual('baz');
expect(example.boolean).toEqual(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 will be explicitly mocked.
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 :

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

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

Warning: 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.

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

beforeEach(() => {
jest.resetModules();
});
test('moduleName 1', () => {
jest.doMock('../moduleName', () => {
return jest.fn(() => 1);
});
const moduleName = require('../moduleName');
expect(moduleName()).toEqual(1);
});
test('moduleName 2', () => {
jest.doMock('../moduleName', () => {
return jest.fn(() => 2);
});
const moduleName = require('../moduleName');
expect(moduleName()).toEqual(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).toEqual('default1');
expect(moduleName.foo).toEqual('foo1');
});
});
test('moduleName 2', () => {
jest.doMock('../moduleName', () => {
return {
__esModule: true,
default: 'default2',
foo: 'foo2',
};
});
return import('../moduleName').then(moduleName => {
expect(moduleName.default).toEqual('default2');
expect(moduleName.foo).toEqual('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.

Remarque Il est recommandé d'utiliser à la place jest.mock(). 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.

Exemple :

jest.mock('../myModule', () => {
// Nécessite que le module original ne soit pas simulé...
const originalModule = jest.requireActual('../myModule');
return {
__esModule: true, // Utilisez-le lorsque vous travaillez avec esModules
...originalModule,
getRandom: jest.fn().mockReturnValue(10),
};
});
const getRandom = require('../myModule').getRandom;
getRandom(); // Retourne toujours 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');

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;

jest.isMockFunction(fn)#

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

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. Si vous voulez écraser la fonction originale, vous pouvez utiliser jest.spyOn(object, methodName).mockImplementation(() => customImplementation) ou object[methodName] = jest.fn(() => customImplementation);

Exemple :

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

Exemple de test :

const video = require('./video');
test('lit la vidéo', () => {
const spy = jest.spyOn(video, 'play');
const isPlaying = video.play();
expect(spy).toHaveBeenCalled();
expect(isPlaying).toBe(true);
spy.mockRestore();
});

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');
test('lit la video', () => {
const spy = jest.spyOn(video, 'play', 'get'); // nous passons 'get'
const isPlaying = video.play;
expect(spy).toHaveBeenCalled();
expect(isPlaying).toBe(true);
spy.mockRestore();
});
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);
spy.mockRestore();
});

jest.clearAllMocks()#

Clears the mock.calls, mock.instances and mock.results properties of all mocks. 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 back to their original value. Equivalent to calling .mockRestore() on every mocked function. Beware that jest.restoreAllMocks() only works when the mock was created with jest.spyOn; other mocks will require you to manually restore them.

Mock Timers#

jest.useFakeTimers(implementation?: 'modern' | 'legacy')#

Indique à Jest d'utiliser des versions factices des fonctions standard de temporisations (setTimeout, setInterval, clearTimeout, clearInterval, nextTick, setImmediate et clearImmediate ainsi que Date.).

If you pass 'legacy' as an argument, Jest's legacy implementation will be used rather than one based on @sinonjs/fake-timers.

Renvoie l'objet jest pour le chaînage.

jest.useRealTimers()#

Indique à Jest d'utiliser les versions réelles des fonctions standard de temporisation.

Renvoie l'objet jest pour le chaînage.

jest.runAllTicks()#

Exhausts the micro-task queue (usually interfaced in node via process.nextTick).

When this API is called, all pending micro-tasks that have been queued via process.nextTick will be executed. Additionally, if those micro-tasks themselves schedule new micro-tasks, those will be continually exhausted until there are no more micro-tasks remaining in the queue.

jest.runAllTimers()#

Exhausts both the macro-task queue (i.e., all tasks queued by setTimeout(), setInterval(), and setImmediate()) and the micro-task queue (usually interfaced in node via process.nextTick).

When this API is called, all pending macro-tasks and micro-tasks will be executed. If those tasks themselves schedule new tasks, those will be continually exhausted until there are no more tasks remaining in the queue.

This is often useful for synchronously executing setTimeouts during a test in order to synchronously assert about some behavior that would only happen after the setTimeout() or setInterval() callbacks executed. See the Timer mocks doc for more information.

jest.runAllImmediates()#

Exhausts all tasks queued by setImmediate().

Note: This function is not available when using modern fake timers implementation

jest.advanceTimersByTime(msToRun)#

Executes only the macro task queue (i.e. all tasks queued by setTimeout() or setInterval() and setImmediate()).

Lorsque cette API est appelée, tous les temporisateurs sont avancés de msToRun millisecondes. All pending "macro-tasks" that have been queued via setTimeout() or setInterval(), and would be executed within this time frame will be executed. Additionally, if those macro-tasks schedule new macro-tasks that would be executed within the same time frame, those will be executed until there are no more macro-tasks remaining in the queue, that should be run within msToRun milliseconds.

jest.runOnlyPendingTimers()#

Executes only the macro-tasks that are currently pending (i.e., only the tasks that have been queued by setTimeout() or setInterval() up to this point). If any of the currently pending macro-tasks schedule new macro-tasks, those new tasks will not be executed by this call.

This is useful for scenarios such as one where the module being tested schedules a setTimeout() whose callback schedules another setTimeout() recursively (meaning the scheduling never stops). In these scenarios, it's useful to be able to run forward in time by a single step at a time.

jest.advanceTimersToNextTimer(steps)#

Advances all timers by the needed milliseconds so that only the next timeouts/intervals will run.

Optionally, you can provide steps, so it will run steps amount of next timeouts/intervals.

jest.clearAllTimers()#

Removes any pending timers from the timer system.

This means, if any timers have been scheduled (but have not yet executed), they will be cleared and will never have the opportunity to execute in the future.

jest.getTimerCount()#

Returns the number of fake timers still left to run.

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

Set the current system time used by fake timers. Simulates a user changing the system clock while your program is running. It affects the current time but it does not in itself cause e.g. timers to fire; they will fire exactly as they would have done without the call to jest.setSystemTime().

Remarque : Cette fonction n'est disponible que si l'on utilise l'implémentation moderne des temporisateurs fictifs

jest.getRealSystemTime()#

When mocking time, Date.now() will also be mocked. If you for some reason need access to the real current time, you can invoke this function.

Remarque : Cette fonction n'est disponible que si l'on utilise l'implémentation moderne des temporisateurs fictifs

Misc#

jest.setTimeout(timeout)#

Set the default timeout interval for tests and before/after hooks in milliseconds. This only affects the test file from which this function is called.

Note: The default timeout interval is 5 seconds if this method is not called.

Note: If you want to set the timeout for all test files, a good place to do this is in setupFilesAfterEnv.

Exemple :

jest.setTimeout(1000); // 1 seconde

jest.retryTimes()#

Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with the default jest-circus runner!

Exemple dans un test :

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

Renvoie l'objet jest pour le chaînage.