Storybook导出的userEvent方法是同步还是异步的？

核心结论 #

@storybook/testing-library 导出的 userEvent 所有交互方法本质都是异步的，必须使用 await 等待完成，否则会因DOM渲染时机不确定导致偶发测试失败。

问题原因拆解 #

• 偶发失败的根源：userEvent.type 这类操作会触发组件状态更新、DOM重新渲染，这些过程是异步的。如果不使用 await，后续代码可能在DOM完成更新前执行，导致元素状态不符合预期，出现偶发失败。
• 文档的矛盾示例：官方文档中同时存在同步和异步调用的写法是疏漏，实际应以API的真实行为为准。
• 类型定义的偏差：当前包的类型定义直接复用了@testing-library/react的同步类型，但实际上它封装的是@testing-library/user-event的异步API（Storybook的play函数本身就是异步执行环境），所以类型提示和ESLint规则会产生误导。

临时修正类型定义的方法 #

如果需要让TypeScript和ESLint正确识别异步方法，可以手动添加类型声明覆盖：

declare module '@storybook/testing-library' {
  import { UserEvent } from '@testing-library/user-event';
  export const userEvent: UserEvent;
}

将这段代码放在项目的types目录下（比如src/types/storybook-testing-library.d.ts），即可修正类型提示，让ESLint允许使用await。

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