Mock-функции
Mock-функции также известны как "шпионы", потому что они позволяют вам шпионить за поведением функции, которая вызывается косвенно каким-либо другим кодом, а не только тестировать вывод. Mock-функцию можно создать при помощи jest.fn(). Если реализация не задана, то при вызове mock-функция вернет значение undefined.
Методы
- Справка
mockFn.getMockName()mockFn.mock.callsmockFn.mock.resultsmockFn.mock.instancesmockFn.mock.lastCallmockFn.mockClear()mockFn.mockReset()mockFn.mockRestore()mockFn.mockImplementation(fn)mockFn.mockImplementationOnce(fn)mockFn.mockName(name)mockFn.mockReturnThis()mockFn.mockReturnValue(value)mockFn.mockReturnValueOnce(value)mockFn.mockResolvedValue(value)mockFn.mockResolvedValueOnce(value)mockFn.mockRejectedValue(value)mockFn.mockRejectedValueOnce(value)
- TypeScript
Справка
mockFn.getMockName()
Возвращает набор имён mock-фукнции путем вызова .mockName().
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'- указывает, что вызов завершился корректно.'throw'- указывает, что вызов завершился путем выброса исключения.'incomplete'- указывает, что вызов еще не завершен. Это происходит, если вы протестируете результат внутри самой mock-функции или из функции, вызванной 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
An array that contains all the object instances that have been instantiated from this mock function using new.
For example: A mock function that has been instantiated twice would have the following mock.instances array:
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.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 and mockFn.mock.results arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
The clearMocks configuration option is available to clear mocks automatically before each tests.
Beware that mockClear will replace mockFn.mock, not just these three properties! You should, therefore, avoid assigning mockFn.mock to other variables, temporary or not, to make sure you don't access stale data.
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.
Доступна опция resetMocks для автоматического сброса mock-функций перед каждым тестом.
Resetting a mock created with jest.spyOn() will result in a function with no return value.
mockFn.mockRestore()
Does everything that mockFn.mockReset() does, and also restores the original (non-mocked) implementation.
This is useful when you want to mock functions in certain test cases and restore the original implementation in others.
The restoreMocks configuration option is available to restore mocks automatically before each test.
mockFn.mockRestore only works when the mock was created with jest.spyOn. Thus you have to take care of restoration yourself when manually assigning jest.fn().
mockFn.mockImplementation(fn)
Accepts a function that should be used as the implementation of the mock. The mock itself will still record all calls that go into and instances that come from itself – the only difference is that the implementation will also be executed when the mock is called.
jest.fn(implementation) is a shorthand for jest.fn().mockImplementation(implementation).
Например:
const mockFn = jest.fn().mockImplementation(scalar => 42 + scalar);
// or: jest.fn(scalar => 42 + scalar);
const a = mockFn(0);
const b = mockFn(1);
a === 42; // true
b === 43; // true
mockFn.mock.calls[0][0] === 0; // true
mockFn.mock.calls[1][0] === 1; // true
mockImplementation can also be used to mock class constructors:
module.exports = class SomeClass {
m(a, b) {}
};
jest.mock('./SomeClass'); // this happens automatically with automocking
const SomeClass = require('./SomeClass');
const mMock = jest.fn();
SomeClass.mockImplementation(() => {
return {
m: mMock,
};
});
const some = new SomeClass();
some.m('a', 'b');
console.log('Calls to m: ', mMock.mock.calls);
mockFn.mockImplementationOnce(fn)
Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results.
const myMockFn = jest
.fn()
.mockImplementationOnce(cb => cb(null, true))
.mockImplementationOnce(cb => cb(null, false));
myMockFn((err, val) => console.log(val)); // true
myMockFn((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 myMockFn = jest
.fn(() => 'default')
.mockImplementationOnce(() => 'first call')
.mockImplementationOnce(() => 'second call');
// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());
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.
Например:
const mockFn = jest.fn().mockName('mockedFunction');
// mockFn();
expect(mockFn).toHaveBeenCalled();
Will result in this error:
expect(mockedFunction).toHaveBeenCalled()
Ожидаемое количество вызовов: >1
Фактическое количество вызовов: 0
mockFn.mockReturnThis()
Сокращенно:
jest.fn(function () {
return this;
});
mockFn.mockReturnValue(value)
Сокращенно:
jest.fn().mockImplementation(() => value);
Accepts a value that will be returned whenever the mock function is called.
const mock = jest.fn();
mock.mockReturnValue(42);
mock(); // 42
mock.mockReturnValue(43);
mock(); // 43
mockFn.mockReturnValueOnce(value)
Сокращенно:
jest.fn().mockImplementationOnce(() => value);
Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more mockReturnValueOnce values to use, calls will return a value specified by mockReturnValue.
const myMockFn = jest
.fn()
.mockReturnValue('default')
.mockReturnValueOnce('first call')
.mockReturnValueOnce('second call');
// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());
mockFn.mockResolvedValue(value)
Сокращенно:
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)
Сокращенно:
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)
Сокращенно:
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'));
await asyncMock(); // throws "Async error"
});
mockFn.mockRejectedValueOnce(value)
Сокращенно:
jest.fn().mockImplementationOnce(() => Promise.reject(value));
Example usage:
test('async test', async () => {
const asyncMock = jest
.fn()
.mockResolvedValueOnce('first call')
.mockRejectedValueOnce(new Error('Async error'));
await asyncMock(); // first call
await asyncMock(); // throws "Async error"
});
TypeScript
Jest itself is written in TypeScript.
If you are using Create React App then the TypeScript template has everything you need to start writing tests in TypeScript.
Otherwise, please see our Getting Started guide for to get setup with TypeScript.
You can see an example of using Jest with TypeScript in our GitHub repository.
jest.MockedFunction
jest.MockedFunction is available in the @types/jest module from version 24.9.0.
The following examples will assume you have an understanding of how Jest mock functions work with JavaScript.
You can use jest.MockedFunction to represent a function that has been replaced by a Jest mock.
Example using automatic jest.mock:
// Assume `add` is imported and used within `calculate`.
import add from './add';
import calculate from './calc';
jest.mock('./add');
// Our mock of `add` is now fully typed
const mockAdd = add as jest.MockedFunction<typeof add>;
test('calculate calls add', () => {
calculate('Add', 1, 2);
expect(mockAdd).toHaveBeenCalledTimes(1);
expect(mockAdd).toHaveBeenCalledWith(1, 2);
});
Example using jest.fn:
// Here `add` is imported for its type
import 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() as jest.MockedFunction<typeof add>;
// Note: You can use the `jest.fn` type directly like this if you want:
// const mockAdd = jest.fn<ReturnType<typeof add>, Parameters<typeof add>>();
// `jest.MockedFunction` is a more friendly shortcut.
// Now we can easily set up mock implementations.
// All the `.mock*` API can now give you proper types for `add`.
// https://jestjs.io/docs/en/mock-function-api
// `.mockImplementation` can now 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.MockedClass
jest.MockedClass is available in the @types/jest module from version 24.9.0.
The following examples will assume you have an understanding of how Jest mock classes work with JavaScript.
You can use jest.MockedClass to represent a class that has been replaced by a Jest mock.
Converting the ES6 Class automatic mock example would look like this:
import SoundPlayer from '../sound-player';
import SoundPlayerConsumer from '../sound-player-consumer';
jest.mock('../sound-player'); // SoundPlayer is now a mock constructor
const SoundPlayerMock = SoundPlayer as jest.MockedClass<typeof SoundPlayer>;
beforeEach(() => {
// Clear all instances and calls to constructor and all methods:
SoundPlayerMock.mockClear();
});
it('We can check if the consumer called the class constructor', () => {
const soundPlayerConsumer = new SoundPlayerConsumer();
expect(SoundPlayerMock).toHaveBeenCalledTimes(1);
});
it('We can check if the consumer called a method on the class instance', () => {
// Show that mockClear() is working:
expect(SoundPlayerMock).not.toHaveBeenCalled();
const soundPlayerConsumer = new SoundPlayerConsumer();
// Constructor should have been called again:
expect(SoundPlayerMock).toHaveBeenCalledTimes(1);
const coolSoundFileName = 'song.mp3';
soundPlayerConsumer.playSomethingCool();
// mock.instances is available with automatic mocks:
const mockSoundPlayerInstance = SoundPlayerMock.mock.instances[0];
// However, it will not allow access to `.mock` in TypeScript as it
// is returning `SoundPlayer`. Instead, you can check the calls to a
// method like this fully typed:
expect(SoundPlayerMock.prototype.playSoundFile.mock.calls[0][0]).toBe(
coolSoundFileName,
);
// Equivalent to above check:
expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledWith(
coolSoundFileName,
);
expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledTimes(1);
});