Jest Mock: Complete Guide to Mocking Modules and Functions

When writing unit tests you often need to isolate the dependencies of the code under test: replacing API calls, faking timers, mocking third-party libraries. Jest provides a complete mocking toolchain—from simple function mocks to module-level replacement—that covers the vast majority of testing scenarios. This article systematically explains the various mocking techniques in Jest and their best practices.

Mock Function Basics

Creating a Mock Function with jest.fn()

// 创建一个 mock 函数
const mockFn = jest.fn();

// 调用
mockFn();
mockFn('hello', 'world');
mockFn(42);

// 断言
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledTimes(3);
expect(mockFn).toHaveBeenCalledWith('hello', 'world');
expect(mockFn).toHaveBeenLastCalledWith(42);

Setting Return Values

const mockFn = jest.fn();

// 固定返回值
mockFn.mockReturnValue(42);
expect(mockFn()).toBe(42);

// 每次调用返回不同值
mockFn
  .mockReturnValueOnce('first')
  .mockReturnValueOnce('second')
  .mockReturnValue('default');

expect(mockFn()).toBe('first');
expect(mockFn()).toBe('second');
expect(mockFn()).toBe('default');
expect(mockFn()).toBe('default');

// 异步返回值
const asyncMock = jest.fn();
asyncMock.mockResolvedValue({ data: 'success' });
// 或 mockResolvedValueOnce

const result = await asyncMock();
expect(result).toEqual({ data: 'success' });

// 异步拒绝
asyncMock.mockRejectedValue(new Error('网络错误'));
await expect(asyncMock()).rejects.toThrow('网络错误');

Setting the Implementation

const mockFn = jest.fn();

// 自定义实现
mockFn.mockImplementation((a, b) => a + b);
expect(mockFn(1, 2)).toBe(3);

// 每次调用不同的实现
mockFn
  .mockImplementationOnce(() => 'first')
  .mockImplementationOnce(() => 'second');

expect(mockFn()).toBe('first');
expect(mockFn()).toBe('second');

// 异步实现
const asyncMock = jest.fn();
asyncMock.mockImplementation(async () => {
  const result = await someAsyncOperation();
  return result;
});

Mocking an Entire Module

Mocking a Third-Party Library

// __mocks__/axios.js（放在与 node_modules 同级的 __mocks__ 目录）
export default {
  get: jest.fn(() => Promise.resolve({ data: {} })),
  post: jest.fn(() => Promise.resolve({ data: {} })),
  put: jest.fn(() => Promise.resolve({ data: {} })),
  delete: jest.fn(() => Promise.resolve({ data: {} })),
  create: jest.fn(function () {
    return this;
  }),
};

In the test file:

import axios from 'axios';
import { fetchUsers } from './userService';

// 自动使用 __mocks__/axios.js
jest.mock('axios');

describe('userService', () => {
  beforeEach(() => {
    jest.clearAllMocks(); // 每次测试前清除 mock 状态
  });

  it('应该正确获取用户列表', async () => {
    const mockUsers = [
      { id: 1, name: '张三' },
      { id: 2, name: '李四' },
    ];

    axios.get.mockResolvedValue({ data: mockUsers });

    const users = await fetchUsers();

    expect(axios.get).toHaveBeenCalledWith('/api/users');
    expect(users).toEqual(mockUsers);
  });

  it('应该处理请求失败', async () => {
    axios.get.mockRejectedValue(new Error('网络错误'));

    await expect(fetchUsers()).rejects.toThrow('网络错误');
  });
});

Mocking Internal Project Modules

// src/services/userService.js
import api from './api';

export function getUser(id) {
  return api.get(`/users/${id}`);
}

export function createUser(data) {
  return api.post('/users', data);
}

// src/services/__tests__/userService.test.js
import { getUser, createUser } from '../userService';

// Mock 整个 api 模块
jest.mock('../api', () => ({
  get: jest.fn(),
  post: jest.fn(),
}));

import api from '../api';

describe('userService', () => {
  afterEach(() => {
    jest.clearAllMocks();
  });

  describe('getUser', () => {
    it('应该调用正确的 URL', async () => {
      const mockUser = { id: 1, name: '张三' };
      api.get.mockResolvedValue({ data: mockUser });

      const result = await getUser(1);

      expect(api.get).toHaveBeenCalledWith('/users/1');
      expect(result.data).toEqual(mockUser);
    });
  });

  describe('createUser', () => {
    it('应该发送正确的数据', async () => {
      const newUser = { name: '王五', email: 'wangwu@example.com' };
      api.post.mockResolvedValue({ data: { id: 3, ...newUser } });

      const result = await createUser(newUser);

      expect(api.post).toHaveBeenCalledWith('/users', newUser);
      expect(result.data.id).toBe(3);
    });
  });
});

Mocking Dates and Timers

Mocking Date

// 固定时间
const mockDate = new Date('2019-09-18T10:00:00Z');
jest.spyOn(global, 'Date').mockImplementation(() => mockDate);

// 或使用 jest.setSystemTime（Jest 26+）
// jest.useFakeTimers('modern');
// jest.setSystemTime(new Date('2019-09-18'));

// 测试中
it('应该显示正确的创建时间', () => {
  jest.spyOn(global, 'Date').mockImplementation(() => new Date('2019-09-18'));

  const component = render(<PostCard post={mockPost} />);
  expect(component.getByText('2019-09-18')).toBeInTheDocument();
});

afterEach(() => {
  jest.restoreAllMocks();
});

Mocking Timers

beforeEach(() => {
  jest.useFakeTimers();
});

afterEach(() => {
  jest.useRealTimers();
});

it('应该在 3 秒后显示提示', () => {
  render(<AutoHideToast message="成功" duration={3000} />);

  expect(screen.getByText('成功')).toBeInTheDocument();

  // 快进 3 秒
  jest.advanceTimersByTime(3000);

  expect(screen.queryByText('成功')).not.toBeInTheDocument();
});

it('setInterval 应该每秒触发', () => {
  const callback = jest.fn();

  setInterval(callback, 1000);

  jest.advanceTimersByTime(5000);

  expect(callback).toHaveBeenCalledTimes(5);
});

Mocking localStorage

// 创建 localStorage mock
const localStorageMock = (() => {
  let store = {};
  return {
    getItem: jest.fn((key) => store[key] || null),
    setItem: jest.fn((key, value) => {
      store[key] = String(value);
    }),
    removeItem: jest.fn((key) => {
      delete store[key];
    }),
    clear: jest.fn(() => {
      store = {};
    }),
  };
})();

Object.defineProperty(window, 'localStorage', {
  value: localStorageMock,
});

// 测试
it('应该保存 token 到 localStorage', () => {
  saveToken('abc123');
  expect(localStorage.setItem).toHaveBeenCalledWith('token', 'abc123');
});

it('应该从 localStorage 读取 token', () => {
  localStorage.getItem.mockReturnValue('abc123');
  expect(getToken()).toBe('abc123');
});

Mocking Utility Functions in a Project

// src/utils/logger.js
export function logError(error) {
  console.error('[ERROR]', error);
  // 上报到监控平台
}

export function logInfo(message) {
  console.log('[INFO]', message);
}

// 测试文件中
import { processData } from '../dataProcessor';

// 部分 mock：只 mock logger，保留其他模块的真实实现
jest.mock('../utils/logger', () => ({
  logError: jest.fn(),
  logInfo: jest.fn(),
}));

import { logError, logInfo } from '../utils/logger';

describe('dataProcessor', () => {
  it('处理失败时应该记录错误', () => {
    processData(null);
    expect(logError).toHaveBeenCalledWith(
      expect.stringContaining('数据为空')
    );
  });

  it('处理成功时应该记录信息', () => {
    processData({ id: 1 });
    expect(logInfo).toHaveBeenCalledWith(
      expect.stringContaining('处理完成')
    );
  });
});

Mocking a Class

// src/services/ApiService.js
export class ApiService {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async fetch(url) {
    const response = await fetch(this.baseURL + url);
    return response.json();
  }
}

// 测试中 mock 整个类
jest.mock('../services/ApiService', () => {
  return {
    ApiService: jest.fn().mockImplementation(() => ({
      fetch: jest.fn(),
    })),
  };
});

import { ApiService } from '../services/ApiService';

it('应该使用 ApiService 获取数据', async () => {
  const mockInstance = new ApiService();
  mockInstance.fetch.mockResolvedValue({ id: 1, name: 'test' });

  // 被测代码会创建 ApiService 实例并调用 fetch
  const result = await someFunctionThatUsesApi();

  expect(ApiService).toHaveBeenCalledWith('https://api.example.com');
  expect(mockInstance.fetch).toHaveBeenCalledWith('/data');
});

jest.spyOn: Track Real Function Calls

import { formatDate } from '../utils/date';

it('应该格式化日期', () => {
  const spy = jest.spyOn(console, 'log');

  someFunction('2019-09-18');

  expect(spy).toHaveBeenCalledWith('格式化后的日期:', '2019年09月18日');

  spy.mockRestore(); // 恢复原始实现
});

// spyOn 也可以替换实现
const mathSpy = jest.spyOn(Math, 'random').mockReturnValue(0.5);
expect(Math.random()).toBe(0.5);
mathSpy.mockRestore();

Mock Cleanup Strategy

// jest.config.js
module.exports = {
  // 每个测试文件运行前自动清除 mock
  clearMocks: true,
  // 自动恢复 mock（对 spyOn 有效）
  restoreMocks: true,
};

// 或手动清理
beforeEach(() => {
  jest.clearAllMocks();  // 清除调用记录、返回值等
  jest.restoreAllMocks(); // 恢复 spyOn 的原始实现
  jest.resetModules();    // 重置模块缓存
});

Summary

jest.fn() creates a mock function, supporting return values (mockReturnValue), implementations (mockImplementation), and async behavior (mockResolvedValue/mockRejectedValue).
jest.mock() can mock an entire module, including manual mocks defined via the __mocks__ directory.
jest.spyOn() tracks calls to real functions, and can also replace their implementation.
Control time with jest.useFakeTimers() + jest.advanceTimersByTime().
Browser APIs like localStorage and fetch need to be mocked globally in a setup file.
Always clean up mock state after tests to prevent cross-test interference.
Partial mocks let you replace only certain exports of a module while keeping the real implementations of the others.

Jest Mock: Complete Guide to Mocking Modules and Functions

Mock Function Basics ​

Creating a Mock Function with jest.fn() ​

Setting Return Values ​

Setting the Implementation ​

Mocking an Entire Module ​

Mocking a Third-Party Library ​

Mocking Internal Project Modules ​

Mocking Dates and Timers ​

Mocking Date ​

Mocking Timers ​

Mocking localStorage ​

Mocking Utility Functions in a Project ​

Mocking a Class ​

jest.spyOn: Track Real Function Calls ​

Mock Cleanup Strategy ​

Summary ​