Version: 26.x

Объект Jest

Объект jest автоматически создается в глобальной области видимости каждого тестового файла. Методы объекта jest помогают создать mock-классы/функции/переменные и позволить вам контролировать общее поведение Jest'а. Также он может быть явно импортирован через import {jest} from '@jest/globals'.

Методы

Mock Модули
Mock-функции
Mock Timers
Misc
- jest.retryTimes(numRetries, options?)
- jest.setTimeout(timeout)

Mock Модули

`jest.disableAutomock()`

Отключает автоматическое создание mock-объектов в загрузчике модулей.

info

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

Конфигурация Jest:

{
  "automock": true
}

Пример:

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

Это обычно полезно, когда у вас есть сценарий, где количество зависимостей, которые вы хотите сымитировать, гораздо меньше, чем количество зависимостей, для которых это не требуется. Например, если вы пишете тест для модуля, который использует большое число зависимостей, которые могут быть расценены, как «детали реализации» модуля, то вы, вероятно, не захотите их имитировать.

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.

Возвращает объект jest для создания цепочки вызовов.

tip

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

Включает автоматическое создание mock-объектов в загрузчике модулей.

info

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

Пример:

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

Возвращает объект jest для создания цепочки вызовов.

tip

При использовании babel-jest вызовы disableAutomock будут автоматически перенесены наверх в текущем блоке кода. Если вы хотите явно избежать этого поведения, используйте autoMockOff.

`jest.createMockFromModule(moduleName)`

tip

Renamed from .genMockFromModule(moduleName) in Jest 26.

Исходя из имени модуля, используйте систему автоматическую имитацию (automocking), чтобы создать для вас мокнутую версию модуля.

Это полезно, когда вы хотите создать ручной mock, который расширяет автоматическое поведение мока.

Пример:

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

Это то как можно createMockFromModule удалить следующие типы данных:

`Функция`

Creates a new mock function. Новая функция не имеет формальных параметров, и при вызове возвращает undefined. Эта функция также применима к async функциям.

`Класс`

Создает новый класс. Поддерживается интерфейс оригинального класса, все функции и свойства класса будут замоканы.

`Объект`

Создает новый клонированный объект. Ключи объекта и их значения будут замоканы.

`Массив`

Создает новый пустой массив, игнорируя оригинал.

`Primitives`

Создает новое свойство с таким же примитивным значением, как и оригинальное свойство.

Пример:

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

  // создает пустой массив, игнорирую оригинал.
  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)`

Сохраняет модуль с auto-mocked версией когда это необходимо. factory и options являются необязательными. Например:

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

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

const banana = require('../banana'); // banana will be explicitly mocked.

banana(); // вернет 'undefined', потому что функция auto-mocked.

Второй аргумент может быть использован для указания явной фабрики модулей, которые запускаются вместо использования automocking Jest:

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

// Выполняет указанную функцию в качестве второго аргумента `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // вернется '42';

При использовании параметра factory для модуля ES6 с экспортом по умолчанию, необходимо указать свойство __esModule: true. Это свойство обычно генерируется Babel / TypeScript, но здесь оно должно быть установлено явно вручную. При импорте default export воспользуйтесь этой инструкцией для импорта свойства default из экспортируемого объекта:

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

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

moduleName(); // будет возвращено 42
foo(); // будет возвращено 43

Третий аргумент может быть использован для создания виртуальных моков – моков модулей, которые не существуют в системе:

jest.mock(
  '../moduleName",
  () => {
    /*
     * Пользовательская реализация модуля который не существует в JS,
     * как сгенерированный модуль или встроенный модуль react-native.
     */
  },
  {virtual: true},
);

caution

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.

Модули, которые замоканы с помощью jest.mock, считаются замоканными только для файла, вызывающего jest.mock. Другой файл, импортирующий модуль, получит оригинальную реализацию, даже если он запускается после тестового файла, который мокает модуль.

Возвращает объект jest для создания цепочки вызовов.

`jest.unmock(moduleName)`

Указывает, что система модулей никогда не должна возвращать замоканную версию указанного модуля из require() (например, что он всегда должен возвращать настоящий модуль).

Чаще всего это используется для указания модуля, который данный тест будет исследовать (и таким образом нам не нужно автоматически мокать его).

Возвращает объект jest для создания цепочки вызовов.

`jest.deepUnmock(moduleName)`

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

Возвращает объект jest для создания цепочки вызовов.

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

One example when this is useful is when you want to mock a module differently within the same file:

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

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

Возвращает объект jest для создания цепочки вызовов.

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

Возвращает объект jest для создания цепочки вызовов.

`jest.setMock(moduleName, moduleExports)`

Explicitly supplies the mock object that the module system should return for the specified module.

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. However, on extremely rare occasions, even a manual mock isn't suitable for your purposes and you need to build the mock yourself inside your test.

In these rare scenarios you can use this API to manually fill the slot in the module system's mock-module registry.

Возвращает объект jest для создания цепочки вызовов.

info

It is recommended to use jest.mock() instead. The jest.mock API's second argument is a module factory instead of the expected exported module object.

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

Пример:

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.

Пример:

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Оба модуля sum являются отдельными "экземплярами" модуля sum.)

Пример в тесте:

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

test('работает', () => {
  const sum = require('../sum');
});

test('также работает', () => {
  const sum = require('../sum');
  // sum это отличная от предыдущего теста копия модуля sum.
});

Возвращает объект jest для создания цепочки вызовов.

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

Mock-функции

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

`jest.isMockFunction(fn)`

Determines if the given function is a mocked function.

`jest.spyOn(object, methodName)`

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

note

By default, jest.spyOn also calls the spied method. This is different behavior from most other test libraries. If you want to overwrite the original function, you can use jest.spyOn(object, methodName).mockImplementation(() => customImplementation) or object[methodName] = jest.fn(() => customImplementation);

tip

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.

Пример:

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

module.exports = video;

Пример теста:

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

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

Пример:

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;

Пример теста:

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

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

Возвращает объект jest для создания цепочки вызовов.

`jest.resetAllMocks()`

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

Возвращает объект jest для создания цепочки вызовов.

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

Instructs Jest to use fake versions of the standard timer functions (setTimeout, setInterval, clearTimeout, clearInterval, nextTick, setImmediate and clearImmediate as well as Date).

If you pass 'legacy' as an argument, Jest's legacy implementation will be used rather than one based on @sinonjs/fake-timers. This also mocks additional timers like Date. 'modern' will be the default behavior in Jest 27.

Возвращает объект jest для создания цепочки вызовов.

`jest.useRealTimers()`

Instructs Jest to use the real versions of the standard timer functions.

Возвращает объект jest для создания цепочки вызовов.

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

info

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

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

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

Удаляет все таймеры из системы таймеров.

Это означает, что если были запланированы некие таймеры, которые ещё не выполнились, то они будут удалены и в будущем выполниться не смогут.

`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 only available when using modern 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 only available when using modern fake timers implementation.

Misc

`jest.retryTimes(numRetries, options?)`

Runs failed tests n-times until they pass or until the max number of retries is exhausted.

jest.retryTimes(3);

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

Возвращает объект jest для создания цепочки вызовов.

caution

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

info

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

`jest.setTimeout(timeout)`

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. The default timeout interval is 5 seconds if this method is not called.

Пример:

jest.setTimeout(1000); // 1 second

tip

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

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

Методы​

Mock Модули​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Функция​

Класс​

Объект​

Массив​

Primitives​

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

Mock-функции​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.spyOn(object, methodName)​

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

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

Mock Timers​

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

Misc​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Методы

Mock Модули

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Функция`

`Класс`

`Объект`

`Массив`

`Primitives`

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

Mock-функции

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

`jest.spyOn(object, methodName)`

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

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

Mock Timers

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

Misc

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`