Ir para o conteúdo principal
Versão: 29.7

Funções Mock

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 →

Funções mock também são conhecidas como "spies" (espiãs), porque permitem que você espie o comportamento de uma função chamada indiretamente por outro código, indo além de apenas testar a saída. Você pode criar uma função mock com jest.fn(). Se nenhuma implementação for fornecida, a função mock retornará undefined quando invocada.

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.

Métodos​

Referência​

mockFn.getMockName()​

Retorna a string do nome mock definida pela chamada .mockName().

mockFn.mock.calls​

Um array contendo os argumentos de todas as chamadas feitas a esta função mock. Cada item do array é um array de argumentos passados durante a chamada.

Por exemplo: Uma função mock f chamada duas vezes com f('arg1', 'arg2') e depois com f('arg3', 'arg4') teria um array mock.calls com esta aparência:

[
  ['arg1', 'arg2'],
  ['arg3', 'arg4'],
];

mockFn.mock.results​

Um array contendo os resultados de todas as chamadas feitas a esta função mock. Cada entrada é um objeto com propriedades type e value. type pode ser:

  • 'return' - Indica que a chamada foi concluída com retorno normal.

  • 'throw' - Indica que a chamada foi concluída lançando um valor.

  • 'incomplete' - Indica que a chamada ainda não foi concluída. Isso ocorre se você testar o resultado de dentro da própria função mock ou de uma função chamada por ela.

A propriedade value contém o valor retornado ou lançado. value é indefinido quando type === 'incomplete'.

Por exemplo: Uma função mock f chamada três vezes, retornando 'result1', lançando um erro e depois retornando 'result2', teria um array mock.results com esta aparência:

[
  {
    type: 'return',
    value: 'result1',
  },
  {
    type: 'throw',
    value: {
      /* Error instance */
    },
  },
  {
    type: 'return',
    value: 'result2',
  },
];

mockFn.mock.instances​

Um array contendo todas as instâncias de objeto instanciadas desta função mock usando new.

Por exemplo: Uma função mock instanciada duas vezes teria o seguinte array mock.instances:

const mockFn = jest.fn();

const a = new mockFn();
const b = new mockFn();

mockFn.mock.instances[0] === a; // true
mockFn.mock.instances[1] === b; // true

mockFn.mock.contexts​

Um array contendo os contextos de todas as chamadas da função mock.

Contexto é o valor this recebido por uma função quando chamada. Pode ser definido usando Function.prototype.bind, Function.prototype.call ou Function.prototype.apply.

Por exemplo:

const mockFn = jest.fn();

const boundMockFn = mockFn.bind(thisContext0);
boundMockFn('a', 'b');
mockFn.call(thisContext1, 'a', 'b');
mockFn.apply(thisContext2, ['a', 'b']);

mockFn.mock.contexts[0] === thisContext0; // true
mockFn.mock.contexts[1] === thisContext1; // true
mockFn.mock.contexts[2] === thisContext2; // true

mockFn.mock.lastCall​

Um array contendo os argumentos da última chamada feita a esta função mock. Retorna undefined se a função não foi chamada.

Por exemplo: Uma função mock f chamada duas vezes com f('arg1', 'arg2') e depois com f('arg3', 'arg4') teria um array mock.lastCall com esta aparência:

['arg3', 'arg4'];

mockFn.mockClear()​

Limpa todas as informações armazenadas nos arrays mockFn.mock.calls, mockFn.mock.instances, mockFn.mock.contexts e mockFn.mock.results. Útil para limpar dados de uso entre asserções.

A opção de configuração clearMocks limpa mocks automaticamente antes de cada teste.

cuidado

Atenção: mockFn.mockClear() substituirá todo o objeto mockFn.mock, não apenas redefinirá os valores das suas propriedades! Portanto, evite atribuir mockFn.mock a outras variáveis, temporárias ou não, para garantir que você não acesse dados desatualizados.

mockFn.mockReset()​

Faz tudo que mockFn.mockClear() faz, e adicionalmente substitui a implementação do mock por uma função vazia que retorna undefined.

A opção de configuração resetMocks está disponível para redefinir mocks automaticamente antes de cada teste.

mockFn.mockRestore()​

Faz tudo que mockFn.mockReset() faz, e também restaura a implementação original (não simulada).

Isso é útil quando você deseja simular funções em certos casos de teste e restaurar a implementação original em outros.

A opção de configuração restoreMocks está disponível para restaurar mocks automaticamente antes de cada teste.

"message": "informação"

mockFn.mockRestore() só funciona quando o mock foi criado com jest.spyOn(). Portanto, você precisa cuidar manualmente da restauração ao atribuir jest.fn() diretamente.

mockFn.mockImplementation(fn)​

Aceita uma função que deve ser usada como implementação do mock. O próprio mock continuará registrando todas as chamadas e instâncias originadas dele – a única diferença é que a implementação também será executada quando o mock for chamado.

"message": "dica"

jest.fn(implementation) é um atalho para jest.fn().mockImplementation(implementation).

const mockFn = jest.fn(scalar => 42 + scalar);

mockFn(0); // 42
mockFn(1); // 43

mockFn.mockImplementation(scalar => 36 + scalar);

mockFn(2); // 38
mockFn(3); // 39

.mockImplementation() também pode ser usado para simular construtores de classe:

SomeClass.js
module.exports = class SomeClass {
  method(a, b) {}
};
SomeClass.test.js
const SomeClass = require('./SomeClass');

jest.mock('./SomeClass'); // this happens automatically with automocking

const mockMethod = jest.fn();
SomeClass.mockImplementation(() => {
  return {
    method: mockMethod,
  };
});

const some = new SomeClass();
some.method('a', 'b');

console.log('Calls to method:', mockMethod.mock.calls);

mockFn.mockImplementationOnce(fn)​

Aceita uma função que será usada como implementação do mock para uma única chamada da função simulada. Pode ser encadeado para que chamadas sucessivas produzam resultados diferentes.

const mockFn = jest
  .fn()
  .mockImplementationOnce(cb => cb(null, true))
  .mockImplementationOnce(cb => cb(null, false));

mockFn((err, val) => console.log(val)); // true
mockFn((err, val) => console.log(val)); // false

Quando a função simulada esgotar as implementações definidas com .mockImplementationOnce(), executará a implementação padrão definida com jest.fn(() => defaultValue) ou .mockImplementation(() => defaultValue) se tiverem sido chamadas:

const mockFn = jest
  .fn(() => 'default')
  .mockImplementationOnce(() => 'first call')
  .mockImplementationOnce(() => 'second call');

mockFn(); // 'first call'
mockFn(); // 'second call'
mockFn(); // 'default'
mockFn(); // 'default'

mockFn.mockName(name)​

Aceita uma string para usar nos resultados de testes no lugar de 'jest.fn()', indicando qual função simulada está sendo referenciada.

Por exemplo:

const mockFn = jest.fn().mockName('mockedFunction');

// mockFn();
expect(mockFn).toHaveBeenCalled();

Resultará neste erro:

expect(mockedFunction).toHaveBeenCalled()

Expected number of calls: >= 1
Received number of calls:    0

mockFn.mockReturnThis()​

Forma abreviada para:

jest.fn(function () {
  return this;
});

mockFn.mockReturnValue(value)​

Forma abreviada para:

jest.fn().mockImplementation(() => value);

Aceita um valor que será retornado sempre que a função simulada for chamada.

const mock = jest.fn();

mock.mockReturnValue(42);
mock(); // 42

mock.mockReturnValue(43);
mock(); // 43

mockFn.mockReturnValueOnce(value)​

Forma abreviada para:

jest.fn().mockImplementationOnce(() => value);

Aceita um valor que será retornado para uma única chamada da função simulada. Pode ser encadeado para que chamadas sucessivas retornem valores diferentes. Quando não houver mais valores mockReturnValueOnce para usar, as chamadas retornarão o valor especificado por mockReturnValue.

const mockFn = jest
  .fn()
  .mockReturnValue('default')
  .mockReturnValueOnce('first call')
  .mockReturnValueOnce('second call');

mockFn(); // 'first call'
mockFn(); // 'second call'
mockFn(); // 'default'
mockFn(); // 'default'

mockFn.mockResolvedValue(value)​

Forma abreviada para:

jest.fn().mockImplementation(() => Promise.resolve(value));

Útil para simular funções assíncronas em testes assíncronos:

test('async test', async () => {
  const asyncMock = jest.fn().mockResolvedValue(43);

  await asyncMock(); // 43
});

mockFn.mockResolvedValueOnce(value)​

Forma abreviada para:

jest.fn().mockImplementationOnce(() => Promise.resolve(value));

Útil para resolver valores diferentes em múltiplas chamadas assíncronas:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockResolvedValue('default')
    .mockResolvedValueOnce('first call')
    .mockResolvedValueOnce('second call');

  await asyncMock(); // 'first call'
  await asyncMock(); // 'second call'
  await asyncMock(); // 'default'
  await asyncMock(); // 'default'
});

mockFn.mockRejectedValue(value)​

Forma abreviada para:

jest.fn().mockImplementation(() => Promise.reject(value));

Útil para criar funções simuladas assíncronas que sempre rejeitarão:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockRejectedValue(new Error('Async error message'));

  await asyncMock(); // throws 'Async error message'
});

mockFn.mockRejectedValueOnce(value)​

Forma abreviada para:

jest.fn().mockImplementationOnce(() => Promise.reject(value));

Útil junto com .mockResolvedValueOnce() ou para rejeitar com exceções diferentes em múltiplas chamadas assíncronas:

test('async test', async () => {
  const asyncMock = jest
    .fn()
    .mockResolvedValueOnce('first call')
    .mockRejectedValueOnce(new Error('Async error message'));

  await asyncMock(); // 'first call'
  await asyncMock(); // throws 'Async error message'
});

mockFn.withImplementation(fn, callback)​

Aceita uma função que deve ser usada temporariamente como implementação do mock enquanto o callback está sendo executado.

test('test', () => {
  const mock = jest.fn(() => 'outside callback');

  mock.withImplementation(
    () => 'inside callback',
    () => {
      mock(); // 'inside callback'
    },
  );

  mock(); // 'outside callback'
});

mockFn.withImplementation pode ser usado independentemente de o callback ser assíncrono (retornar um thenable) ou não. Se o callback for assíncrono, uma promise será retornada. Aguardar essa promise aguardará o callback e redefinirá a implementação.

test('async test', async () => {
  const mock = jest.fn(() => 'outside callback');

  // We await this call since the callback is async
  await mock.withImplementation(
    () => 'inside callback',
    async () => {
      mock(); // 'inside callback'
    },
  );

  mock(); // 'outside callback'
});

Propriedades Substituídas​

replacedProperty.replaceValue(value)​

Altera o valor de uma propriedade já substituída. Útil quando você deseja substituir uma propriedade e depois ajustar seu valor em testes específicos. Como alternativa, você pode chamar jest.replaceProperty() múltiplas vezes na mesma propriedade.

replacedProperty.restore()​

Restaura a propriedade do objeto para seu valor original.

Atenção: replacedProperty.restore() só funciona quando o valor da propriedade foi substituído com jest.replaceProperty().

A opção de configuração restoreMocks está disponível para restaurar propriedades substituídas automaticamente antes de cada teste.

Uso com TypeScript​

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.

jest.fn(implementation?)​

As tipagens corretas do mock serão inferidas se a implementação for passada para jest.fn(). Em muitos casos a implementação é omitida. Para garantir segurança de tipos, passe um argumento de tipo genérico (veja também os exemplos acima como referência):

import {expect, jest, test} from '@jest/globals';
import type add from './add';
import calculate from './calc';

test('calculate calls add', () => {
  // Create a new mock that can be used in place of `add`.
  const mockAdd = jest.fn<typeof add>();

  // `.mockImplementation()` now can infer that `a` and `b` are `number`
  // and that the returned value is a `number`.
  mockAdd.mockImplementation((a, b) => {
    // Yes, this mock is still adding two numbers but imagine this
    // was a complex function we are mocking.
    return a + b;
  });

  // `mockAdd` is properly typed and therefore accepted by anything
  // requiring `add`.
  calculate(mockAdd, 1, 2);

  expect(mockAdd).toHaveBeenCalledTimes(1);
  expect(mockAdd).toHaveBeenCalledWith(1, 2);
});

jest.Mock<T>​

Constrói o tipo de uma função mock (ex: tipo de retorno de jest.fn()). Útil para definir funções mock recursivas:

import {jest} from '@jest/globals';

const sumRecursively: jest.Mock<(value: number) => number> = jest.fn(value => {
  if (value === 0) {
    return 0;
  } else {
    return value + fn(value - 1);
  }
});

jest.Mocked<Source>​

O tipo utilitário jest.Mocked<Source> retorna o tipo Source encapsulado com as definições de tipo de função mock do Jest.

import {expect, jest, test} from '@jest/globals';
import type {fetch} from 'node-fetch';

jest.mock('node-fetch');

let mockedFetch: jest.Mocked<typeof fetch>;

afterEach(() => {
  mockedFetch.mockClear();
});

test('makes correct call', () => {
  mockedFetch = getMockedFetch();
  // ...
});

test('returns correct data', () => {
  mockedFetch = getMockedFetch();
  // ...
});

Tipos de classes, funções ou objetos podem ser passados como argumento para jest.Mocked<Source>. Para restringir o tipo de entrada, use: jest.MockedClass<Source>, jest.MockedFunction<Source> ou jest.MockedObject<Source>.

jest.Replaced<Source>​

O tipo utilitário jest.Replaced<Source> retorna o tipo Source encapsulado com as definições de tipo de propriedade substituída do Jest.

src/utils.ts
export function isLocalhost(): boolean {
  return process.env['HOSTNAME'] === 'localhost';
}
src/__tests__/utils.test.ts
import {afterEach, expect, it, jest} from '@jest/globals';
import {isLocalhost} from '../utils';

let replacedEnv: jest.Replaced<typeof process.env> | undefined = undefined;

afterEach(() => {
  replacedEnv?.restore();
});

it('isLocalhost should detect localhost environment', () => {
  replacedEnv = jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});

  expect(isLocalhost()).toBe(true);
});

it('isLocalhost should detect non-localhost environment', () => {
  replacedEnv = jest.replaceProperty(process, 'env', {HOSTNAME: 'example.com'});

  expect(isLocalhost()).toBe(false);
});

jest.mocked(source, options?)​

O método auxiliar mocked() encapsula os tipos do objeto source e seus membros aninhados com definições de tipo de função mock do Jest. Passe {shallow: true} como options para desabilitar o comportamento de mock profundo.

Retorna o objeto source.

song.ts
export const song = {
  one: {
    more: {
      time: (t: number) => {
        return t;
      },
    },
  },
};
song.test.ts
import {expect, jest, test} from '@jest/globals';
import {song} from './song';

jest.mock('./song');
jest.spyOn(console, 'log');

const mockedSong = jest.mocked(song);
// or through `jest.Mocked<Source>`
// const mockedSong = song as jest.Mocked<typeof song>;

test('deep method is typed correctly', () => {
  mockedSong.one.more.time.mockReturnValue(12);

  expect(mockedSong.one.more.time(10)).toBe(12);
  expect(mockedSong.one.more.time.mock.calls).toHaveLength(1);
});

test('direct usage', () => {
  jest.mocked(console.log).mockImplementation(() => {
    return;
  });

  console.log('one more time');

  expect(jest.mocked(console.log).mock.calls).toHaveLength(1);
});

jest.Spied<Source>​

Constrói o tipo de uma classe ou função espiada (ex: tipo de retorno de jest.spyOn()).

__utils__/setDateNow.ts
import {jest} from '@jest/globals';

export function setDateNow(now: number): jest.Spied<typeof Date.now> {
  return jest.spyOn(Date, 'now').mockReturnValue(now);
}
import {afterEach, expect, type jest, test} from '@jest/globals';
import {setDateNow} from './__utils__/setDateNow';

let spiedDateNow: jest.Spied<typeof Date.now> | undefined = undefined;

afterEach(() => {
  spiedDateNow?.mockReset();
});

test('renders correctly with a given date', () => {
  spiedDateNow = setDateNow(1_482_363_367_071);
  // ...

  expect(spiedDateNow).toHaveBeenCalledTimes(1);
});

Tipos de classe ou função podem ser passados como argumento para jest.Spied<Source>. Para restringir o tipo de entrada, use: jest.SpiedClass<Source> ou jest.SpiedFunction<Source>.

Use jest.SpiedGetter<Source> ou jest.SpiedSetter<Source> para criar o tipo de um getter ou setter espiado, respectivamente.