Versión: Siguiente

El objeto Jest

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

El objeto jest está automáticamente disponible en el ámbito de cada archivo de pruebas. Los métodos en el objeto jest ayudan a crear mocks y permiten controlar el comportamiento general de Jest. También puede importarse explícitamente mediante import {jest} from '@jest/globals'.

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

información

Los ejemplos de TypeScript en esta página solo funcionarán como se documenta si importas explícitamente las APIs de Jest:

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

Consulta la guía de Primeros pasos para obtener detalles sobre cómo configurar Jest con TypeScript.

Módulos simulados (Mocks)

`jest.disableAutomock()`

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

información

La simulación automática debe estar habilitada mediante la opción de configuración automock para que este método tenga efecto. Consulta también la documentación de esta opción para más detalles.

JavaScript
TypeScript

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

module.exports = config;

import type {Config} from 'jest';

const config: Config = {
  automock: true,
};

export default config;

Tras llamar a disableAutomock(), todos los require() devolverán las versiones reales de cada módulo (en lugar de versiones simuladas).

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 suele ser útil cuando tienes un escenario donde el número de dependencias que quieres simular es mucho menor que las que no. Por ejemplo, al probar un módulo que usa muchas dependencias que pueden considerarse "detalles de implementación", normalmente no querrás simularlas.

Ejemplos de dependencias que podrían considerarse "detalles de implementación" incluyen elementos nativos del lenguaje (como métodos de Array.prototype), utilidades comunes (underscore, lodash, etc.) y bibliotecas completas como React.js.

Devuelve el objeto jest para encadenamiento.

consejo

Al usar babel-jest, las llamadas a disableAutomock() se elevan automáticamente al inicio del bloque. Usa autoMockOff() si quieres evitar explícitamente este comportamiento.

`jest.enableAutomock()`

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

información

Para más detalles sobre simulación automática, consulta la opción de configuración automock.

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

Devuelve el objeto jest para encadenamiento.

consejo

Al usar babel-jest, las llamadas a enableAutomock se elevan automáticamente al inicio del bloque. Usa autoMockOn si quieres evitar explícitamente este comportamiento.

`jest.createMockFromModule(moduleName)`

Dado el nombre de un módulo, usa el sistema de simulación automática para generar una versión simulada del mismo.

Es útil cuando quieres crear un mock manual que extienda el comportamiento del mock automático:

JavaScript
TypeScript

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

utils.ts
export const utils = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: (secret: string) => secret === 'wizard',
};

__tests__/createMockFromModule.test.ts
const {utils} =
  jest.createMockFromModule<typeof import('../utils')>('../utils');

utils.isAuthorized = jest.fn((secret: string) => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

Así es como createMockFromModule simula estos tipos de datos:

`Function`

Crea una nueva función simulada sin parámetros formales que devuelve undefined al ser llamada. También aplica a funciones async.

`Class`

Crea una nueva clase manteniendo la interfaz original, con todas sus funciones y propiedades simuladas.

`Object`

Crea un nuevo objeto clonado profundamente. Se mantienen las claves originales y sus valores son simulados.

`Array`

Crea un nuevo array vacío, ignorando el original.

`Primitives`

Crea una nueva propiedad con el mismo valor primitivo que la propiedad original.

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

Simula un módulo con una versión automática simulada cuando se requiere. factory y options son opcionales. 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 una fábrica de módulos explícita que se ejecuta en lugar de usar la función de automocking de Jest:

JavaScript
TypeScript

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

// The optional type argument provides typings for the module factory
jest.mock<typeof import('../moduleName')>('../moduleName', () => {
  return jest.fn(() => 42);
});

// This runs the function specified as second argument to `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // Will return '42';

Al usar el parámetro factory para módulos ES6 con exportación predeterminada, se debe especificar la propiedad __esModule: true. Normalmente esta propiedad es generada por Babel/TypeScript, pero aquí debe establecerse manualmente. Al importar una exportación predeterminada, es una instrucción para importar la propiedad llamada default del objeto exportado:

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 usarse para crear mocks virtuales (simulaciones de módulos que no existen en ningún lugar 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},
);

precaución

Importar un módulo en un archivo de configuración (como se especifica en setupFilesAfterEnv) evitará la simulación para ese módulo y todos los módulos que importe.

Los módulos simulados con jest.mock solo se simulan para el archivo que llama a jest.mock. Otro archivo que importe el módulo obtendrá la implementación original incluso si se ejecuta después del archivo de prueba que simula el módulo.

Devuelve el objeto jest para encadenamiento.

consejo

¿Escribes pruebas en TypeScript? Usa la utilidad de tipos jest.Mocked o el método auxiliar jest.mocked() para tener tus módulos simulados tipados.

`jest.Mocked<Source>`

Consulta el capítulo Uso con TypeScript en la página de Funciones Simuladas para la documentación.

`jest.mocked(source, options?)`

Consulta el capítulo Uso con TypeScript en la página de Funciones Simuladas para la documentación.

`jest.unmock(moduleName)`

Indica que el sistema de módulos nunca debe devolver una versión simulada del módulo especificado desde require() (es decir, que siempre debe devolver el módulo real).

El uso más común de esta API es especificar el módulo que una prueba determinada pretende probar (y por lo tanto no quiere que se simule automáticamente).

Devuelve el objeto jest para encadenamiento.

`jest.deepUnmock(moduleName)`

Indica que el sistema de módulos nunca debe devolver una versión simulada del módulo especificado ni de sus dependencias.

Devuelve el objeto jest para encadenamiento.

`jest.doMock(moduleName, factory, options)`

Cuando se usa babel-jest, las llamadas a mock se elevan automáticamente al inicio del bloque de código. Usa este método si quieres evitar explícitamente este comportamiento.

Un ejemplo donde esto es útil es cuando quieres simular un módulo de manera diferente dentro del mismo archivo:

JavaScript
TypeScript

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

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

test('moduleName 1', () => {
  // The optional type argument provides typings for the module factory
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

test('moduleName 2', () => {
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 2);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(2);
});

Usar jest.doMock() con importaciones ES6 requiere pasos adicionales. Sigue estos pasos si no quieres usar require en tus pruebas:

Debemos especificar la propiedad __esModule: true (consulta la API jest.mock() para más información).
Las importaciones estáticas de módulos ES6 se elevan al inicio del archivo, así que debemos importarlas dinámicamente usando import().
Finalmente, necesitamos un entorno que admita importaciones dinámicas. Consulta Usando Babel para la configuración inicial. Luego agrega el plugin babel-plugin-dynamic-import-node, o un equivalente, a tu configuración de Babel para habilitar importaciones dinámicas en 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');
  });
});

Devuelve el objeto jest para encadenamiento.

`jest.dontMock(moduleName)`

Cuando se usa babel-jest, las llamadas a unmock se elevan automáticamente al inicio del bloque de código. Utiliza este método si deseas evitar explícitamente este comportamiento.

Devuelve el objeto jest para encadenamiento.

`jest.setMock(moduleName, moduleExports)`

Proporciona explícitamente el objeto simulado que el sistema de módulos debe devolver para el módulo especificado.

Ocasionalmente, la simulación generada automáticamente por el sistema de módulos puede no ser adecuada para tus necesidades de pruebas. Normalmente en esos casos deberías escribir un mock manual más apropiado. Sin embargo, en raras ocasiones incluso un mock manual puede no servir y necesitas construir la simulación directamente en tu prueba.

En estos escenarios excepcionales puedes usar esta API para llenar manualmente el espacio en el registro de módulos simulados del sistema.

Devuelve el objeto jest para encadenamiento.

información

Se recomienda usar jest.mock() en su lugar. El segundo argumento de jest.mock es una fábrica de módulos en lugar del objeto de módulo exportado esperado.

`jest.requireActual(moduleName)`

Devuelve el módulo real en lugar de una simulación, omitiendo todas las verificaciones sobre si el módulo debería recibir una implementación simulada o no.

JavaScript
TypeScript

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.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule =
    jest.requireActual<typeof import('../myModule')>('../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)`

Devuelve un módulo simulado en lugar del módulo real, omitiendo todas las verificaciones sobre si el módulo debería requerirse normalmente o no.

`jest.onGenerateMock(cb)`

Registra una función callback que se invoca cada vez que Jest genera una simulación para un módulo. Este callback permite modificar la simulación antes de que se devuelva al resto de tus pruebas.

Parámetros del callback:

modulePath: string - Ruta absoluta al módulo que se está simulando.
moduleMock: T - Objeto simulado que Jest ha generado para el módulo. Este objeto puede modificarse o reemplazarse antes de devolverlo.

Comportamiento:

Si se registran múltiples callbacks mediante llamadas consecutivas a onGenerateMock, se invocarán en el orden en que se añadieron.
Cada callback recibe la salida del callback anterior como su moduleMock. Esto permite aplicar múltiples capas de transformaciones a la misma simulación.

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

nota

El callback onGenerateMock no se llama para simulaciones creadas manualmente, como:

Mocks definidos en una carpeta __mocks__
Fábricas explícitas proporcionadas mediante jest.mock('moduleName', () => { ... })

`jest.resetModules()`

Reinicia el registro de módulos (la caché de todos los módulos requeridos). Es útil para aislar módulos donde el estado local podría generar conflictos 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.
});

Devuelve el objeto jest para encadenamiento.

`jest.isolateModules(fn)`

jest.isolateModules(fn) va un paso más allá que jest.resetModules() y crea un registro en sandbox para los módulos cargados dentro de la función callback. Es útil para aislar módulos específicos en cada prueba y evitar conflictos de estado local entre pruebas.

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

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync() es el equivalente de jest.isolateModules() pero para callbacks asíncronos. Se espera que el llamante await la finalización de isolateModulesAsync.

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

const otherCopyOfMyModule = await import('myModule');

Funciones Simuladas

`jest.fn(implementation?)`

Devuelve una nueva función simulada sin usar. Opcionalmente recibe una implementación simulada.

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

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

consejo

Consulta la página Funciones Mock para detalles sobre uso con TypeScript.

`jest.isMockFunction(fn)`

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

`jest.replaceProperty(object, propertyKey, value)`

Reemplaza object[propertyKey] con un value. La propiedad debe existir previamente en el objeto. La misma propiedad puede reemplazarse múltiples veces. Retorna una propiedad reemplazada de Jest.

nota

Para mockear propiedades definidas como getters o setters, usa jest.spyOn(object, methodName, accessType). Para mockear funciones, usa jest.spyOn(object, methodName).

consejo

Todas las propiedades reemplazadas con jest.replaceProperty pueden restaurarse a su valor original llamando jest.restoreAllMocks en el método afterEach.

Ejemplo:

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

module.exports = utils;

Ejemplo de prueba:

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

Crea una función mock similar a jest.fn pero también rastrea llamadas a object[methodName]. Retorna una función mock de Jest.

nota

Por defecto, jest.spyOn también llama al método espía. Este comportamiento difiere de otras librerías de pruebas. Si quieres sobrescribir la función original, usa jest.spyOn(object, methodName).mockImplementation(() => customImplementation) o object[methodName] = jest.fn(() => customImplementation).

consejo

Como jest.spyOn es un mock, puedes restaurar el estado inicial llamando jest.restoreAllMocks en el callback de afterEach.

Ejemplo:

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

module.exports = video;

Ejemplo de prueba:

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

Métodos espiados y la palabra clave `using`

Si tu código transpila "gestión explícita de recursos" (ej. con TypeScript ≥ 5.2 o el plugin @babel/plugin-proposal-explicit-resource-management), puedes combinar spyOn con using:

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

Este código es semánticamente equivalente a:

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

Así tu espía se restaurará automáticamente al salir del bloque actual.

Puedes incluso limitar el mock a una parte específica del test usando bloques de código:

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

nota

Si recibes una advertencia sobre que Symbol.dispose no existe, necesitarás un polyfill:

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

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

Desde Jest 22.1.0+, jest.spyOn acepta un tercer parámetro opcional accessType ('get' o 'set') para espiar getters o setters respectivamente.

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;

Ejemplo de prueba:

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

Ver documentación en Uso con TypeScript de Funciones Mock.

`jest.Spied<Source>`

Consulta el capítulo Uso con TypeScript de la página Funciones simuladas para obtener la documentación.

`jest.clearAllMocks()`

Borra las propiedades mock.calls, mock.instances, mock.contexts y mock.results de todas las simulaciones. Equivale a llamar a .mockClear() en cada función simulada.

Devuelve el objeto jest para encadenamiento.

`jest.resetAllMocks()`

Reinicia el estado de todas las simulaciones. Equivale a llamar a .mockReset() en cada función simulada.

Devuelve el objeto jest para encadenamiento.

`jest.restoreAllMocks()`

Restaura todas las simulaciones y propiedades reemplazadas a su valor original. Equivale a llamar a .mockRestore() en cada función simulada y a .restore() en cada propiedad reemplazada. Ten en cuenta que jest.restoreAllMocks() solo funciona para simulaciones creadas con jest.spyOn() y propiedades reemplazadas con jest.replaceProperty(); otras simulaciones requerirán que las restaures manualmente.

Temporizadores falsos

`jest.useFakeTimers(fakeTimersConfig?)`

Indica a Jest que use versiones falsas de las APIs globales de fecha, rendimiento, tiempo y temporizadores. La implementación de temporizadores falsos está respaldada por @sinonjs/fake-timers.

Los temporizadores falsos reemplazarán Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() con una implementación que obtiene su tiempo del reloj falso.

En entornos de Node, process.hrtime, process.nextTick() y en entornos JSDOM, requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() también serán reemplazados.

Opciones de configuración:

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

Llamar a jest.useFakeTimers() utilizará temporizadores falsos para todas las pruebas en el archivo, hasta que los temporizadores originales sean restaurados con jest.useRealTimers().

Puedes llamar a jest.useFakeTimers() o jest.useRealTimers() desde cualquier lugar: nivel superior, dentro de un bloque test, etc. Ten en cuenta que esta es una operación global y afectará a otras pruebas dentro del mismo archivo. Llamar a jest.useFakeTimers() nuevamente en el mismo archivo de prueba restablecerá el estado interno (por ejemplo, el contador de temporizadores) y reinstalará los temporizadores falsos usando las opciones proporcionadas:

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

Temporizadores falsos heredados

Por alguna razón, podrías tener que usar la implementación heredada de temporizadores falsos. Se puede habilitar así (las opciones adicionales no son compatibles):

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

Los temporizadores falsos heredados reemplazarán setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() con funciones simuladas de Jest. En entornos de Node, process.nextTick() y en entornos JSDOM, requestAnimationFrame(), cancelAnimationFrame() también serán reemplazados.

Devuelve el objeto jest para encadenamiento.

`jest.useRealTimers()`

Indica a Jest que restaure las implementaciones originales de las APIs globales de fecha, rendimiento, tiempo y temporizadores. Por ejemplo, puedes llamar a jest.useRealTimers() dentro del hook afterEach para restaurar los temporizadores después de cada prueba:

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

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

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

Devuelve el objeto jest para encadenamiento.

`jest.runAllTicks()`

Agota la cola de micro-tareas (normalmente interfazada en node mediante process.nextTick).

Cuando se llama a esta API, se ejecutarán todas las microtareas pendientes encoladas mediante process.nextTick. Además, si esas microtareas programan nuevas microtareas, estas se agotarán continuamente hasta que no queden más microtareas en la cola.

`jest.runAllTimers()`

Agota tanto la cola de macrotareas (es decir, todas las tareas encoladas por setTimeout(), setInterval() y setImmediate()) como la cola de microtareas (normalmente gestionadas en Node.js mediante process.nextTick).

Cuando se llama a esta API, se ejecutarán todas las macro-tareas y micro-tareas pendientes. Si esas tareas programan nuevas tareas, estas se agotarán continuamente hasta que no queden más tareas en la cola.

Esto suele ser útil para ejecutar sincrónicamente temporizadores durante una prueba y así poder hacer aserciones sincrónicas sobre comportamientos que solo ocurrirían después de ejecutar los callbacks de setTimeout() o setInterval(). Consulta la documentación de Timer mocks para más información.

`jest.runAllTimersAsync()`

Equivalente asíncrono de jest.runAllTimers(). Permite que se ejecuten los callbacks de promesas programadas antes de ejecutar los temporizadores.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.runAllImmediates()`

Agota todas las tareas encoladas por setImmediate().

información

Esta función solo está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.advanceTimersByTime(msToRun)`

Ejecuta solo la cola de macro-tareas (es decir, todas las tareas encoladas por setTimeout(), setInterval() y setImmediate()).

Cuando se llama a esta API, todos los temporizadores avanzan msToRun milisegundos. Se ejecutarán todas las "macro-tareas" pendientes encoladas mediante setTimeout() o setInterval() que debían ejecutarse en este intervalo de tiempo. Además, si esas macro-tareas programan nuevas macro-tareas que se ejecutarían dentro del mismo intervalo temporal, estas también se ejecutarán hasta que no queden más macro-tareas en la cola que deban ejecutarse dentro de msToRun milisegundos.

`jest.advanceTimersByTimeAsync(msToRun)`

Equivalente asíncrono de jest.advanceTimersByTime(msToRun). Permite que se ejecuten los callbacks de promesas programadas antes de ejecutar los temporizadores.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.runOnlyPendingTimers()`

Ejecuta solo las macro-tareas pendientes actualmente (es decir, solo tareas encoladas por setTimeout() o setInterval() hasta este momento). Si alguna de las macro-tareas pendientes programa nuevas macro-tareas, estas nuevas tareas no se ejecutarán en esta llamada.

Esto es útil para escenarios como cuando el módulo probado programa un setTimeout() cuyo callback programa otro setTimeout() recursivamente (lo que significa que la programación nunca se detiene). En estos casos, es útil poder avanzar en el tiempo paso a paso.

`jest.runOnlyPendingTimersAsync()`

Equivalente asíncrono de jest.runOnlyPendingTimers(). Permite que se ejecuten los callbacks de promesas programadas antes de ejecutar los temporizadores.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.advanceTimersToNextTimer(steps)`

Avanza todos los temporizadores los milisegundos necesarios para que solo se ejecuten los próximos timeouts/intervalos.

Opcionalmente, puedes proporcionar steps para que ejecute la cantidad steps de próximos timeouts/intervalos.

`jest.advanceTimersToNextTimerAsync(steps)`

Equivalente asíncrono de jest.advanceTimersToNextTimer(steps). Permite que cualquier callback programado en promesas se ejecute antes de avanzar los temporizadores.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.advanceTimersToNextFrame()`

Avanza todos los temporizadores los milisegundos necesarios para ejecutar callbacks actualmente programados con requestAnimationFrame. advanceTimersToNextFrame() es útil para ejecutar código programado mediante requestAnimationFrame.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.clearAllTimers()`

Elimina todos los temporizadores pendientes del sistema de temporización.

Esto significa que si hay temporizadores programados (pero aún no ejecutados), se borrarán y nunca tendrán oportunidad de ejecutarse en el futuro.

`jest.getTimerCount()`

Devuelve el número de temporizadores falsos que aún quedan por ejecutar.

`jest.now()`

Devuelve el tiempo actual en milisegundos. Equivale a Date.now() si se usan temporizadores reales o si Date está simulado. En otros casos (como temporizadores heredados) puede ser útil para implementar simulaciones personalizadas de Date.now(), performance.now(), etc.

`jest.setSystemTime(now?: number | Date)`

Establece la hora del sistema actual que usan los temporizadores falsos. Simula un usuario cambiando el reloj del sistema mientras se ejecuta tu programa. Afecta la hora actual pero no activa temporizadores; estos se dispararán exactamente como lo harían sin llamar a jest.setSystemTime().

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.setTimerTickMode(mode)`

Permite configurar cómo avanzan el tiempo los temporizadores simulados (fake timers).

Opciones de configuración:

type TimerTickMode =
  | {mode: 'manual'}
  | {mode: 'nextAsync'}
  | {mode: 'interval'; delta?: number};

manual: Los temporizadores no avanzan sin llamadas explícitas y manuales a las APIs de tick (jest.advanceTimersByTime(ms), jest.runAllTimers(), etc).
nextAsync: El reloj interrumpirá continuamente el bucle de eventos (event loop) y luego ejecutará el siguiente temporizador hasta que el modo cambie.
interval: Equivale a especificar advanceTimers: true con un advanceTimeDelta. Si no se especifica el delta, se usará 20 por defecto.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

`jest.getRealSystemTime()`

Cuando el tiempo está simulado, Date.now() también estará simulado. Si necesitas acceder al tiempo real actual, puedes invocar esta función.

información

Esta función no está disponible cuando se usa la implementación de temporizadores falsos heredada.

Miscelánea

`jest.getSeed()`

Cada vez que Jest se ejecuta, se genera aleatoriamente un valor semilla que puedes usar en generadores pseudaleatorios u otros lugares.

consejo

Usa el flag --showSeed para mostrar la semilla en el resumen del reporte de pruebas. Para establecer manualmente el valor de la semilla usa el argumento CLI --seed=<num>.

`jest.isEnvironmentTornDown()`

Devuelve true si el entorno de pruebas ha sido desmontado.

`jest.retryTimes(numRetries, options?)`

Reintenta pruebas fallidas n veces hasta que pasen o se agoten los reintentos.

jest.retryTimes(3);

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

Si está habilitada la opción logErrorsBeforeRetry, los errores que causaron el fallo se mostrarán en consola.

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

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

waitBeforeRetry son los milisegundos de espera antes de reintentar.

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

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

La opción retryImmediately reintenta la prueba fallida inmediatamente después del fallo. Si no se especifica, las pruebas se reintentan después de que Jest termine de ejecutar otras pruebas del archivo.

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

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

Devuelve el objeto jest para encadenamiento.

precaución

jest.retryTimes() debe declararse al nivel superior del archivo de pruebas o dentro de un bloque describe.

información

Esta función solo está disponible con el runner predeterminado jest-circus.

`jest.setTimeout(timeout)`

Establece el intervalo de tiempo de espera predeterminado (en milisegundos) para todas las pruebas y hooks before/after en el archivo de prueba. Esto solo afecta al archivo de prueba desde el que se llama esta función. El intervalo de tiempo de espera predeterminado es de 5 segundos si no se llama este método.

Ejemplo:

jest.setTimeout(1000); // 1 second

consejo

Para establecer intervalos de tiempo de espera en diferentes pruebas dentro del mismo archivo, usa la opción timeout en cada prueba individual.

Si quieres establecer el tiempo de espera para todos los archivos de prueba, usa la opción de configuración testTimeout.

Métodos
Módulos simulados (Mocks)
Funciones Simuladas
Temporizadores falsos
Miscelánea

Métodos​

Módulos simulados (Mocks)​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Function​

Class​

Object​

Array​

Primitives​

jest.mock(moduleName, factory, options)​

jest.Mocked<Source>​

jest.mocked(source, 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.onGenerateMock(cb)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

Funciones Simuladas​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

Métodos espiados y la palabra clave using​

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

jest.Replaced<Source>​

jest.Spied<Source>​

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

Temporizadores falsos​

jest.useFakeTimers(fakeTimersConfig?)​

jest.useRealTimers()​

jest.runAllTicks()​

jest.runAllTimers()​

jest.runAllTimersAsync()​

jest.runAllImmediates()​

jest.advanceTimersByTime(msToRun)​

jest.advanceTimersByTimeAsync(msToRun)​

jest.runOnlyPendingTimers()​

jest.runOnlyPendingTimersAsync()​

jest.advanceTimersToNextTimer(steps)​

jest.advanceTimersToNextTimerAsync(steps)​

jest.advanceTimersToNextFrame()​

jest.clearAllTimers()​

jest.getTimerCount()​

jest.now()​

jest.setSystemTime(now?: number | Date)​

jest.setTimerTickMode(mode)​

jest.getRealSystemTime()​

Miscelánea​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Métodos

Módulos simulados (Mocks)

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Function`

`Class`

`Object`

`Array`

`Primitives`

`jest.mock(moduleName, factory, options)`

`jest.Mocked<Source>`

`jest.mocked(source, 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.onGenerateMock(cb)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

Funciones Simuladas

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

`jest.replaceProperty(object, propertyKey, value)`

`jest.spyOn(object, methodName)`

Métodos espiados y la palabra clave `using`

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

`jest.Replaced<Source>`

`jest.Spied<Source>`

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

Temporizadores falsos

`jest.useFakeTimers(fakeTimersConfig?)`

`jest.useRealTimers()`

`jest.runAllTicks()`

`jest.runAllTimers()`

`jest.runAllTimersAsync()`

`jest.runAllImmediates()`

`jest.advanceTimersByTime(msToRun)`

`jest.advanceTimersByTimeAsync(msToRun)`

`jest.runOnlyPendingTimers()`

`jest.runOnlyPendingTimersAsync()`

`jest.advanceTimersToNextTimer(steps)`

`jest.advanceTimersToNextTimerAsync(steps)`

`jest.advanceTimersToNextFrame()`

`jest.clearAllTimers()`

`jest.getTimerCount()`

`jest.now()`

`jest.setSystemTime(now?: number | Date)`

`jest.setTimerTickMode(mode)`

`jest.getRealSystemTime()`

Miscelánea

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`