Skip to main content
Version: Înainte

Obiectul Jest

The jest object is automatically in scope within every test file. The methods in the jest object help create mocks and let you control Jest's overall behavior. It can also be imported explicitly by via import {jest} from '@jest/globals'.

Metode


Mock Modules

jest.disableAutomock()

Dezactivează automat dublurile mock în sistemul de încărcare a modulelor.

See automock section of configuration for more information

După apelul aceastei metode, toate require()-urile vor returna versiunile reale ale fiecare modul (în locul unei versiuni dublate).

Jest configuration:

{
"automock": true
}

Example:

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

Acest lucru este de obicei util atunci când aveţi un scenariu în care numărul de dependenţe pe care doriţi să le dublați este mult mai mic decât celor care doriți să rămână neatinse. De exemplu, dacă scrieți un test pentru un modul care utilizează un număr mare de dependențe ce pot fi clasificate în mod rezonabil ca "detalii de implementare" ale modulului, atunci probabil că nu doriți să fie dublate.

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/lo-dash, array utilities, etc) and entire libraries like React.js.

Returnează obiectul jest pentru înlănţuire.

Notă: această metodă se numea autoMockOff înainte. Atunci când se utilizează babel-jest, apelurile către disableAutomock vor fi arborate automat în partea de sus a blocului de cod. Utilizaţi autoMockOff dacă doriţi să evitați în mod explicit acest comportament.

jest.enableAutomock()

Activează automat dublurile mock în sistemul de încărcare a modulelor.

Returnează obiectul jest pentru înlănţuire.

See automock section of configuration for more information

Example:

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

Notă: această metodă se numea autoMockOn înainte. Atunci când se utilizează babel-jest, apelurile către enableAutomock vor fi arborate automat în partea de sus a blocului de cod. Utilizaţi autoMockOn dacă doriţi să evitați în mod explicit acest comportament.

jest.createMockFromModule(moduleName)

renamed in Jest 26.0.0+

Also under the alias: .genMockFromModule(moduleName)

Având în vedere numele unui modul, utilizează sistemul automat de mock pentru a genera o versiune dublată a modulului.

Acest lucru este util atunci când doriţi să creați un mock manual, care extinde comportamentul automat de dublare.

Example:

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

This is how createMockFromModule will mock the following data types:

Function

Creates a new mock function. The new function has no formal parameters and when called will return undefined. This functionality also applies to async functions.

Class

Creates a new class. The interface of the original class is maintained, all of the class member functions and properties will be mocked.

Object

Creates a new deeply cloned object. The object keys are maintained and their values are mocked.

Array

Creates a new empty array, ignoring the original.

Primitives

Creates a new property with the same primitive value as the original property.

Example:

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

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

// creates a new class with the same interface, member functions and properties are mocked.
expect(example.class.constructor.name).toEqual('Bar');
expect(example.class.foo.name).toEqual('foo');
expect(example.class.array.length).toEqual(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.length).toEqual(0);

// creates a new property with the same primitive value as the original property.
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)

Mocks a module with an auto-mocked version when it is being required. factory and options are optional. De exemplu:

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.

Al doilea argument poate fi folosit pentru a specifica un modul explicit, care este rulat în locul celui generat automat de Jest:

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

When using the factory parameter for an ES6 module with a default export, the __esModule: true property needs to be specified. This property is normally generated by Babel / TypeScript, but here it needs to be set manually. When importing a default export, it's an instruction to import the property named default from the export object:

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

Al treilea argument poate fi folosit pentru a crea dubluri virtuale – dubluri ale unor module care nu există de fapt:

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

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.

Module care sunt dublate cu jest.mock sunt dublate numai pentru fişierul care apelează jest.mock. Another file that imports the module will get the original implementation even if it runs after the test file that mocks the module.

Returnează obiectul jest pentru înlănţuire.

jest.unmock(moduleName)

Indică faptul că sistemul de încărcare a modulelor nu trebuie să returneze niciodată o versiune dublată a modulului specificat la require() (ex. ci trebuie să returneze întotdeauna modulul real).

Cea mai comună utilizare a acestui API este pentru specificarea modulului pe care un anumit test intenţionează să-l testeze (şi astfel nu vrea să fie dublat automat).

Returnează obiectul jest pentru înlănţuire.

jest.doMock(moduleName, factory, options)

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

Un exemplu când acest lucru este util este atunci când vreți să dublați un modul diferit în acelaşi fişier:

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

Using jest.doMock() with ES6 imports requires additional steps. Follow these if you don't want to use require in your tests:

  • We have to specify the __esModule: true property (see the jest.mock() API for more information).
  • Static ES6 module imports are hoisted to the top of the file, so instead we have to import them dynamically using import().
  • Finally, we need an environment which supports dynamic importing. Please see Using Babel for the initial setup. Then add the plugin babel-plugin-dynamic-import-node, or an equivalent, to your Babel config to enable dynamic importing in 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');
});
});

Returnează obiectul jest pentru înlănţuire.

jest.dontMock(moduleName)

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

Returnează obiectul jest pentru înlănţuire.

jest.setMock(moduleName, moduleExports)

Furnizează în mod explicit dublura pe care sistemul ar trebui să o returneze pentru modulul specificat.

On occasion, there are times where the automatically generated mock the module system would normally provide you isn't adequate enough for your testing needs. Normally under those circumstances you should write a manual mock that is more adequate for the module in question. Cu toate acestea, în cazuri extrem de rare, chiar și o dublură manuală nu este potrivită şi aveţi nevoie pentru a construi dublurile în interiorul testului.

În aceste scenarii rare utilizaţi acest API pentru a înlocui manual slotul modulului din registrul de dubluri al sistemului.

Returnează obiectul jest pentru înlănţuire.

Reţineţi, este recomandat să folosiţi jest.mock() în schimb. Al doilea argument al API-ului Jest.mock este un factory de modul în locul unui obiect exportat de către modul.

jest.requireActual(moduleName)

Returns the actual module instead of a mock, bypassing all checks on whether the module should receive a mock implementation or not.

Example:

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().mockReturnValue(10),
};
});

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

getRandom(); // Always returns 10

jest.requireMock(moduleName)

Returns a mock module instead of the actual module, bypassing all checks on whether the module should be required normally or not.

jest.resetModules()

Resets the module registry - the cache of all required modules. This is useful to isolate modules where local state might conflict between tests.

Example:

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Ambele module sum sunt "instanțe" separate ale aceluiași modul sum.)

Exemplu într-un test:

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

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

test('works too', () => {
const sum = require('../sum');
// sum este o copie diferită a modului sum din testul precedent.
});

Returnează obiectul jest pentru înlănţuire.

jest.isolateModules(fn)

jest.isolateModules(fn) goes a step further than jest.resetModules() and creates a sandbox registry for the modules that are loaded inside the callback function. This is useful to isolate specific modules for every test so that local module state doesn't conflict between tests.

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

const otherCopyOfMyModule = require('myModule');

Funcții pentru dubluri

jest.fn(implementation?)

Returns a new, unused mock function. Optionally takes a mock implementation.

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

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

See Mock Functions page for details on TypeScript usage.

jest.isMockFunction(fn)

Determină dacă funcţia pasată este o funcție mock.

jest.spyOn(object, methodName)

Creates a mock function similar to jest.fn but also tracks calls to object[methodName]. Returns a Jest mock function.

Notă: în mod implicit, jest.spyOn și apelează, de asemenea, metoda spionată. Acesta este un comportament diferit față de celelalte librării de testare. Dacă doriţi să suprascrieţi funcţia iniţială, puteţi utiliza jest.spyOn (obiect, methodName).mockImplementation(() = > customImplementation) sau object[methodName] = jest.fn(() = > customImplementation);

Example:

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

module.exports = video;

Exemplu de test:

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

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

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

spy.mockRestore();
});

jest.spyOn(object, methodName, accessType?)

Since Jest 22.1.0+, the jest.spyOn method takes an optional third argument of accessType that can be either 'get' or 'set', which proves to be useful when you want to spy on a getter or a setter, respectively.

Example:

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;

Exemplu de test:

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

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

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

spy.mockRestore();
});

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

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

spy.mockRestore();
});

jest.clearAllMocks()

Clears the mock.calls, mock.instances, mock.contexts and mock.results properties of all mocks. Equivalent to calling .mockClear() on every mocked function.

Returnează obiectul jest pentru înlănţuire.

jest.resetAllMocks()

Resets the state of all mocks. Equivalent to calling .mockReset() on every mocked function.

Returnează obiectul jest pentru înlănţuire.

jest.restoreAllMocks()

Resetează toate dublurile la valoarea lor originală. 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.

jest.mocked<T>(item: T, deep = false)

The mocked test helper provides typings on your mocked modules and even their deep methods, based on the typing of its source. It makes use of the latest TypeScript feature, so you even have argument types completion in the IDE (as opposed to jest.MockInstance).

Note: while it needs to be a function so that input type is changed, the helper itself does nothing else than returning the given input value.

Example:

// foo.ts
export const foo = {
a: {
b: {
c: {
hello: (name: string) => `Hello, ${name}`,
},
},
},
name: () => 'foo',
};
// foo.spec.ts
import {foo} from './foo';
jest.mock('./foo');

// here the whole foo var is mocked deeply
const mockedFoo = jest.mocked(foo, true);

test('deep', () => {
// there will be no TS error here, and you'll have completion in modern IDEs
mockedFoo.a.b.c.hello('me');
// same here
expect(mockedFoo.a.b.c.hello.mock.calls).toHaveLength(1);
});

test('direct', () => {
foo.name();
// here only foo.name is mocked (or its methods if it's an object)
expect(jest.mocked(foo.name).mock.calls).toHaveLength(1);
});

Fake Timers

jest.useFakeTimers(fakeTimersConfig?)

Instructs Jest to use fake versions of the global date, performance, time and timer APIs. Fake timers implementation is backed by @sinonjs/fake-timers.

Fake timers will swap out Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() with an implementation that gets its time from the fake clock.

In Node environment process.hrtime, process.nextTick() and in JSDOM environment requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() will be replaced as well.

Configuration options:

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

Calling jest.useFakeTimers() will use fake timers for all tests within the file, until original timers are restored with jest.useRealTimers().

You can call jest.useFakeTimers() or jest.useRealTimers() from anywhere: top level, inside an test block, etc. Keep in mind that this is a global operation and will affect other tests within the same file. Calling jest.useFakeTimers() once again in the same test file would reset the internal state (e.g. timer count) and reinstall fake timers using the provided options:

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

For some reason you might have to use legacy implementation of fake timers. It can be enabled like this (additional options are not supported):

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

Legacy fake timers will swap out setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() with Jest mock functions. In Node environment process.nextTick() and in JSDOM environment requestAnimationFrame(), cancelAnimationFrame() will be also replaced.

Returnează obiectul jest pentru înlănţuire.

jest.useRealTimers()

Instructs Jest to restore the original implementations of the global date, performance, time and timer APIs. For example, you may call jest.useRealTimers() inside afterEach hook to restore timers after each test:

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

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

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

Returnează obiectul jest pentru înlănţuire.

jest.runAllTicks()

Epuizează coada de micro-comenzi (de obicei interfașată în node prin process.nextTick).

Atunci când acest API este apelat, toate micro-comenzile în aşteptare care au fost puse în coadă prin intermediul lui process.nextTick vor fi executate. În plus, în cazul în care aceste micro-comenzi programează noi micro-comenzi la rândul lor, acestea vor fi în continuu epuizate până când nu mai există nicio micro-comandă rămasă în coada de aşteptare.

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.

Acest lucru este adesea util pentru executarea sincronă de setTimeouts în timpul unui test pentru a testa sincron unele comportamente care s-ar întâmpla numai după execuția callback-ul setTimeout() sau setInterval(). See the Timer mocks doc for more information.

jest.runAllImmediates()

Epuizează toate comenzile din coada setImmediate().

info

This function is only available when using legacy fake timers implementation.

jest.advanceTimersByTime(msToRun)

Epuizează doar coada de macro comenzi (toate comenzile din coada setTimeout(), setInterval() şi setImmediate()).

When this API is called, all timers are advanced by msToRun milliseconds. 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()

Execută numai macro-comenzi care sunt în prezent în așteptare (adică, doar comenzile care au fost puse în coadă de setTimeout() sau setInterval() până la acest moment). În cazul în care oricare din macro-comenzi programează alte macro-comenzi noi, acestea nu vor fi executate.

Acest lucru este util pentru scenarii, în care modulul testat programează un setTimeout() al cărui apel programează și el la randul lui un alt setTimeout() recursiv (adica programarea nu se opreşte niciodată). În aceste scenarii, este util pentru a putea avansa în timp pas cu pas.

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

Sterge orice cronometre în aşteptare din sistemul de cronometrare.

Acest lucru înseamnă că, în cazul în care există cronometre care au fost programate (dar nu au fost încă executate), acestea vor fi eliminate şi nu vor avea niciodată posibilitatea de a se executa în viitor.

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().

info

This function is not available when using legacy fake timers implementation.

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.

info

This function is not available when using legacy fake timers implementation.

Misc

jest.setTimeout(timeout)

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

To set timeout intervals on different tests in the same file, use the timeout option on each individual test.

Notă: Intervalul de expirate implicit este de 5 secunde, dacă această metodă nu este apelată.

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

Example:

jest.setTimeout(1000); // 1 secundă

jest.retryTimes(numRetries, options)

Runs failed tests n-times until they pass or until the max number of retries is exhausted. options are optional. This only works with the default jest-circus runner! This must live at the top-level of a test file or in a describe block. Retries will not work if jest.retryTimes() is called in a beforeEach or a test block.

Exemplu într-un test:

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

If logErrorsBeforeRetry is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred.

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

Returnează obiectul jest pentru înlănţuire.