Why does Testing Library's user-event require a userEvent.setup() call and return a promise from every interaction, instead of exposing plain synchronous helpers like fireEvent does?

## The API shape is a consequence, not a style choice Candidates often describe `userEvent.setup()` as boilerplate. It is not — both halves of the API shape fall directly out of what an interaction is. **Asynchrony.** A single dispatched event is atomic; there is nothing to wait for. An interaction is a sequence of events, and user-event may insert a delay between them (typing with a per-character delay is the obvious case). Once a delay exists at all, the API must be promise-returning. There is a second benefit: yielding between the events of a sequence lets the framework process the updates each event caused, so the DOM the next event lands on is the DOM a real user would have been looking at. A synchronous version would have to fire the whole burst into an unchanging tree. **Instance state.** Real input devices have state. A keyboard has keys currently held down; a mouse has buttons currently pressed and a position. That state spans interactions: pressing and holding Shift, then clicking, is a shift-click. Modelling that requires an object that persists across calls, and that object is what `setup()` returns. ```javascript const user = userEvent.setup() await user.keyboard('{Shift>}') // press and hold Shift await user.click(lastItem) // this click carries shiftKey: true await user.keyboard('{/Shift}') // release ``` The `{Key>}` / `{/Key}` syntax means "press and hold" and "release", and it only means anything because the instance remembers between calls. ## What else setup() does - **Applies options for the test.** `delay` controls the pause between events in a sequence; `document` points the instance at a different document; `pointerEventsCheck` controls how aggressively the library refuses to interact with unreachable elements; `skipHover` and friends trim parts of a sequence you do not want. - **Stubs the clipboard.** jsdom has no working `navigator.clipboard`, so copy, cut and paste interactions would be untestable. Setup installs a stub for the life of the test so `user.copy()` and `user.paste()` behave, and restores the original afterwards. ## What happens if you skip it The direct API still exists — `userEvent.click(el)` works — but it creates a fresh instance internally for that one call. Two consequences follow: options you might want cannot be supplied, and no state survives between calls, so the held-Shift example above silently degrades into an ordinary click. Nothing errors; the test just quietly stops testing what you meant. That is why the recommended pattern is one `setup()` per test. ## Where to put the call Call it at the start of the test, **before** rendering: ```javascript const user = userEvent.setup() render(<Editor />) await user.click(screen.getByRole('button', { name: 'Bold' })) ``` Order matters because setup performs document-level work such as installing the clipboard stub, and because a shared instance created once outside all tests would leak device state — a key left held by one test would still be held in the next. One instance per test keeps tests independent, which is the same isolation discipline that applies to any other per-test fixture. A common convenience is to fold setup into a small helper that renders the component and returns both the instance and the render result, so every test in the file gets the same configuration without repeating it: ```javascript function renderWithUser(ui) { return { user: userEvent.setup(), ...render(ui) } } ``` ## The interview framing If you are asked this, the strong answer connects the shape to the semantics in one sentence — *an interaction is a stateful sequence, so the API is instance-based and asynchronous* — and then gives one concrete thing the state buys you, such as shift-clicking or clipboard support. The weak answer is "it is just how v14 works", which tells the interviewer you copied the pattern from a template without asking what it protects.