When users interact in the browser by e.g. pressing keyboard keys, they interact
with a UI layer the browser shows to them. The browser then interprets this
input, possibly alters the underlying DOM accordingly and dispatches
The UI layer and trusted events are not programmatically available.
user-event has to apply workarounds and mock the UI layer to
simulate user interactions like they would happen in the browser.
Starting a session per
setup(options?: Options): UserEvent
userEvent.setup() API applies these workarounds to the document and allows
you to configure an "instance" of
Methods on this instance share one input device state, e.g. which keys are pressed.
This allows to write multiple consecutive interactions that behave just like the described interactions by a real user.
import userEvent from '@testing-library/user-event'
const user = userEvent.setup()
await user.keyboard('[ShiftLeft>]') // Press Shift (without releasing it)
await user.click(element) // Perform a click with `shiftKey: true`
The instance exposes another
.setup() API that allows to configure another
instance that shares the same input device state.
You can also call the APIs directly on the default export. This will call
setup internally and then use the method on the instance.
This exists to ease the transition to version 14 and writing simple tests. Using
the methods on the instances returned by
userEvent.setup() is recommended.