Jest

Translate this Doc

The Jest Object

O objeto jest é automaticamente inserido no escopo de cada arquivo de teste. Os métodos no objeto jest ajudam a criar simulações (mock, em inglês) e deixam você controlar o comportamento geral de Jest.

Métodos #

Referência #

jest.clearAllTimers() #

Remove quaisquer temporizadores pendentes do sistema de temporizador.

Isto significa que se quaisquer temporizadores foram programados (mas ainda não foram executados), eles serão apagados e nunca terão a oportunidade de executar no futuro.

jest.disableAutomock() #

Desabilita simulações automáticas no carregador de módulo.

Depois que esse método é chamado, todos os require() irão retornar as versões reais de cada módulo (em vez de uma versão simulada, ou mocked).

Isto é geralmente útil quando você tiver um cenário onde o número de dependências que se quer simular (mock, em inglês) é muito menor do que o número de dependências que você não quer. Por exemplo, se você estiver escrevendo um teste para um módulo que utiliza um grande número de dependências que podem razoavelmente ser classificadas como "detalhes de implementação" do módulo, então você provavelmente não quer simular elas.

Exemplos de dependências que podem ser considerados "detalhes de implementação" são coisas que variam de built-ins de linguagem (por exemplo, métodos Array.prototype) para métodos de utilitário altamente comuns (por exemplo, underscore/lo-dash, utilidades de array, etc) e bibliotecas inteiras como React.js.

Retorna o objeto jest para encadeamento.

Nota: Este método anteriormente foi chamado autoMockOff. Ao usar babel-jest, chamadas para disableAutomock serão automaticamente içadas (hoisted, em inglês) até o topo do bloco de código. Use autoMockOff se você quiser evitar explicitamente esse comportamento.

jest.enableAutomock() #

Habilita simulações automáticas no carregador de módulo.

Retorna o objeto jest para encadeamento.

Nota: Este método anteriormente foi chamado autoMockOn. Ao usar babel-jest, chamadas para enableAutomock serão automaticamente içadas (hoisted, em inglês) até o topo do bloco de código. Use autoMockOn se você quiser evitar explicitamente esse comportamento.

jest.fn(implementation) #

Retorna uma nova, não utilizada função de simulação. Opcionalmente, toma uma implementação de simulação (mock, em inglês).

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

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

jest.isMockFunction(fn) #

Determina se a função dada é uma função simulada.

jest.genMockFromModule(moduleName) #

Dado o nome de um módulo, use o sistema automático de simulação para gerar uma versão simulada do módulo para você.

Isso é útil quando você deseja criar uma simulação manual que estende o comportamento da simulação automática.

jest.mock(moduleName, factory, options) #

Simula um módulo com uma versão auto simulada quando ele está sendo "required". 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 um módulo factory explícito que está sendo executado em vez de usar o recurso de automocking do Jest:

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

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

O terceiro argumento pode ser usado para criar simulações virtuais – simulações de módulos que não existem em qualquer lugar no sistema:

jest.mock('../moduleName', () => {
  /*
   * Implementação personalizada de um módulo que não existe em JS,
   * como um módulo gerado ou um módulo nativo do react-native.
   */
}, {virtual: true});

Aviso: Importar um módulo em um arquivo de instalação (conforme especificado pelo setupTestFrameworkScriptFile) impedirá a simulação para o módulo em questão, bem como todos os módulos que ele importa.

Módulos que são simulados (mocked, em inglês) com jest.mock são simulados apenas para o arquivo que chama jest.mock. Outro arquivo que importa o módulo receberá a implementação original, mesmo se executado após o arquivo de teste que simula o módulo.

Retorna o objeto jest para encadeamento.

jest.unmock(moduleName) #

Indica que o sistema de módulo nunca deve retornar uma versão simulada (mocked, em inglês) do módulo especificado no require() (por exemplo, que ele sempre deve retornar o módulo real).

O uso mais comum dessa API é para especificar ao módulo que um determinado teste pretende testar (e, portanto, não quer ser automaticamente simulado).

Retorna o objeto jest para encadeamento.

jest.doMock(moduleName, factory, options) #

Ao usar babel-jest, chamadas para mock serão automaticamente içadas (hoisted, em inglês) até o topo do bloco de código. Use este método se você deseja evitar explicitamente esse comportamento.

Um exemplo de quando isso é útil é quando você quer simular (mock, em inglês) de outra maneira um módulo dentro do mesmo arquivo:

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

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toEqual(1);
});

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

Retorna o objeto jest para encadeamento.

jest.dontMock(moduleName) #

Ao usar babel-jest, chamadas para unmock serão automaticamente içadas (hoisted, em inglês) até o topo do bloco de código. Use este método se você deseja evitar explicitamente esse comportamento.

Retorna o objeto jest para encadeamento.

jest.clearAllMocks() #

Limpa as propriedades mock.calls e mock.instances de todas as simulações. Equivalente a chamar .mockClear() em cada função de simulação.

Retorna o objeto jest para encadeamento.

jest.resetAllMocks() #

Redefine o estado de todas as simulações. Equivalente a chamar .mockReset() em cada função simulada.

Retorna o objeto jest para encadeamento.

jest.restoreAllMocks() #

disponível no Jest 20.1.0+ #

Restaura todas as simulações (mocks, em inglês) para seu valor original. Equivalente a chamar .mockRestore em cada função simulada. Cuidado que jest.restoreAllMocks() só funciona quando a simulação foi criada com jest.spyOn; outras simulações vão exigir você restaurá-las manualmente.

jest.resetModules() #

Redefine o registro do módulo - o cache de todos os módulos necessários. Isso é útil para isolar módulos onde o estado local pode entrar em conflito entre os 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.runAllTicks() #

Esgota a pilha de micro-task (geralmente usando um interface node via process.nextTick).

Quando esta API for chamada, todas micro-tasks pendentes que foram empilhadas via process.nextTick serão executadas. Adicionalmente, caso estas micro-tasks agendem novas micro-tasks, essas por sua vez serão esgotadas até que não haja mais micro-tasks na fila.

jest.runAllTimers() #

Esgota a fila de macro-task (ou seja, todas as tarefas enfileiradas por setTimeout(), setInterval() e setImmediate()).

Quando esta API é chamada, todas as "macro-tasks" pendentes que foram enfileiradas via setTimeout() ou setInterval() serão executadas. Adicionalmente, caso estas macro-tasks agendem novas macro-tasks, essas por sua vez serão esgotadas até que não haja mais macro-tasks na fila.

Isso muitas vezes é útil para executar de modo síncrono setTimeouts durante um teste para verificar sincronicamente algum comportamento que só aconteceria após as "callbacks" setTimeout() ou setInterval() executarem. Consulte a documentação Simulações de Temporizador para obter mais informações.

jest.runAllImmediates() #

Esgota todas as tarefas enfileiradas por setImmediate().

jest.runTimersToTime(msToRun) #

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

Quando esta API é chamada, todas as "macro-tasks" pendentes que foram enfileiradas via setTimeout() ou setInterval(), e que serão executadas dentro de msToRun milissegundos, serão executadas. Adicionalmente, caso estas macro-tarefas agendem novas macro-tarefas que seriam executadas dentro do mesmo prazo, aquelas serão executadas até que não haja mais nenhuma macro-tarefa restante na fila que deve ser executada dentro de msToRun milissegundos.

jest.runOnlyPendingTimers() #

Executa somente as macro-tasks que estão atualmente pendentes (ou seja, apenas as tarefas que foram enfileiradas por setTimeout() ou setInterval() até este ponto). Se qualquer uma das macro-tasks atualmente pendentes agendar novas macro-tasks, essas novas tarefas não serão executadas por essa chamada.

Isso é útil para cenários como aquele onde o módulo sendo testado agendará um setTimeout() cuja "callback" agenda outro setTimeout() recursivamente (ou seja, o agendamento nunca para). Nesses cenários, é útil ser capaz de executar para a frente no tempo, um passo de cada vez.

jest.setMock(moduleName, moduleExports) #

Explicitamente fornece o objeto simulado (mock, em inglês) que o sistema de módulo deve retornar para o módulo especificado.

Às vezes, há ocasiões em que a simulação automaticamente gerada, que o sistema de módulo normalmente lhe providencia, não é adequada o suficiente para suas necessidades de testes. Normalmente nessas circunstâncias você deve escrever uma simulação manual que for mais adequada para o módulo em questão. No entanto, em ocasiões extremamente raras, até mesmo um simulação manual não é apropriada para seus propósitos e você precisa construir a simulação você mesmo dentro de seu teste.

Nessas situações raras, você pode usar essa API para preencher manualmente o slot do registro "mock-module" no sistema do módulo.

Retorna o objeto jest para encadeamento.

Nota: recomenda-se usar ao invés jest.mock(). O segundo argumento da API jest.mock é uma fábrica de módulo, em vez do esperado objeto do módulo exportado.

jest.setTimeout(timeout) #

Define o tempo limite de execução padrão para testes antes/depois de ganchos em milissegundos.

Nota: O tempo limite de execução padrão é 5 segundos caso este método não seja chamado.

Exemplo:

jest.setTimeout(1000); // 1 segundo

jest.useFakeTimers() #

Instrui Jest para usar versões falsas das funções de temporizador padrão (setTimeout, setInterval, clearTimeout, clearInterval, nextTick, setImmediate e clearImmediate).

Retorna o objeto jest para encadeamento.

jest.useRealTimers() #

Instrui Jest para usar as versões reais das funções de temporizador padrão.

Retorna o objeto jest para encadeamento.

jest.spyOn(object, methodName) #

disponível no Jest 19.0.0+ #

Cria uma função de simulação (mock, em inglês) semelhante ao jest.fn mas também rastreia chamadas para object[methodName]. Retorna uma função de simulação Jest.

Nota: Por padrão, jest.spyOn também chama o método spied. Este é um comportamento diferente da maioria das outras bibliotecas de teste. Se você deseja substituir a função original, você pode usar jest.spyOn(object, methodName).mockImplementation(() => customImplementation) ou object[methodName] = jest.fn(() => customImplementation);

Exemplo:

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

module.exports = video;

Exemplo do teste:

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

test('plays video', () => {
  const spy = jest.spyOn(video, 'play');
  const isPlaying = video.play();

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);

  spy.mockReset();
  spy.mockRestore();
});
← AnteriorPróximo →