本地正常的表单提交按钮在Vitest与React Testing Library中无法触发

问题重现 #

• 本地运行时，<form>内的type="submit"按钮能正常触发onSubmit事件，控制台可输出预期日志
• 切换到Vitest + React Testing Library编写测试时，不管用fireEvent.click还是userEvent.click点击按钮，都无法触发onSubmit
• 将按钮移出form、改为普通button绑定onClick能让测试通过，但这违背了表单的最佳实践

可能原因 #

happy-dom对表单submit事件的模拟存在兼容性问题，默认情况下可能未正确处理按钮点击触发表单提交的逻辑；另外如果组件内的onSubmit未阻止默认行为，测试环境下表单的默认刷新行为可能导致事件捕获失败。

可行解决方案 #

1. 直接触发表单的submit事件（推荐）

跳过按钮点击的模拟步骤，直接获取表单元素并调用userEvent.submit触发提交：

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import YourForm from './YourForm';

test('表单提交事件正常触发', async () => {
  const mockHandleSubmit = vi.fn();
  const user = userEvent.setup();

  render(<YourForm onSubmit={mockHandleSubmit} />);
  const formElement = screen.getByRole('form');
  
  await user.submit(formElement);
  
  expect(mockHandleSubmit).toHaveBeenCalledTimes(1);
});

2. 配置happy-dom启用表单控件模拟

在vitest.config.ts中添加happy-dom的表单支持配置，确保它能正确模拟表单相关行为：

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'happy-dom',
    environmentOptions: {
      happyDom: {
        settings: {
          enableFormControls: true,
        },
      },
    },
  },
});

3. 确保组件内onSubmit阻止默认行为

检查表单组件代码，确保onSubmit回调里调用了e.preventDefault()，避免表单默认刷新导致测试中事件丢失：

const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
  e.preventDefault(); // 必须添加这一行
  console.log('表单提交触发');
  // 你的业务逻辑
};

return (
  <form onSubmit={handleSubmit}>
    {/* 表单内容 */}
    <button type="submit">提交</button>
  </form>
);

为什么不推荐临时方案 #

把按钮移出form或改用onClick会丢失表单的原生特性：比如用户按回车键提交表单、无障碍设备对表单提交的支持，这些都是符合Web标准的最佳实践，应该尽量保留。

内容的提问来源于stack exchange，提问作者two-touch