react-testing-library测试Formik时如何mock内部onSubmit回调

使用react-testing-library测试嵌套在组件内部的Formik表单时，不需要强行mock内部定义的提交函数，以下是按推荐度排序的可行方案：

方案1：等待提交产生的可观测副作用（首选） #

React Testing Library的核心原则是测试用户可感知的行为，而非组件内部实现。不需要关心内部handleSubmit有没有被调用，只需要等待提交动作完成后产生的可观测结果即可：

• 如果提交后会展示成功提示、跳转页面、更新列表，直接等待这些UI变化出现
• 如果提交会调用后端接口，直接mock接口方法，等待接口被传入正确参数调用

示例代码：

test('内嵌表单提交逻辑正常', async () => {
  // mock提交对应的后端接口
  const mockSubmitApi = jest.fn().mockResolvedValue({ code: 200 })
  jest.mock('@/services/form', () => ({ submitFormData: mockSubmitApi }))

  render(<SomeComponentWithFormInside />)
  const user = userEvent.setup()

  // 正常填写表单字段
  await user.type(screen.getByLabelText(/名字/i), 'John')
  await user.type(screen.getByLabelText(/姓氏/i), 'Dee')
  await user.type(screen.getByLabelText(/邮箱/i), 'john.dee@someemail.com')
  // 点击提交按钮
  await user.click(screen.getByRole('button', {name: /提交/i}))

  // 等待提交结果出现
  await waitFor(() => {
    // 断言接口被正确参数调用
    expect(mockSubmitApi).toHaveBeenCalledWith({
      email: 'john.dee@someemail.com',
      firstName: 'John',
      lastName: 'Dee',
    })
    // 断言提交成功的UI反馈出现
    expect(screen.getByText(/提交成功/i)).toBeInTheDocument()
  })
})

这个方案完全不触碰组件内部实现，即使后续重构把Formik换成其他表单库、修改内部函数名，测试用例依然有效。

方案2：增加可选测试回调（适合需要精确断言提交参数的场景） #

如果组件提交后没有明显的UI变化，或者需要单独校验表单值的转换逻辑，可以给组件增加一个仅测试环境使用的可选prop，不影响生产环境逻辑：

// 组件代码
const SomeComponentWithFormInside = ({ onFormSubmitForTest } = {}) => {
  const handleSubmit = async (values) => {
    // 原有业务提交逻辑
    await submitFormData(values)
    // 仅测试环境传入回调时触发，生产环境不会执行
    onFormSubmitForTest?.(values)
  }

  return <MyForm onSubmit={handleSubmit} />
}

测试时直接传入mock函数即可，写法和官方示例完全一致：

test('表单提交参数构造正确', async () => {
  const mockTestSubmit = jest.fn()
  render(<SomeComponentWithFormInside onFormSubmitForTest={mockTestSubmit} />)
  const user = userEvent.setup()

  // 填写表单、点击提交步骤同上
  await user.type(screen.getByLabelText(/名字/i), 'John')
  await user.type(screen.getByLabelText(/姓氏/i), 'Dee')
  await user.type(screen.getByLabelText(/邮箱/i), 'john.dee@someemail.com')
  await user.click(screen.getByRole('button', {name: /提交/i}))

  await waitFor(() =>
    expect(mockTestSubmit).toHaveBeenCalledWith({
      email: 'john.dee@someemail.com',
      firstName: 'John',
      lastName: 'Dee',
    }),
  )
})

生产环境不会传入这个prop，相关判断逻辑会在构建时被tree-shaking移除，不会增加产物体积，也不会破坏组件的封装性。

方案3：兜底方案：mock useFormik方法 #

如果前两种方案都无法落地，可以通过mock formik模块的useFormik方法注入mock提交函数，但这个方案会耦合Formik的内部实现，版本升级时容易失效，且无法覆盖组件内部自定义的提交逻辑，仅作为兜底使用：

import { useFormik } from 'formik'
// mock formik模块
jest.mock('formik', () => ({
  ...jest.requireActual('formik'),
  useFormik: jest.fn()
}))

test('兜底校验表单值正确性', async () => {
  const mockHandleSubmit = jest.fn()
  // 拦截useFormik调用，替换onSubmit为我们的mock函数
  useFormik.mockImplementation((options) => {
    const actualFormik = jest.requireActual('formik').useFormik({
      ...options,
      onSubmit: mockHandleSubmit
    })
    return actualFormik
  })

  render(<SomeComponentWithFormInside />)
  // 后续填写、提交、断言逻辑和官方示例一致
})

避坑提醒 #

• 不要直接mock内部handleSubmit或者整个MyForm组件，会跳过表单渲染、校验的核心逻辑，测试没有实际意义
• 不要给waitFor设置超过1000ms的超时时间，jsdom环境下Formik异步提交逻辑1秒内必然触发，超时说明测试逻辑存在问题
• 不要仅用findBy*查询代替提交后的等待，findBy只能保证元素存在，无法保证异步提交逻辑执行完成

内容的提问来源于stack exchange，提问作者Toni Bardina Comas