Skip to main content
Version: Next

Funções de Simulação

Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. Você pode criar uma função de simulação (mock, em inglês) com jest.fn(). Se nenhuma implementação é dada, a função de simulação retornará undefined quando invocada.

info

The TypeScript examples from this page will only work as document if you import jest from '@jest/globals':

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

Métodos


Reference

mockFn.getMockName()

Returns the mock name string set by calling mockFn.mockName(value).

mockFn.mock.calls

An array containing the call arguments of all calls that have been made to this mock function. Each item in the array is an array of arguments that were passed during the call.

For example: A mock function f that has been called twice, with the arguments f('arg1', 'arg2'), and then with the arguments f('arg3', 'arg4'), would have a mock.calls array that looks like this:

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

mockFn.mock.results

An array containing the results of all calls that have been made to this mock function. Each entry in this array is an object containing a type property, and a value property. type will be one of the following:

  • 'return' - Indicates that the call completed by returning normally.
  • 'throw' - Indicates that the call completed by throwing a value.
  • 'incomplete' - Indicates that the call has not yet completed. This occurs if you test the result from within the mock function itself, or from within a function that was called by the mock.

The value property contains the value that was thrown or returned. value is undefined when type === 'incomplete'.

For example: A mock function f that has been called three times, returning 'result1', throwing an error, and then returning 'result2', would have a mock.results array that looks like this:

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

mockFn.mock.instances

Por exemplo: uma função de simulação que foi instanciada duas vezes teria o seguinte array de mock.instances:

Redefine todas as informações armazenadas nos arrays de mockFn.mock.calls e mockFn.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

An array that contains the contexts for all calls of the mock function.

A context is the this value that a function receives when called. The context can be set using Function.prototype.bind, Function.prototype.call or 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

An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return undefined.

For example: A mock function f that has been called twice, with the arguments f('arg1', 'arg2'), and then with the arguments f('arg3', 'arg4'), would have a mock.lastCall array that looks like this:

['arg3', 'arg4'];

mockFn.mockClear()

Clears all information stored in the mockFn.mock.calls, mockFn.mock.instances, mockFn.mock.contexts and mockFn.mock.results arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

Beware that mockFn.mockClear() will replace mockFn.mock, not just reset the values of its properties! Evite portanto atribuir mockFn.mock a outras variáveis, temporárias ou não, para ter certeza que não acessará dados antigos.

The clearMocks configuration option is available to clear mocks automatically before each tests.

mockFn.mockReset()

Does everything that mockFn.mockClear() does, and also removes any mocked return values or implementations.

This is useful when you want to completely reset a mock back to its initial state. (Note that resetting a spy will result in a function with no return value).

The mockReset configuration option is available to reset mocks automatically before each test.

mockFn.mockRestore()

Does everything that mockFn.mockReset() does, and also restores the original (non-mocked) implementation.

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

Beware that mockFn.mockRestore() only works when the mock was created with jest.spyOn(). Assim, tem que cuidar da restauração você mesmo quando atribuir manualmente jest.fn().

The restoreMocks configuration option is available to restore mocks automatically before each test.

mockFn.mockImplementation(fn)

Aceita uma função que deve ser usada como a implementação da simulação (mock, em inglês). A simulação em si ainda irá gravar todas as chamadas que entram e instâncias que vêm dela própria – a única diferença é que a implementação também será executada quando a simulação é chamada.

tip

jest.fn(implementation) is a shorthand for 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() can also be used to mock class constructors:

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 uma implementação de simulação para uma chamada à função simulada (mocked, em inglês). Podem ser encadeadas para que várias chamadas de função 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

When the mocked function runs out of implementations defined with .mockImplementationOnce(), it will execute the default implementation set with jest.fn(() => defaultValue) or .mockImplementation(() => defaultValue) if they were called:

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

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

mockFn.mockName(name)

Accepts a string to use in test result output in place of 'jest.fn()' to indicate which mock function is being referenced.

Por exemplo:

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

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

Will result in this error:

expect(mockedFunction).toHaveBeenCalled() Expected mock function "mockedFunction" to have been called, but it was not called.

mockFn.mockReturnThis()

Syntactic sugar function for:

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

mockFn.mockReturnValue(value)

Aceita um valor que será retornado sempre que a função de simulação é chamada.

const mock = jest.fn();

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

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

mockFn.mockReturnValueOnce(value)

Aceita um valor que será retornado por uma chamada para a função de simulação. Podem ser encadeados para que sucessivas chamadas para a função de simulação retornem valores diferentes. Quando não há mais valores mockReturnValueOnce para usar, chamadas irão retornar um valor especificado pelo 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)

Syntactic sugar function for:

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

Useful to mock async functions in async tests:

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

await asyncMock(); // 43
});

mockFn.mockResolvedValueOnce(value)

Syntactic sugar function for:

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

Useful to resolve different values over multiple async calls:

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)

Syntactic sugar function for:

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

Useful to create async mock functions that will always reject:

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

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

mockFn.mockRejectedValueOnce(value)

Syntactic sugar function for:

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

Useful together with .mockResolvedValueOnce() or to reject with different exceptions over multiple async calls:

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

TypeScript Usage

tip

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

jest.fn(implementation?)

Correct mock typings will be inferred if implementation is passed to jest.fn(). There are many use cases where the implementation is omitted. To ensure type safety you may pass a generic type argument (also see the examples above for more reference):

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).toBeCalledTimes(1);
expect(mockAdd).toBeCalledWith(1, 2);
});