testing-library/user-event

Concept: Simulating real user interactions

user-event is a library designed to simulate real browser events that occur when a user interacts with a web page.

Unlike lower-level utilities like fireEvent (from dom-testing-library), which simply dispatch a single event, user-event provides a higher-level abstraction that simulates the full sequence of events a real user would trigger. For example, calling userEvent.click(checkbox) does more than just dispatch a click event; it handles the state changes and side effects that a real browser would perform when a checkbox is clicked.

Key Principle:

The more your tests resemble the way your software is used, the more confidence they can give you.

When using userEvent.upload, the applyAccept option determines if files that do not match the accept attribute of the input element should be automatically discarded.

• Default: true
• Usage: Set to false if you want to allow files that do not match the accept criteria to be uploaded during tests.

The writeToClipboard option controls whether cut or copy actions write data to the Clipboard API. Since the Clipboard API is often unavailable in test environments, user-event can stub navigator.clipboard.

• Default (when calling APIs directly): false
• Default (when using setup()): true

The pointer method is an asynchronous function available on a user-event instance used to simulate complex pointer interactions (like mouse or touch movements and presses). It accepts a single PointerInput or an array of PointerInput items, which are processed sequentially.

PointerInput can be:

• A string representing a key definition (e.g., a mouse button).
• An object containing keys and optional position data (target, coords, node, offset).
• A PointerAction object (either a PointerPressAction or a PointerMoveAction).

When providing position data:

• If node is set, offset is treated as the DOM offset.
• If node is not set, offset is treated as the textContent/value offset on the target.

Use setupDirect when you want to call user-event APIs directly without maintaining a persistent session state, or when you need manual control over the system (input device state). Unlike setupMain, setupDirect uses defaultOptionsDirect, which sets writeToClipboard: false and autoModify: true.

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

const { api, system } = userEvent.setupDirect({
  delay: 10,
});

// Use the returned api
await api.click(element);