user-event

user-event is the companion library to @testing-library/dom (and by extension React Testing Library, Vue Testing Library, and the rest of the Testing Library family) for firing events the way a real user would trigger them, rather than the single low-level DOM event that fireEvent dispatches. Clicking a checkbox with user-event doesn’t just fire a click event — it walks through pointer-down, focus, pointer-up, and click, updating the element’s state along the way, the same as clicking it in a browser would.

The library is built around two layers: a stateful setup() session that tracks keyboard modifier and pointer button state across calls (so pressing {Shift>} in one keyboard() call stays held for the next), and a set of convenience methods (click, type, tab, hover, selectOptions, upload, clipboard.paste, and more) built on top of that shared state. Internally it models keyboard and pointer interaction as explicit System state machines fed by a small event-dispatch layer, so every convenience method ultimately resolves to the same primitive event sequence a browser would produce.

What You Get

• A stateful userEvent.setup() session API that shares keyboard/pointer state across multiple interaction calls in a single test
• High-level convenience methods — click, dblClick, tripleClick, hover, unhover, tab — for common interactions
• A keyboard() API with a small DSL ({Shift>}, {Enter}, [KeyA]) for precise key-by-key and modifier-aware typing
• A low-level pointer() API for scripting multi-step pointer/touch/pen interaction sequences (press, move, release)
• Clipboard integration (copy, cut, paste) backed by a stubbed clipboard so paste-driven UI logic can be tested
• Form-focused utilities: type, clear, upload, selectOptions, deselectOptions for exercising inputs, file pickers, and <select> elements

Common Use Cases

• Typing into a form field character-by-character to trigger the same onChange/onKeyDown handlers a real keystroke would
• Testing keyboard-only navigation flows (tab() through focusable elements) for accessibility coverage
• Simulating drag-style or multi-step pointer interactions (press-move-release) for custom UI widgets
• Verifying clipboard-driven features by scripting copy/paste against a stubbed clipboard
• Uploading files to an <input type="file"> in tests without touching the real filesystem dialog

Under The Hood

Architecture A setup() call produces a shared Instance object holding config, a System state machine, and the userEventApi method map; every convenience method is wrapped through a level-tracking async wrapper before it dispatches events via a dedicated event layer, so calls made against one session compose consistently. Keyboard and pointer state live as separate System sub-machines that convenience methods, the keyboard DSL, and the pointer API all read and mutate, which is what lets sequential calls on one instance behave like a continuous user session rather than isolated one-off actions.

Tech Stack Written entirely in TypeScript and built with an esbuild-based pipeline (via the shared kcd-scripts toolchain), targeting CJS output. Tests run under Jest with a jsdom environment, configured through the same shared tooling. The package’s only runtime dependency is a peer dependency on @testing-library/dom — everything else in its dependency list is build or test tooling.

Code Quality The test suite mirrors the source tree section-for-section (clipboard, convenience, document, event, keyboard, pointer, setup, system, utility), backed by shared test helpers for rendering fixtures and capturing dispatched events. Path aliases keep test imports pointed at source and helpers directly. Linting runs through a shared flat ESLint config augmented with project-specific custom rules, and CI runs a typecheck pass ahead of the test suite, indicating a strict, enforced quality bar.

API Design The central ergonomic choice is offering both a one-off direct call (userEvent.click(el)) and a stateful session (userEvent.setup() then user.click(el)) from the same method surface, so simple tests stay terse while multi-step interactions can share keyboard/pointer state. A compact keyboard description syntax (holding modifiers, naming specific physical keys) lets a single string argument express what would otherwise require several imperative press/release calls.