Course contentsShow
← React
Lesson 2070 of 2,39646. Testing React with RTLFree lesson

The async Nature of user-event

Why user-event methods return promises and require await, while fireEvent is synchronous.

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:

  1. All intermediate events complete
  2. React processes state updates
  3. Components re-render
  4. 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.