Jest测试中setTimeout替代await waitFor生效问题咨询

我用Jest编写测试用例时遇到一个问题：未更新@testing-library/react前，await waitFor能正常工作；但更新后这条语句出现错误（无法得到预期结果），移除await waitFor改用setTimeout后，测试用例成功通过，想咨询该现象的原因。

原测试代码 #

it("toast displays client key exists message", async () => {
  const uniqueContraintError = { description: "Key for client name already exists" };
  mockApiPostClientKey(400, uniqueContraintError);

  render(<AddClient onSave={(_): void => {}} clientCreateEndpoint="/api/clients/"
      clientKeyCreateEndpoint="/api/clients/keys/" />);

  fillInClientNameInput(clientName);
  clickAddButton();

  await waitFor(() => expect(toast.error).toHaveBeenCalledWith(uniqueContraintError));
});

修改后可正常运行的代码 #

it("toast displays client key exists message", async () => {
  const uniqueContraintError = { description: "Key for client name already exists" };
  mockApiPostClientKey(400, uniqueContraintError);

  render(<AddClient onSave={(_): void => {}} clientCreateEndpoint="/api/clients/"
      clientKeyCreateEndpoint="/api/clients/keys/" />);

  fillInClientNameInput(clientName);
  clickAddButton();

  setTimeout(() => expect(toast.error).toHaveBeenCalledWith(uniqueContraintError));
});

可能的原因 #

• waitFor的重试/超时逻辑变更：新版@testing-library/react调整了waitFor的默认超时时间或重试间隔，如果你的toast触发时机刚好落在重试周期之外，或者超时时间不足以等待toast调用，waitFor就会提前终止并断言失败。而setTimeout是强制延迟执行，刚好能等到toast触发的时机。
• 异步逻辑的追踪差异：waitFor会在React的更新周期内检查断言条件，但如果toast的调用是通过非React调度的异步逻辑触发的（比如直接调用第三方toast库方法，未走React状态更新或useEffect），waitFor可能无法捕捉到这个变化；而setTimeout属于宏任务，跳出了React的更新队列，能等到断言条件满足。
• mock函数的断言时机问题：新版waitFor在重试过程中，只要某次断言失败就会抛出错误终止测试；而setTimeout中的断言是延迟执行的，刚好在toast调用完成后触发，不会中途终止。
• 依赖兼容性问题：更新@testing-library/react后，可能与你使用的toast库（如react-toastify）版本不兼容，导致waitFor无法正确监听toast的mock调用。

推荐的解决办法 #

• 调整waitFor参数：给waitFor设置更长的超时时间或调整重试间隔，比如：

  await waitFor(() => expect(toast.error).toHaveBeenCalledWith(uniqueContraintError), { timeout: 3000 });
  

• 改用findBy系列查询（若适用）：如果toast会渲染为DOM元素，优先使用await findByRole('alert')这类查询方法，它本身就是waitFor与getBy的结合，更适配React的更新逻辑。
• 检查mock函数的正确性：确认toast.error的mock设置正确，可在waitFor中添加日志，查看toast.error的调用次数变化，验证是否在预期时机被调用。
• 避免用setTimeout替代：setTimeout的测试结果不稳定，环境变慢时容易失败，尽量使用@testing-library提供的异步测试方法，保证测试的可靠性。

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