Mocking fetch() in Jest: fetch-mock-jest vs jest-fetch-mock

When testing frontend code that uses fetch, you need a reliable way to intercept HTTP calls without making real network requests. Both fetch-mock-jest and jest-fetch-mock solve this problem, but they take different approaches under the hood. Let’s compare how they work in practice.

🔌 Core Architecture: Wrapper vs Native Jest Spy

fetch-mock-jest is a thin integration layer on top of fetch-mock, a powerful standalone mocking library. It doesn’t reimplement mocking logic — it configures fetch-mock to play nicely with Jest’s test lifecycle.

// fetch-mock-jest example
import { enableFetchMocks } from 'fetch-mock-jest';

enableFetchMocks();

beforeEach(() => {
  fetchMock.resetMocks();
});

it('calls the API', async () => {
  fetchMock.getOnce('https://api.example.com/user', { id: 123 });
  const user = await getUser();
  expect(user.id).toBe(123);
});

jest-fetch-mock replaces global.fetch with a Jest mock function (jest.fn()). This means all the familiar Jest assertion methods work out of the box.

// jest-fetch-mock example
import 'jest-fetch-mock';

fetchMock.enableMocks();

it('calls the API', async () => {
  fetchMock.mockResponseOnce(JSON.stringify({ id: 123 }));
  const user = await getUser();
  expect(user.id).toBe(123);
  expect(fetch).toHaveBeenCalledWith('https://api.example.com/user');
});

🧪 Setup and Cleanup

Both packages require minimal setup, but their cleanup strategies differ slightly.

With fetch-mock-jest, you typically call fetchMock.resetMocks() in beforeEach to clear routes and call history between tests. The package itself handles restoring the original fetch during Jest’s teardown.

// fetch-mock-jest cleanup
import { enableFetchMocks } from 'fetch-mock-jest';

enableFetchMocks();

beforeEach(() => {
  fetchMock.resetMocks(); // clears routes and history
});

With jest-fetch-mock, calling fetchMock.enableMocks() replaces global.fetch once. Between tests, you usually call fetchMock.resetMocks() which internally calls fetch.mockReset(), clearing both implementation and call history.

// jest-fetch-mock cleanup
import 'jest-fetch-mock';

fetchMock.enableMocks();

beforeEach(() => {
  fetchMock.resetMocks(); // equivalent to fetch.mockReset()
});

🎯 Matching Requests: Pattern-Based vs Full URL

fetch-mock-jest inherits fetch-mock’s rich matching system. You can match by exact URL, glob patterns, regular expressions, or even custom functions.

// fetch-mock-jest: advanced matching
fetchMock.get('/api/users/*', { name: 'Alice' }); // glob
fetchMock.post(/\/api\/posts/, { id: 1 });       // regex
fetchMock.get(
  (url, opts) => opts.headers?.Authorization,
  { secret: 'data' }
); // custom matcher

jest-fetch-mock matches only by full URL string unless you use Jest’s built-in mock implementations. For pattern matching, you’d need to implement your own logic inside mockImplementation.

// jest-fetch-mock: basic matching
fetchMock.mockResponseOnce(JSON.stringify({ id: 1 }));
// Only matches the next call, regardless of URL

// To match specific URLs, you must check inside mockImplementation
fetchMock.mockImplementation((url) => {
  if (url === 'https://api.example.com/user') {
    return Promise.resolve({ json: () => ({ id: 123 }) });
  }
  return Promise.reject(new Error('Unexpected URL'));
});

📤 Response Configuration

Both let you return JSON, text, or status codes, but with different syntax.

fetch-mock-jest uses object-based response configuration:

fetchMock.get('https://api.example.com/error', {
  status: 404,
  body: { error: 'Not found' }
});

jest-fetch-mock provides helper methods like mockResponseOnce and mockRejectOnce:

fetchMock.mockResponseOnce(
  JSON.stringify({ error: 'Not found' }),
  { status: 404 }
);

For non-JSON responses, jest-fetch-mock requires manual construction of the Response object or use of mockResponseOnce with raw strings.

🔍 Assertion Capabilities

Because jest-fetch-mock uses a real Jest spy, you get full access to Jest’s assertion API:

expect(fetch).toHaveBeenCalledTimes(2);
expect(fetch).toHaveBeenCalledWith(
  'https://api.example.com/user',
  expect.objectContaining({ method: 'GET' })
);

With fetch-mock-jest, you assert through fetchMock’s own API:

expect(fetchMock.called()).toBe(true);
expect(fetchMock.calls()).toHaveLength(2);
expect(fetchMock.lastCall()[0]).toBe('https://api.example.com/user');

If your team is already fluent in Jest matchers, jest-fetch-mock’s approach may feel more natural. If you prefer a dedicated mocking interface, fetch-mock-jest offers more semantic clarity for complex scenarios.

⚠️ Error Handling and Edge Cases

Both support simulating network errors:

// fetch-mock-jest
fetchMock.get('https://api.example.com/fail', 500);

// jest-fetch-mock
fetchMock.mockRejectOnce(new Error('Network error'));

However, fetch-mock-jest can simulate partial failures (e.g., 50% of requests fail) using its route repetition controls, while jest-fetch-mock requires manual sequencing with mockImplementationOnce.

🔄 Real-World Recommendation

• Use fetch-mock-jest when:

  • You need to mock many endpoints with different behaviors
  • Your app uses dynamic URLs (query params, path variables)
  • You want declarative, readable mock definitions that mirror real API contracts

• Use jest-fetch-mock when:

  • Most tests only mock one or two simple endpoints
  • Your team prefers using standard Jest assertions everywhere
  • You’re already deep in the Jest ecosystem and want minimal conceptual overhead

💡 Final Thought

Neither package is deprecated, and both are actively maintained. The choice boils down to whether you value expressive request matching (fetch-mock-jest) or native Jest integration (jest-fetch-mock). For most greenfield projects with complex API interactions, fetch-mock-jest’s routing power pays off. For simpler apps or teams new to mocking, jest-fetch-mock’s simplicity wins.