Versão: Próximo

O Objeto Jest

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

O objeto jest está automaticamente disponível em todos os arquivos de teste. Os métodos no objeto jest ajudam a criar mocks e controlar o comportamento geral do Jest. Também pode ser importado explicitamente via import {jest} from '@jest/globals'.

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

"message": "informação"

Os exemplos em TypeScript desta página só funcionarão conforme documentado se você importar explicitamente as APIs do Jest:

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

Consulte o guia Primeiros Passos para detalhes sobre como configurar o Jest com TypeScript.

Mock de Módulos

`jest.disableAutomock()`

Desativa o mock automático no carregador de módulos.

"message": "informação"

O mock automático precisa estar habilitado via opção de configuração automock para este método surtir efeito. Consulte a documentação da opção para detalhes.

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;

Após chamar disableAutomock(), todos os require() retornarão as versões reais dos módulos (em vez de versões mockadas).

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

É útil quando você precisa mockar poucas dependências em comparação com muitas que não devem ser mockadas. Por exemplo, ao testar módulos com muitas dependências consideradas "detalhes de implementação", não é recomendado mocká-las.

Exemplos de "detalhes de implementação": recursos nativos da linguagem (como métodos de Array.prototype), utilitários comuns (underscore, lodash, etc.) e bibliotecas como React.js.

Retorna o objeto jest para encadeamento.

"message": "dica"

Com babel-jest, chamadas de disableAutomock() são automaticamente elevadas para o topo do bloco. Use autoMockOff() para evitar explicitamente esse comportamento.

`jest.enableAutomock()`

Ativa o mock automático no carregador de módulos.

"message": "informação"

Para detalhes sobre mock automático, consulte a opção automock.

Exemplo:

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

Retorna o objeto jest para encadeamento.

"message": "dica"

Com babel-jest, chamadas de enableAutomock são automaticamente elevadas para o topo do bloco. Use autoMockOn para evitar explicitamente esse comportamento.

`jest.createMockFromModule(moduleName)`

Gera uma versão mockada do módulo usando o sistema de mock automático.

Útil para criar mocks manuais que estendem o comportamento do 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);
});

É assim que createMockFromModule irá simular os seguintes tipos de dados:

`Function`

Cria uma nova função mock sem parâmetros que retorna undefined. Funciona também com funções async.

`Class`

Cria uma nova classe mantendo a interface original, com todos os métodos e propriedades mockados.

`Object`

Cria um objeto clonado profundamente com chaves originais e valores mockados.

`Array`

Cria um novo array vazio, ignorando o original.

`Primitives`

Cria uma nova propriedade com o mesmo valor primitivo da original.

Exemplo:

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 um módulo com uma versão automockada quando ele é carregado. Os parâmetros factory e options são opcionais. Por exemplo:

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.

O segundo argumento pode ser usado para especificar uma fábrica de módulo explícita que será executada em vez de usar o recurso de automocking do 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';

Ao usar o parâmetro factory para um módulo ES6 com exportação padrão, a propriedade __esModule: true precisa ser especificada. Normalmente essa propriedade é gerada pelo Babel/TypeScript, mas aqui precisa ser definida manualmente. Ao importar uma exportação padrão, isso instrui a importar a propriedade chamada default do objeto de exportação:

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

O terceiro argumento pode ser usado para criar mocks virtuais – simulações de módulos que não existem em nenhum lugar do 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},
);

cuidado

Importar um módulo em um arquivo de configuração (especificado por setupFilesAfterEnv) impedirá a simulação do módulo em questão, bem como de todos os módulos que ele importa.

Módulos simulados com jest.mock são mockados apenas para o arquivo que chama jest.mock. Outro arquivo que importa o módulo receberá a implementação original, mesmo que seja executado após o arquivo de teste que simula o módulo.

Retorna o objeto jest para encadeamento.

"message": "dica"

Escrevendo testes em TypeScript? Use o tipo utilitário jest.Mocked ou o método auxiliar jest.mocked() para tipar seus módulos simulados.

`jest.Mocked<Source>`

Consulte o capítulo Uso com TypeScript da página Funções de Simulação para documentação.

`jest.mocked(source, options?)`

Consulte o capítulo Uso com TypeScript da página Funções de Simulação para documentação.

`jest.unmock(moduleName)`

Indica que o sistema de módulos nunca deve retornar uma versão simulada do módulo especificado a partir de require() (ou seja, sempre deve retornar o módulo real).

O uso mais comum dessa API é especificar o módulo que um teste pretende verificar (e, portanto, não deseja que seja automockado).

Retorna o objeto jest para encadeamento.

`jest.deepUnmock(moduleName)`

Indica que o sistema de módulos nunca deve retornar uma versão simulada do módulo especificado e de suas dependências.

Retorna o objeto jest para encadeamento.

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

Ao usar babel-jest, chamadas para mock são automaticamente elevadas para o topo do bloco de código. Use este método se quiser evitar explicitamente esse comportamento.

Um exemplo útil disso é quando você deseja simular um módulo de maneira diferente dentro do mesmo arquivo:

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() com imports ES6 requer etapas adicionais. Siga estas instruções se não quiser usar require em seus testes:

Precisamos especificar a propriedade __esModule: true (veja a API jest.mock() para mais informações).
Imports estáticos de módulos ES6 são elevados para o topo do arquivo, então precisamos importá-los dinamicamente usando import().
Por fim, precisamos de um ambiente que suporte importação dinâmica. Consulte Usando Babel para a configuração inicial. Em seguida, adicione o plugin babel-plugin-dynamic-import-node, ou equivalente, à sua configuração do Babel para habilitar a importação dinâmica no 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');
  });
});

Retorna o objeto jest para encadeamento.

`jest.dontMock(moduleName)`

Ao usar babel-jest, chamadas para unmock são automaticamente elevadas para o topo do bloco de código. Use este método se desejar evitar explicitamente esse comportamento.

Retorna o objeto jest para encadeamento.

`jest.setMock(moduleName, moduleExports)`

Fornece explicitamente o objeto mock que o sistema de módulos deve retornar para o módulo especificado.

Ocasionalmente, o mock gerado automaticamente pelo sistema de módulos pode não ser adequado para suas necessidades de teste. Normalmente, nesses casos, você deve criar um mock manual mais apropriado. Porém, em situações extremamente raras, até mesmo um mock manual pode ser insuficiente, exigindo que você construa o mock diretamente no teste.

Nesses cenários raros, você pode usar esta API para preencher manualmente o registro de mocks do sistema de módulos.

Retorna o objeto jest para encadeamento.

"message": "informação"

Recomenda-se usar jest.mock() em seu lugar. O segundo argumento da API jest.mock é uma fábrica de módulos em vez do objeto de módulo exportado esperado.

`jest.requireActual(moduleName)`

Retorna o módulo real em vez de um mock, ignorando todas as verificações sobre se o módulo deve receber uma implementação mockada ou não.

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

Retorna um mock do módulo em vez do módulo real, ignorando todas as verificações sobre se o módulo deve ser carregado normalmente ou não.

`jest.onGenerateMock(cb)`

Registra uma função de callback que é invocada sempre que Jest gera um mock para um módulo. Esse callback permite modificar o mock antes que seja retornado para o resto dos testes.

Parâmetros do callback:

modulePath: string - O caminho absoluto para o módulo que está sendo mockado.
moduleMock: T - O objeto mock que Jest gerou para o módulo. Este objeto pode ser modificado ou substituído antes do retorno.

Comportamento:

Múltiplos callbacks registrados via chamadas consecutivas de onGenerateMock serão invocados na ordem em que foram adicionados.
Cada callback recebe como moduleMock a saída do callback anterior, permitindo aplicar múltiplas camadas de transformações ao mesmo 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

"message": "nota"

O callback onGenerateMock não é chamado para mocks criados manualmente, como:

Mocks definidos em pastas __mocks__
Fábricas explícitas fornecidas via jest.mock('moduleName', () => { ... })

`jest.resetModules()`

Reinicia o registro de módulos - o cache de todos os módulos carregados. É útil para isolar módulos onde estados locais podem causar conflitos entre testes.

Exemplo:

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

Exemplo em um teste:

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

Retorna o objeto jest para encadeamento.

`jest.isolateModules(fn)`

jest.isolateModules(fn) vai além de jest.resetModules(), criando um registro sandbox para módulos carregados dentro da função callback. Isso é útil para isolar módulos específicos em cada teste, evitando conflitos de estado local entre testes.

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

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync() é equivalente a jest.isolateModules(), mas para callbacks assíncronos. O chamador deve await a conclusão de isolateModulesAsync.

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

const otherCopyOfMyModule = await import('myModule');

Funções Mock

`jest.fn(implementation?)`

Retorna uma nova função mock não utilizada. Aceita opcionalmente uma implementação mock.

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

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

Consulte a página Funções Mock para detalhes sobre uso com TypeScript.

`jest.isMockFunction(fn)`

Determina se a função fornecida é uma função mockada.

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

Substitui object[propertyKey] por um value. A propriedade já deve existir no objeto. A mesma propriedade pode ser substituída múltiplas vezes. Retorna uma propriedade substituída do Jest.

Para mockar propriedades definidas como getters ou setters, use jest.spyOn(object, methodName, accessType). Para mockar funções, use jest.spyOn(object, methodName).

Todas as propriedades substituídas com jest.replaceProperty podem ser restauradas ao valor original chamando jest.restoreAllMocks no método afterEach.

Exemplo:

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

module.exports = utils;

Exemplo de teste:

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

Cria uma função mockada similar a jest.fn mas também rastreia chamadas a object[methodName]. Retorna uma função mockada do Jest.

Por padrão, jest.spyOn também executa o método espionado. Este comportamento difere da maioria das bibliotecas de teste. Para sobrescrever a função original, use jest.spyOn(object, methodName).mockImplementation(() => customImplementation) ou object[methodName] = jest.fn(() => customImplementation).

Como jest.spyOn é um mock, você pode restaurar o estado inicial chamando jest.restoreAllMocks no corpo do callback passado para o hook afterEach.

Exemplo:

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

module.exports = video;

Exemplo de teste:

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 espionados e a palavra-chave `using`

Se seu código utiliza "gerenciamento explícito de recursos" (ex: TypeScript >= 5.2 ou plugin @babel/plugin-proposal-explicit-resource-management), você pode combinar spyOn com a palavra-chave using:

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

Este código é semanticamente equivalente a:

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

Dessa forma, seu spy será automaticamente restaurado ao valor original quando o bloco de código atual for finalizado.

Você pode ir além e usar blocos de código para restringir seu mock apenas a parte do teste sem prejudicar a legibilidade.

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

Se receber um aviso que Symbol.dispose não existe, talvez seja necessário implementar um polyfill, ex:

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

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

Desde o Jest 22.1.0+, jest.spyOn aceita um terceiro argumento opcional accessType que pode ser 'get' ou 'set', útil para espionar getters ou setters respectivamente.

Exemplo:

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;

Exemplo de teste:

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

Veja o capítulo Uso com TypeScript na página de Funções Mock para documentação.

`jest.Spied<Source>`

Consulte o capítulo Uso com TypeScript na página de Funções de Mock para a documentação.

`jest.clearAllMocks()`

Limpa as propriedades mock.calls, mock.instances, mock.contexts e mock.results de todos os mocks. Equivalente a chamar .mockClear() em toda função mockada.

Retorna o objeto jest para encadeamento.

`jest.resetAllMocks()`

Reinicia o estado de todos os mocks. Equivalente a chamar .mockReset() em toda função mockada.

Retorna o objeto jest para encadeamento.

`jest.restoreAllMocks()`

Restaura todos os mocks e propriedades substituídas para seus valores originais. Equivalente a chamar .mockRestore() em toda função mockada e .restore() em toda propriedade substituída. Atenção: jest.restoreAllMocks() funciona apenas para mocks criados com jest.spyOn() e propriedades substituídas com jest.replaceProperty(); outros mocks exigirão restauração manual.

Temporizadores Falsos

`jest.useFakeTimers(fakeTimersConfig?)`

Instrui o Jest a usar versões falsas das APIs globais de data, desempenho, tempo e temporizadores. A implementação utiliza @sinonjs/fake-timers.

Substitui Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() por uma implementação que obtém tempo do relógio falso.

Em Node.js: process.hrtime, process.nextTick(). Em JSDOM: requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() também são substituídos.

Opções de configuração:

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

Chamar jest.useFakeTimers() ativa temporizadores falsos para todos os testes no arquivo até que os originais sejam restaurados com jest.useRealTimers().

Você pode chamar jest.useFakeTimers() ou jest.useRealTimers() de qualquer lugar: no nível superior, dentro de um bloco test, etc. Tenha em mente que esta é uma operação global e afetará outros testes no mesmo arquivo. Chamar jest.useFakeTimers() novamente no mesmo arquivo de teste reiniciará o estado interno (ex: contagem de temporizadores) e reinstalará os temporizadores falsos com as opções fornecidas:

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 Legados

Para casos específicos, ative a implementação legada (opções adicionais não suportadas):

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

Substitui setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() por funções mock do Jest. Em Node.js: process.nextTick(). Em JSDOM: requestAnimationFrame(), cancelAnimationFrame() também são substituídos.

Retorna o objeto jest para encadeamento.

`jest.useRealTimers()`

Restaura as implementações originais das APIs globais de data, desempenho, tempo e temporizadores. Exemplo: chamar jest.useRealTimers() no hook afterEach restaura temporizadores após cada teste:

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

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

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

Retorna o objeto jest para encadeamento.

`jest.runAllTicks()`

Esgota a fila de microtarefas (normalmente acessada via process.nextTick no Node.js).

Quando esta API é chamada, todas as microtarefas pendentes que foram enfileiradas via process.nextTick serão executadas. Além disso, se essas microtarefas agendarem novas microtarefas, elas serão continuamente esgotadas até que não reste nenhuma microtarefa na fila.

`jest.runAllTimers()`

Esgota tanto a fila de macrotarefas (ou seja, todas as tarefas enfileiradas por setTimeout(), setInterval() e setImmediate()) quanto a fila de microtarefas (normalmente acessada no Node.js via process.nextTick).

Quando esta API é chamada, todas as macrotarefas e microtarefas pendentes serão executadas. Se essas tarefas agendarem novas tarefas, elas serão continuamente esgotadas até que não reste nenhuma tarefa na fila.

Isso é frequentemente útil para executar setTimeouts de forma síncrona durante um teste, permitindo fazer asserções síncronas sobre comportamentos que só ocorreriam após a execução dos callbacks de setTimeout() ou setInterval(). Consulte a documentação Timer mocks para mais informações.

`jest.runAllTimersAsync()`

Equivalente assíncrono de jest.runAllTimers(). Permite que qualquer callback de promise agendada execute antes de rodar os timers.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.runAllImmediates()`

Esgota todas as tarefas enfileiradas por setImmediate().

"message": "informação"

Esta função só está disponível ao usar a implementação legada de timers simulados.

`jest.advanceTimersByTime(msToRun)`

Executa apenas a fila de macro tarefas (ou seja, todas as tarefas enfileiradas por setTimeout(), setInterval() e setImmediate()).

Quando esta API é chamada, todos os timers são avançados em msToRun milissegundos. Todas as "macro-tarefas" pendentes enfileiradas via setTimeout() ou setInterval(), e que seriam executadas dentro desse intervalo de tempo, serão executadas. Além disso, se essas macro-tarefas agendarem novas macro-tarefas que seriam executadas no mesmo intervalo de tempo, elas serão executadas até que não reste nenhuma macro-tarefa na fila que deva ser executada dentro de msToRun milissegundos.

`jest.advanceTimersByTimeAsync(msToRun)`

Equivalente assíncrono de jest.advanceTimersByTime(msToRun). Permite que qualquer callback de promise agendada execute antes de rodar os timers.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.runOnlyPendingTimers()`

Executa apenas as macro-tarefas que estão atualmente pendentes (ou seja, apenas tarefas enfileiradas por setTimeout() ou setInterval() até este momento). Se qualquer macro-tarefa pendente agendar novas macro-tarefas, essas novas tarefas não serão executadas por esta chamada.

Isso é útil para cenários como um módulo em teste que agenda um setTimeout() cujo callback agenda outro setTimeout() recursivamente (significando que o agendamento nunca para). Nesses casos, é útil poder avançar no tempo um passo de cada vez.

`jest.runOnlyPendingTimersAsync()`

Equivalente assíncrono de jest.runOnlyPendingTimers(). Permite que qualquer callback de promise agendada execute antes de rodar os timers.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.advanceTimersToNextTimer(steps)`

Avança todos os timers pelos milissegundos necessários para que apenas os próximos timeouts/intervals sejam executados.

Opcionalmente, você pode fornecer steps para que ele execute steps quantidade de próximos timeouts/intervals.

`jest.advanceTimersToNextTimerAsync(steps)`

Equivalente assíncrono de jest.advanceTimersToNextTimer(steps). Permite que quaisquer callbacks de promessas agendadas sejam executados antes de avançar os temporizadores.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.advanceTimersToNextFrame()`

Avança todos os temporizadores pelos milissegundos necessários para executar callbacks agendados com requestAnimationFrame. advanceTimersToNextFrame() é uma forma útil de executar código agendado usando requestAnimationFrame.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.clearAllTimers()`

Remove todos os temporizadores pendentes do sistema de temporização.

Isso significa que, se algum temporizador foi agendado (mas ainda não executado), ele será cancelado e nunca terá oportunidade de executar no futuro.

`jest.getTimerCount()`

Retorna o número de temporizadores simulados que ainda restam para executar.

`jest.now()`

Retorna o tempo atual em ms do relógio interno. Equivale a Date.now() se temporizadores reais estiverem em uso ou se Date estiver simulado. Em outros casos (como temporizadores legados), pode ser útil para implementar simulações customizadas de Date.now(), performance.now(), etc.

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

Define o tempo atual do sistema usado por temporizadores simulados. Simula um usuário alterando o relógio do sistema durante a execução do seu programa. Afeta o tempo atual mas não dispara temporizadores automaticamente - eles serão acionados exatamente como seriam sem a chamada para jest.setSystemTime().

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.setTimerTickMode(mode)`

Permite configurar como os timers simulados avançam no tempo.

Opções de configuração:

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

manual: Os timers não avançam sem chamadas manuais explícitas às APIs de tick (jest.advanceTimersByTime(ms), jest.runAllTimers(), etc).
nextAsync: O relógio quebrará continuamente o event loop e executará o próximo timer até que o modo seja alterado.
interval: Equivale a especificar advanceTimers: true com um advanceTimeDelta. Se o delta não for especificado, 20 será usado por padrão.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

`jest.getRealSystemTime()`

Quando o tempo está simulado, Date.now() também será simulado. Se por algum motivo você precisar acessar o tempo real atual, pode invocar esta função.

"message": "informação"

Esta função não está disponível ao usar a implementação legada de temporizadores simulados.

Diversos

`jest.getSeed()`

Sempre que o Jest é executado, um valor de seed é gerado aleatoriamente para uso em geradores pseudoaleatórios ou outras aplicações.

"message": "dica"

Use a flag --showSeed para exibir a seed no resumo do relatório de testes. Para definir manualmente o valor da seed, use o argumento CLI --seed=<num>.

`jest.isEnvironmentTornDown()`

Retorna true se o ambiente de teste foi finalizado.

`jest.retryTimes(numRetries, options?)`

Executa testes falhos n vezes até que passem ou até esgotar o número máximo de tentativas.

jest.retryTimes(3);

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

Se a opção logErrorsBeforeRetry estiver ativada, erros que causaram falha serão registrados no console.

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

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

waitBeforeRetry define os milissegundos de espera antes de cada nova tentativa.

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

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

A opção retryImmediately executa uma nova tentativa imediatamente após a falha. Sem esta opção, as novas tentativas ocorrem após todos os outros testes do arquivo.

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

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

Retorna o objeto jest para encadeamento.

cuidado

jest.retryTimes() deve ser declarado no nível superior do arquivo de teste ou dentro de um bloco describe.

"message": "informação"

Esta função está disponível apenas com o runner padrão jest-circus.

`jest.setTimeout(timeout)`

Define o intervalo de timeout padrão (em milissegundos) para todos os testes e hooks before/after no arquivo de teste. Isso afeta apenas o arquivo de teste de onde esta função é chamada. O intervalo de timeout padrão é de 5 segundos se este método não for chamado.

Exemplo:

jest.setTimeout(1000); // 1 second

"message": "dica"

Para definir intervalos de timeout diferentes em testes do mesmo arquivo, use a opção timeout em cada teste individual.

Se quiser definir o timeout para todos os arquivos de teste, use a opção de configuração testTimeout.

Métodos
Mock de Módulos
Funções Mock
Temporizadores Falsos
Diversos

Métodos​

Mock de Módulos​

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

Funções Mock​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

Métodos espionados e a palavra-chave 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()​

Diversos​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Métodos

Mock de Módulos

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

Funções Mock

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

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

`jest.spyOn(object, methodName)`

Métodos espionados e a palavra-chave `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()`

Diversos

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`