Jest Mocks: Spies for Your Functions

Why it exists

Unit tests must be fast, reliable, and focused on a single unit of code. If testing a component also requires a live API and a running database, the test becomes slow, brittle, and hard to debug. Mocking was created to sever these external dependencies, allowing you to test one piece of code in perfect isolation.

The mental model

Think of a mock function as a stunt double for your real function. The stunt double doesn't know the actor's real lines and won't perform the original function's logic. Instead, it stands in, ready to be observed. You can check that it was called, how it was called, and you can give it specific instructions for a scene, like what value to return for a particular test.

How it works

You create a mock with jest.fn(). This special function comes with a .mock property that acts as a logbook. This property tracks all interactions: mock.calls is an array of arguments for each call, mock.results is an array of return values, and mock.instances tracks new instantiations. In your tests, you inspect these arrays to assert that the function was used as expected. You can also control its behavior by chaining methods like .mockReturnValue('test-value') or .mockReturnValueOnce(10) to dictate what it returns when called.

When to use it

Use mocks to isolate the code you are testing from its dependencies. This is ideal for replacing functions with external side effects, like API calls or database queries. It's also essential for verifying interactions, such as confirming a callback function passed to a component is actually invoked with the correct arguments when a user clicks a button.

When not to use it

Avoid mocking everything. For integration tests, the goal is to see how real modules work together. Do not mock trivial, pure functions or implementation details internal to the code you're testing; test the public interface, not the internal machinery. Over-mocking leads to brittle tests that are tightly coupled to the implementation and break on minor refactors.

One canonical example

Imagine testing a processData function that uses a fetchData utility. To avoid a real network call, you mock fetchData. First, create the mock: const mockFetchData = jest.fn(). In your test, you can specify what it should return for one specific call: mockFetchData.mockReturnValueOnce({ user: 'test' }). Then, you call your function under test. Finally, you can assert that the mock was called once (expect(mockFetchData.mock.calls.length).toBe(1)) and that your function correctly handled the mock's return value. This isolates your test from the network.