Skip to main content
Version: Next

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

info

Los ejemplos de TypeScript de esta página sólo funcionarán como documentados si se importan explícitamente APIs de Jest:

import {expect, jest, test} from '@jest/globals';

Consult the Getting Started guide for details on how to setup Jest with TypeScript.

Métodos​

Mock Modules​

jest.disableAutomock()​

Deshabilita la simulación mock automática en el cargador de módulos.

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.

/** @type {import('jest').Config} */
const config = {
  automock: true,
};

module.exports = config;

After disableAutomock() is called, all require()s will return the real versions of each module (rather than a mocked version).

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

Esto es especialmente útil en el caso donde las dependencias que se desean simular es mucho menor a las dependencias que no se desean simular. Por ejemplo, si se escribe un test para un módulo que ocupa una gran cantidad de dependencias que se podrían clasificar como "detalles de la implementación", es probable que no se deseen simular.

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.

Returns the jest object for chaining.

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

Habilita la simulación mock automática en el cargador de módulos.

info

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

Ejemplo:

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

Returns the jest object for chaining.

tip

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

jest.createMockFromModule(moduleName)​

Dado el nombre de un modulo, usa el sistema automático de simulación mock para generar una versión mock del modulo deseado.

This is useful when you want to create a manual mock that extends the automatic mock's behavior:

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

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.

Ejemplo:

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

  // creates a new empty array, ignoring the original array.
  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)​

Crea una simulación mock de un modulo auto-mocked cuando es requerido. factory and options are optional. Por ejemplo:

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.

El segundo argumento puede usarse para especificar que se ejecute una fábrica de módulos de manera explicita en lugar de la funcionalidad de simulación mock automática 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

El tercer argumento puede ser usado para crear simulaciones mock virtuales, es decir, mocks de módulos que no existen en ninguna parte del sistema:

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

Modules that are mocked with jest.mock are mocked only for the file that calls 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.

Returns the jest object for chaining.

tip

Writing tests in TypeScript? Use the jest.Mocked utility type or the jest.mocked() helper method to have your mocked modules typed.

jest.Mocked<Source>​

See TypeScript Usage chapter of Mock Functions page for documentation.

jest.mocked(source, options?)​

See TypeScript Usage chapter of Mock Functions page for documentation.

jest.unmock(moduleName)​

Indicates that the module system should never return a mocked version of the specified module from require() (e.g. that it should always return the real module).

El uso más común de esta API es para especificar el modulo que se va a probar (y que por tanto no se desea simular automáticamente).

Returns the jest object for chaining.

jest.deepUnmock(moduleName)​

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

Returns the jest object for chaining.

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 ejemplo cuando esto es util es cuando desea simular un modulo de manera diferente dentro del mismo archivo:

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

Returns the jest object for chaining.

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.

Returns the jest object for chaining.

jest.setMock(moduleName, moduleExports)​

Provee de manera especifica el modulo simulado mock que el sistema de módulos debe regresar para un modulo en especifico.

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. Y sin embargo, en raras ocasiones, inclusive un mock manual puede no ser apropiado para los propósitos de la prueba, en cuyo caso se tiene que construir el mock dentro de la prueba.

En estos raros casos, se puede ocupar esta API para llenar de manera manual el registro del módulo mock en el sistema de módulos.

Returns the jest object for chaining.

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(() => 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.onGenerateMock(cb)​

Registers a callback function that is invoked whenever Jest generates a mock for a module. This callback allows you to modify the mock before it is returned to the rest of your tests.

Parameters for callback:

  1. modulePath: string - The absolute path to the module that is being mocked.
  2. moduleMock: T - The mock object that Jest has generated for the module. This object can be modified or replaced before returning.

Behaviour:

  • If multiple callbacks are registered via consecutive onGenerateMock calls, they will be invoked in the order they were added.
  • Each callback receives the output of the previous callback as its moduleMock. This makes it possible to apply multiple layers of transformations to the same mock.
jest.onGenerateMock((modulePath, moduleMock) => {
  // Inspect the module name and decide how to transform the mock
  if (modulePath.includes('Database')) {
    // For demonstration, let's replace a method with our own custom mock
    moduleMock.connect = jest.fn().mockImplementation(() => {
      console.log('Connected to mock DB');
    });
  }

  // Return the (potentially modified) mock
  return moduleMock;
});

// Apply mock for module
jest.mock('./Database');

// Later in your tests
import Database from './Database';
// The `Database` mock now has any transformations applied by our callback
note

The onGenerateMock callback is not called for manually created mocks, such as:

  • Mocks defined in a __mocks__ folder
  • Explicit factories provided via jest.mock('moduleName', () => { ... })

jest.resetModules()​

Restablece el registro de módulos - el caché de todos los módulos importados. Esto es útil para aislar módulos donde estado local podría entrar en conflicto entre pruebas.

Ejemplo:

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

Ejemplo en una prueba:

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

Returns the jest object for chaining.

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

jest.isolateModulesAsync(fn)​

jest.isolateModulesAsync() is the equivalent of jest.isolateModules(), but for async callbacks. The caller is expected to await the completion of isolateModulesAsync.

let myModule;
await jest.isolateModulesAsync(async () => {
  myModule = await import('myModule');
  // do async stuff here
});

const otherCopyOfMyModule = await import('myModule');

Funciones Mock​

jest.fn(implementation?)​

Returns a new, unused mock function. Opcionalmente acepta como parámetro una implementación de mock.

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

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

See the Mock Functions page for details on TypeScript usage.

jest.isMockFunction(fn)​

Determina si la función dada es una función simulada.

jest.replaceProperty(object, propertyKey, value)​

Replace object[propertyKey] with a value. The property must already exist on the object. The same property might be replaced multiple times. Returns a Jest replaced property.

note

To mock properties that are defined as getters or setters, use jest.spyOn(object, methodName, accessType) instead. To mock functions, use jest.spyOn(object, methodName) instead.

tip

All properties replaced with jest.replaceProperty could be restored to the original value by calling jest.restoreAllMocks on afterEach method.

Ejemplo:

const utils = {
  isLocalhost() {
    return process.env.HOSTNAME === 'localhost';
  },
};

module.exports = utils;

Prueba de ejemplo:

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

afterEach(() => {
  // restore replaced property
  jest.restoreAllMocks();
});

test('isLocalhost returns true when HOSTNAME is localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});
  expect(utils.isLocalhost()).toBe(true);
});

test('isLocalhost returns false when HOSTNAME is not localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'not-localhost'});
  expect(utils.isLocalhost()).toBe(false);
});

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. Este comportamiento es diferente de casi todas las otras librerías para pruebas. 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.

Ejemplo:

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

module.exports = video;

Prueba de ejemplo:

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

Spied methods and the using keyword​

If your codebase is set up to transpile the "explicit resource management" (e.g. if you are using TypeScript >= 5.2 or the @babel/plugin-proposal-explicit-resource-management plugin), you can use spyOn in combination with the using keyword:

test('logs a warning', () => {
  using spy = jest.spyOn(console, 'warn');
  doSomeThingWarnWorthy();
  expect(spy).toHaveBeenCalled();
});

That code is semantically equal to

test('logs a warning', () => {
  let spy;
  try {
    spy = jest.spyOn(console, 'warn');
    doSomeThingWarnWorthy();
    expect(spy).toHaveBeenCalled();
  } finally {
    spy.mockRestore();
  }
});

That way, your spy will automatically be restored to the original value once the current code block is left.

You can even go a step further and use a code block to restrict your mock to only a part of your test without hurting readability.

test('testing something', () => {
  {
    using spy = jest.spyOn(console, 'warn');
    setupStepThatWillLogAWarning();
  }
  // here, console.warn is already restored to the original value
  // your test can now continue normally
});
note

If you get a warning that Symbol.dispose does not exist, you might need to polyfill that, e.g. with this code:

if (!Symbol.dispose) {
  Object.defineProperty(Symbol, 'dispose', {
    get() {
      return Symbol.for('nodejs.dispose');
    },
  });
}

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.

Ejemplo:

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;

Prueba de ejemplo:

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.Replaced<Source>​

See TypeScript Usage chapter of Mock Functions page for documentation.

jest.Spied<Source>​

See TypeScript Usage chapter of Mock Functions page for documentation.

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.

Returns the jest object for chaining.

jest.resetAllMocks()​

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

Returns the jest object for chaining.

jest.restoreAllMocks()​

Restores all mocks and replaced properties back to their original value. Equivalent to calling .mockRestore() on every mocked function and .restore() on every replaced property. Beware that jest.restoreAllMocks() only works for mocks created with jest.spyOn() and properties replaced with jest.replaceProperty(); other mocks will require you to manually restore them.

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, in milliseconds. 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.

Returns the jest object for chaining.

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', () => {
  // ...
});

Returns the jest object for chaining.

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. De manera adicional, si esas micro-tareas mismas crean nuevas micro-tareas, éstas se agotaran continuamente hasta que no haya más micro-tareas en la cola.

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

Asynchronous equivalent of jest.runAllTimers(). It allows any scheduled promise callbacks to execute before running the timers.

info

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

jest.runAllImmediates()​

Exhausts all tasks queued by setImmediate().

info

This function is only available when using legacy 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.advanceTimersByTimeAsync(msToRun)​

Asynchronous equivalent of jest.advanceTimersByTime(msToRun). It allows any scheduled promise callbacks to execute before running the timers.

info

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

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). Si cualquiera de esas macro-tareas crearon nuevas macro-tareas, éstas últimas no se ejecutarán en esta llamada.

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). En dichos escenarios, es útil poder avanzar en la linea de tiempo de ejecución un paso a la vez.

jest.runOnlyPendingTimersAsync()​

Asynchronous equivalent of jest.runOnlyPendingTimers(). It allows any scheduled promise callbacks to execute before running the timers.

info

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

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.advanceTimersToNextTimerAsync(steps)​

Asynchronous equivalent of jest.advanceTimersToNextTimer(steps). It allows any scheduled promise callbacks to execute before running the timers.

info

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

jest.advanceTimersToNextFrame()​

Advances all timers by the needed milliseconds to execute callbacks currently scheduled with requestAnimationFrame. advanceTimersToNextFrame() is a helpful way to execute code that is scheduled using requestAnimationFrame.

info

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

jest.clearAllTimers()​

Remueve cualquier temporizador pendiente en el sistema de temporizadores.

Esto significa que, cualquier temporizador que haya sido programado (pero no se ha ejecutado aún), será borrado y no tendrá la oportunidad de ejecutarse en un futuro.

jest.getTimerCount()​

Returns the number of fake timers still left to run.

jest.now()​

Returns the time in ms of the current clock. This is equivalent to Date.now() if real timers are in use, or if Date is mocked. In other cases (such as legacy timers) it may be useful for implementing custom mocks of Date.now(), performance.now(), etc.

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.setTimerTickMode(mode)​

Allows configuring how fake timers advance time.

Configuration options:

type TimerTickMode =
  | {mode: 'manual'}
  | {mode: 'nextAsync'}
  | {mode: 'interval'; delta?: number};
  • manual: Timers do not advance without explicit, manual calls to the tick APIs (jest.advanceTimersByTime(ms), jest.runAllTimers(), etc).
  • nextAsync: The clock will continuously break the event loop, then run the next timer until the mode changes.
  • interval: This is the same as specifying advanceTimers: true with an advanceTimeDelta. If the delta is not specified, 20 will be used by default.
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.getSeed()​

Every time Jest runs a seed value is randomly generated which you could use in a pseudorandom number generator or anywhere else.

tip

Use the --showSeed flag to print the seed in the test report summary. To manually set the value of the seed use --seed=<num> CLI argument.

jest.isEnvironmentTornDown()​

Returns true if test environment has been torn down.

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

If logErrorsBeforeRetry option is enabled, error(s) that caused the test to fail will be logged to the console.

jest.retryTimes(3, {logErrorsBeforeRetry: true});

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

waitBeforeRetry is the number of milliseconds to wait before retrying.

jest.retryTimes(3, {waitBeforeRetry: 1000});

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

retryImmediately option is used to retry the failed test immediately after the failure. If this option is not specified, the tests are retried after Jest is finished running all other tests in the file.

jest.retryTimes(3, {retryImmediately: true});

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

Returns the jest object for chaining.

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.

Ejemplo:

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.