The async Nature of user-event
What you'll learn: Why user-event methods return promises while fireEvent is synchronous, and what this means for your tests.
The Core Difference
When you use fireEvent.click(button), it synchronously dispatches a single click event and returns immediately. But when you call userEvent.click(button), something fundamentally different happens: it simulates the entire sequence of events a real user would trigger—mousedown, focus, mouseup, click—and gives React time to process state updates and re-renders between each event.
Because this multi-step simulation involves React's asynchronous state updates and potential side effects, all user-event methods return promises. You must await them.
Why This Matters
// ❌ Wrong - missing await
userEvent.click(button); // Promise ignored!
expect(screen.getByText('Clicked')).toBeInTheDocument(); // May fail
// ✅ Correct - await the interaction
await userEvent.click(button);
expect(screen.getByText('Clicked')).toBeInTheDocument();
The await ensures that:
- All intermediate events complete
- React processes state updates
- Components re-render
- The DOM reflects the final state
Think of fireEvent as teleporting directly to the outcome, while user-event walks through every step a real user would take—and walking takes time, even if just milliseconds.
The Pattern
Every user-event interaction follows this pattern:
await userEvent.type(input, 'hello');
await userEvent.click(checkbox);
await userEvent.selectOptions(select, 'option1');
Forgetting await creates race conditions where you assert before the interaction completes.
Key Takeaway: user-event methods are asynchronous because they simulate real user behavior across multiple events and React render cycles—always use await to ensure interactions complete before making assertions.