React Testing Library中fireEvent.click无法勾选复选框的问题排查

场景复现 #

执行screen.debug()后控制台输出的元素：
第一个复选框

<input
  type="checkbox"
  aria-label="checkbox"
  name="checkbox-array"
  value="first"
  checked=""
  id="first"
/>

第二个复选框

<input
  type="checkbox"
  aria-label="checkbox"
  name="checkbox-array"
  value="second"
  id="second"
/>

编写的单元测试代码：

it('should select second option when clicked', () => {
  const secondElement = screen.getAllByLabelText('checkbox')[1]; // 选中正确元素
  expect(secondElement).toBeInTheDocument(); // 测试通过
  expect(secondElement).not.toHaveAttribute('checked', ''); // 测试通过
  // screen.debug(); // 仅用于调试
  fireEvent.click(secondElement); // 点击元素，此时应被勾选
  // screen.debug(); // 仅用于调试
  expect(secondElement).toHaveAttribute('checked', ''); // 测试失败，仍未勾选
});

原因分析 #

1. fireEvent的局限性：fireEvent仅模拟原生DOM事件触发，而React组件的事件处理依赖自身的合成事件系统，直接调用fireEvent.click可能无法触发React绑定的事件处理器，导致组件state未更新，DOM状态自然不会变化。
2. 断言方式错误：复选框的checked是布尔属性，只要属性存在就表示勾选状态，且React受控组件的状态由state驱动，直接断言DOM属性的方式并不准确，应该使用专门的匹配器判断勾选状态。

修复方案 #

1. 替换fireEvent为userEvent #

@testing-library/react提供的userEvent会模拟真实用户的交互流程，能正确触发React的合成事件，进而更新组件状态。需要先导入userEvent：

import userEvent from '@testing-library/user-event';

2. 使用正确的断言匹配器 #

用toBeChecked()匹配器判断复选框是否被勾选，这是Testing Library专为表单元素提供的断言方法，比断言DOM属性更可靠。

修改后的测试代码：

it('should select second option when clicked', async () => {
  const user = userEvent.setup();
  const secondElement = screen.getAllByLabelText('checkbox')[1];
  
  expect(secondElement).toBeInTheDocument();
  expect(secondElement).not.toBeChecked();
  
  await user.click(secondElement); // userEvent的方法为异步，需用await
  
  expect(secondElement).toBeChecked();
});

补充说明 #

如果复选框是非受控组件（用defaultChecked初始化），理论上fireEvent.click能修改DOM状态，但仍推荐使用userEvent，因为它更贴近真实用户行为，测试结果更可信。同时断言依然要用toBeChecked()，避免DOM属性判断带来的误差。

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