使用Jest/React Testing Library渲染Next.js页面时无法模拟具名导出函数

问题分析 #

你遇到的核心问题是：jest.mock的全局特性会让所有测试用例共享同一个模拟实现，导致真实实现的测试失败；直接用jest.fn()修改返回值无法关联到导入的函数；jest.spyOn因目标函数不是对象的方法而报错。

解决方案 #

通过jest.mock结合jest.requireActual，可以在单个测试用例中动态切换真实实现和自定义模拟，同时支持调用验证。

步骤1：初始化模块Mock并保留修改入口 #

在测试文件顶部先对目标模块进行Mock，并用jest.fn()包裹导出的函数，方便后续修改实现：

import { render, screen } from '@testing-library/react'
import Home from '@/pages/index'

// 初始化Mock，将hello设为可修改的jest.fn
jest.mock('../utils/greeter', () => ({
  __esModule: true,
  hello: jest.fn(),
}))

// 导入Mock后的模块，用于后续修改实现
import * as greeter from '../utils/greeter'

步骤2：测试真实实现 #

在第一个测试用例中，通过jest.requireActual获取真实函数，替换Mock的实现：

describe('Home', () => {
  it('renders unmocked greeting', () => {
    // 获取utils/greeter的真实实现
    const actualGreeter = jest.requireActual('../utils/greeter')
    // 将Mock的hello替换为真实函数
    greeter.hello.mockImplementation(actualGreeter.hello)

    render(<Home />)

    const heading = screen.getByRole('heading', {
      name: 'hello world',
    })

    expect(heading).toBeInTheDocument()
  })

步骤3：测试自定义Mock并验证调用 #

在第二个测试用例中，直接修改Mock的实现为自定义逻辑，还可以验证函数调用情况：

it('renders mocked greeting', () => {
    // 设置自定义Mock返回值
    greeter.hello.mockImplementation(() => 'hello mock')

    render(<Home />)

    const heading = screen.getByRole('heading', {
      name: 'hello mock',
    })

    expect(heading).toBeInTheDocument()
    // 验证hello函数被调用了一次
    expect(greeter.hello).toHaveBeenCalledTimes(1)
  })
})

关键原理说明 #

1. jest.mock的提升特性：jest.mock会被Jest自动提升到文件最顶部执行，确保模块导入前就完成Mock。
2. jest.requireActual的作用：绕过Mock，获取模块的真实实现，用于在需要时恢复原有逻辑。
3. mockImplementation的动态修改：通过导入Mock后的模块，可以在每个测试用例中独立修改函数实现，避免测试间的污染。

为什么之前的方法失效？ #

• 直接全局jest.mock会覆盖所有测试的模块实现，无法区分真实/模拟场景。
• 单独使用jest.fn()没有关联到被Mock的模块，页面导入的还是原始函数或全局Mock的函数，因此修改无效。
• jest.spyOn需要目标函数属于某个对象（如obj.method），而直接导出的具名函数不符合这个条件，因此会报类型错误。

内容的提问来源于stack exchange，提问作者naffers