Объект Jest

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

Методы

Модули-моки

jest.disableAutomock()

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

См. раздел automock в разделе конфигурации для получения дополнительной информации.

После вызова этого метода все require() вернут реальные версии каждого модуля (а не смокированную версию).

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

{
  "automock": true
}

Пример:

export default {
  authorize: () => {
    return 'token';
  },
};

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

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

Примеры зависимостей, которые могут рассматриваться как «детали реализации», — это всё, начиная от встроенных в язык функций (например, методы Array.prototype) до очень распространённых служебных методов (например, underscore/lo-dash, вспомогательные методы для массивов и т. д.) и целых библиотек, таких как React.js.

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

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

jest.enableAutomock()

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

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

См. раздел automock в разделе конфигурации для получения дополнительной информации.

Пример:

export default {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

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

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

jest.createMockFromModule(moduleName)

переименовано в Jest 26.0.0+

Также доступно под псевдонимом: .genMockFromModule(moduleName)

Используйте автоматическую систему создания моков для генерации смокированной версии модуля по его имени.

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

Пример:

export default {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

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

Вот как createMockFromModule будет мокировать следующие типы данных:

Function

Создаёт новую заглушку функции. Новая функция не имеет формальных параметров и при вызове возвращает undefined. Эта функциональность также применяется к функциям async.

Class

Создаёт новый класс. Интерфейс исходного класса сохраняется, все члены класса и свойства будут смокированы.

Object

Создаёт новую глубоко клонированную копию объекта. Ключи объекта сохраняются, а их значения смокируются.

Array

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

Primitives

Создаёт новую собственность с таким же примитивным значением, как и у исходного свойства.

Пример:

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

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

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

jest.mock('../banana');

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

banana(); // will return 'undefined' because the function is auto-mocked.

Второй аргумент может быть использован для задания явной фабрики модулей, которая будет запущена вместо функции автоматического смокирования 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';

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

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

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

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

Предупреждение: Импорт модуля в файле настройки (как указано в setupFilesAfterEnv) предотвратит смокирование этого модуля, а также всех импортируемых им модулей.

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

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

jest.Mocked<Source>

См. главу «Использование TypeScript» на странице «Мокирование функций» для получения документации.

jest.mocked(source, options?)

См. главу «Использование TypeScript» на странице «Мокирование функций» для получения документации.

jest.unmock(moduleName)

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

Наиболее распространённое использование этого API — указание модуля, который данный тест намерен тестировать (и, следовательно, не хочет автоматического смокирования).

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

jest.doMock(moduleName, factory, options)

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

Один из примеров, когда это полезно, — когда вы хотите смокировать модуль по-разному в одном и том же файле:

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

Использование jest.doMock() с ES6-импортами требует дополнительных шагов. Следуйте им, если вы не хотите использовать require в своих тестах:

• Мы должны указать свойство __esModule: true (см. API jest.mock() для получения дополнительной информации).
• Статические импорты модулей ES6 поднимаются в начало файла, поэтому нам нужно импортировать их динамически, используя import().
• Наконец, нам нужна среда, поддерживающая динамический импорт. Пожалуйста, ознакомьтесь с Использованием Babel для первоначальной настройки. Затем добавьте плагин babel-plugin-dynamic-import-node или эквивалент в свою конфигурацию Babel, чтобы включить динамический импорт в 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');
  });
});

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

jest.dontMock(moduleName)

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

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

jest.setMock(moduleName, moduleExports)

Явно предоставляет объект-заглушку, который система модулей должна возвращать для указанного модуля.

Иногда автоматически сгенерированная заглушка системы модулей может оказаться недостаточной для ваших потребностей тестирования. В таких случаях, обычно, нужно написать ручную заглушку, которая больше подходит для данного модуля. Однако в крайне редких случаях даже ручная заглушка не подходит, и вам нужно создать заглушку самостоятельно в вашем тесте.

В этих редких случаях вы можете использовать этот API для ручного заполнения слота в реестре заглушенных модулей системы модулей.

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

Примечание: Рекомендуется использовать jest.mock() вместо этого. Второй аргумент API jest.mock — фабрика модулей вместо ожидаемого экспортируемого объекта модуля.

jest.requireActual(moduleName)

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

Пример:

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)

Возвращает модуль-заглушку вместо фактического модуля, минуя все проверки того, должен ли модуль загружаться нормально или нет.

jest.resetModules()

Сбрасывает реестр модулей — кэш всех загруженных модулей. Это полезно для изоляции модулей, где локальное состояние может конфликтовать между тестами.

Пример:

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

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

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

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

test('works too', () => {
  const sum = require('../sum');
  // sum is a different copy of the sum module from the previous test.
});

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

jest.isolateModules(fn)

jest.isolateModules(fn) идет дальше, чем jest.resetModules(), и создает песочницу для реестра модулей, которые загружаются внутри функции обратного вызова. Это полезно для изоляции конкретных модулей для каждого теста, чтобы локальное состояние модуля не конфликтовало между тестами.

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

const otherCopyOfMyModule = require('myModule');

Функции-заглушки

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

Определяет, является ли заданная функция функцией-заглушкой.

jest.spyOn(object, methodName)

Создаёт функцию-заглушку, аналогичную jest.fn, но также отслеживает вызовы object[methodName]. Возвращает Jest функцию-заглушку.

Пример:

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

Начиная с Jest 22.1.0+, метод jest.spyOn принимает необязательный третий аргумент accessType, который может быть либо 'get', либо 'set', что оказывается полезным, когда вы хотите отследить геттер или сеттер соответственно.

Пример:

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

Очищает свойства mock.calls, mock.instances, mock.contexts и mock.results всех заглушек. Эквивалентно вызову .mockClear() для каждой заглушенной функции.

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

jest.resetAllMocks()

Сбрасывает состояние всех заглушек. Эквивалентно вызову .mockReset() для каждой заглушенной функции.

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

jest.restoreAllMocks()

Восстанавливает все заглушки до их исходного значения. Эквивалентно вызову .mockRestore() для каждой заглушенной функции. Обратите внимание, что jest.restoreAllMocks() работает только в том случае, если заглушка была создана с помощью jest.spyOn; для других заглушек вам необходимо восстановить их вручную.

Заглушки таймеров

jest.useFakeTimers(fakeTimersConfig?)

Указывает Jest использовать фальшивые версии глобальных API даты, производительности, времени и таймеров. Реализация фальшивых таймеров основана на @sinonjs/fake-timers.

Фальшивые таймеры заменят Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() реализацией, которая получает время из фальшивых часов.

В среде Node process.hrtime, process.nextTick() и в среде JSDOM requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() также будут заменены.

Параметры конфигурации:

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

Вызов jest.useFakeTimers() будет использовать фальшивые таймеры для всех тестов в файле до тех пор, пока исходные таймеры не будут восстановлены с помощью jest.useRealTimers().

Вы можете вызвать jest.useFakeTimers() или jest.useRealTimers() откуда угодно: на верхнем уровне, внутри блока test и т. д. Имейте в виду, что это глобальная операция и повлияет на другие тесты в том же файле. Вызов jest.useFakeTimers() ещё раз в том же файле теста сбросит внутреннее состояние (например, счетчик таймеров) и установит фальшивые таймеры с предоставленными параметрами:

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

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

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

jest.useRealTimers()

Указывает Jest восстановить исходные реализации глобальных API даты, производительности, времени и таймеров. Например, вы можете вызвать jest.useRealTimers() внутри хука afterEach для восстановления таймеров после каждого теста:

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

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

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

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

jest.runAllTicks()

Очищает очередь микрозадач (обычно в Node через process.nextTick).

При вызове этого API все ожидающие микрозадачи, которые были помещены в очередь через process.nextTick, будут выполнены. Кроме того, если эти микрозадачи сами добавляют в очередь новые микрозадачи, они будут выполняться до тех пор, пока в очереди не останется ни одной микрозадачи.

jest.runAllTimers()

Очищает очередь макрозадач (т. е. все задачи, поставленные в очередь setTimeout(), setInterval(), и setImmediate()) и очередь микрозадач (обычно в Node через process.nextTick).

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

Это часто полезно для синхронного выполнения таймаутов во время теста, чтобы синхронно утверждать некоторые действия, которые произойдут только после выполнения обратных вызовов setTimeout() или setInterval(). См. документацию по заглушкам таймеров для получения дополнительной информации.

jest.runAllImmediates()

Очищает все задачи, помещённые в очередь с помощью setImmediate().

jest.advanceTimersByTime(msToRun)

Выполняет только очередь макрозадач (т. е. все задачи, поставленные в очередь с помощью setTimeout() или setInterval() и setImmediate()).

При вызове этого API все таймеры продвигаются вперёд на msToRun миллисекунд. Все ожидающие «макро-задачи», которые были помещены в очередь с помощью setTimeout() или setInterval(), и должны были быть выполнены в этом временном интервале, будут выполнены. Кроме того, если эти макро-задачи планируют новые макро-задачи, которые должны быть выполнены в том же временном интервале, они также будут выполнены, до тех пор, пока в очереди не останутся макро-задачи, которые нужно выполнить в течение msToRun миллисекунд.

jest.runOnlyPendingTimers()

Выполняет только макро-задачи, которые в настоящее время ожидают выполнения (т.е., только задачи, помещённые в очередь с помощью setTimeout() или setInterval() до этого момента). Если какие-либо из текущих ожидающих макро-задач планируют новые макро-задачи, эти новые задачи не будут выполнены при этом вызове.

Это полезно в сценариях, где модуль, который тестируется, планирует setTimeout(), чья функция обратного вызова планирует другую setTimeout() рекурсивно (что означает, что планирование никогда не останавливается). В таких сценариях полезно иметь возможность продвигаться вперёд во времени по одному шагу за раз.

jest.advanceTimersToNextTimer(steps)

Продвигает все таймеры на необходимое количество миллисекунд, так что будут выполнены только следующие таймауты/интервалы.

Вы можете дополнительно указать steps, чтобы запустить steps количество следующих таймаутов/интервалов.

jest.clearAllTimers()

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

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

jest.getTimerCount()

Возвращает количество фейковых таймеров, которые ещё предстоит запустить.

jest.setSystemTime(now?: number | Date)

Устанавливает текущее системное время, используемое фейковыми таймерами. Симулирует изменение пользователем системных часов во время выполнения вашей программы. Это влияет на текущее время, но само по себе не приводит к запуску таймеров; они будут запускаться точно так же, как и без вызова jest.setSystemTime().

jest.getRealSystemTime()

При имитации времени Date.now() также будет имитироваться. Если по какой-то причине вам нужен доступ к реальному текущему времени, вы можете вызвать эту функцию.

Разное

jest.setTimeout(timeout)

Устанавливает интервал таймаута по умолчанию (в миллисекундах) для всех тестов и перед/после хуков в файле тестов. Это влияет только на файл тестов, из которого вызвана эта функция.

Чтобы установить интервалы таймаута для разных тестов в одном файле, используйте опцию timeout на каждом отдельном тесте.

Примечание: интервал таймаута по умолчанию составляет 5 секунд, если этот метод не вызывается.

Примечание: если вы хотите установить таймаут для всех файлов тестов, хорошее место для этого — setupFilesAfterEnv.

Пример:

jest.setTimeout(1000); // 1 second

jest.retryTimes(numRetries, options)

Выполняет неудавшиеся тесты n раз, пока они не пройдут или пока не исчерпается максимальное количество попыток. options необязательны. Это работает только с предустановленным исполнителем jest-circus! Это должно находиться на самом верхнем уровне файла теста или в блоке describe. Повторные попытки не будут работать, если jest.retryTimes() вызывается в beforeEach или test блоке.

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

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

Если logErrorsBeforeRetry включено, Jest будет выводить в консоль ошибку(и), которая(ые) привели к тому, что тест не прошёл, обеспечивая наглядность причин, по которым произошёл повтор.

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

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