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()jest.enableAutomock()jest.createMockFromModule(moduleName)jest.mock(moduleName, factory, 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)
- Fonctions simulées
- Temporisateurs fictifs
jest.useFakeTimers(implementation?: 'modern' | 'legacy')jest.useRealTimers()jest.runAllTicks()jest.runAllTimers()jest.runAllImmediates()jest.advanceTimersByTime(msToRun)jest.runOnlyPendingTimers()jest.advanceTimersToNextTimer(steps)jest.clearAllTimers()jest.getTimerCount()jest.setSystemTime(now?: number | Date)jest.getRealSystemTime()
- Divers
Modules simulés
jest.disableAutomock()
Désactive la simulation automatique dans le chargeur de module.
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.
Configuration de Jest :
{
"automock": true
}
Exemple :
export default {
authorize: () => {
return 'token';
},
};
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.
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.
For more details on automatic mocking see documentation of automock configuration option.
Exemple :
export default {
authorize: () => {
return 'token';
},
isAuthorized: secret => secret === 'wizard',
};
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.
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)
Renamed from .genMockFromModule(moduleName) in Jest 26.
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 :
module.exports = {
authorize: () => {
return 'token';
},
isAuthorized: secret => secret === 'wizard',
};
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);
});
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 :
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'),
};
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 :
module.exports = () => 'banana';
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 :
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},
);
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.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 :
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);
});
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 dejest.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.
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.
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.
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);
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);
});
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(() => {
// 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.clearAllMocks()
Efface les propriétés mock.calls, mock.instances 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()
Restaure tous les simulations à leur valeur originale. Equivalent aux appels de .mockRestore() sur chaque fonction simulée. Attention, jest.restoreAllMocks() ne fonctionne que lorsque la simulation a été créée avec jest.spyOn; pour les autres simulations, vous devrez les restaurer manuellement.
Temporisateurs fictifs
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).
Si vous passez 'modern' comme argument, @sinonjs/fake-timers sera utilisé comme implémentation au lieu des temporisateurs simulés propres à Jest. Cela permet également de simuler des temporisateurs supplémentaires comme Date. 'modern' sera le comportement par défaut dans Jest 27.
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()
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.runAllImmediates()
Libère toutes les tâches mises en file d'attente par setImmediate().
This function is not available when using modern fake timers implementation.
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.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.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.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.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().
This function is only available when using modern fake timers implementation.
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.
This function is only available when using modern fake timers implementation.
Divers
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);
});
Renvoie l'objet jest pour le chaînage.
jest.retryTimes() must be declared at the top level of a test file or in a describe block.
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
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.