The expense form is where Splitwise-lite meets real people, and real people do messy things: they tab between fields, paste " 45.50 ", click “Add” with the amount still empty, double-click. A unit test of parseAmount can’t tell you whether the form wires all of that up correctly. A test that uses the form like a person can.
Testing Library ships two ways to interact.
\nfireEvent (from @testing-library/dom) dispatches exactly one DOM event. fireEvent.click(button) sends a click. fireEvent.change(input, { target: { value: '45.50' } }) sets the value and sends a change. It’s fast and precise, and it’s not what happens when a person clicks or types.
user-event (from @testing-library/user-event) simulates the interaction. user.click(button) produces pointer and mouse events, moves focus, then fires click, and refuses to click a disabled button or one hidden under pointer-events: none, like a real browser. user.type(input, '45.50') clicks the field, then for each character sends keydown, keypress, input and keyup.
Default to user-event. Reach for fireEvent only for events user-event doesn’t model, such as a custom event or scroll.
The form has two labelled fields, an “Add expense” button and an alert area. Here is the happy path, written the way you’d describe it to a colleague:
\n// @vitest-environment jsdom\nimport { afterEach, test, expect, vi } from 'vitest';\nimport { screen } from '@testing-library/dom';\nimport userEvent from '@testing-library/user-event';\nimport { mountExpenseForm } from './expense-form.js';\n\nafterEach(() => {\n document.body.innerHTML = '';\n});\n\ntest('adds a valid expense in cents and clears the form', async () => {\n const user = userEvent.setup();\n const onAdd = vi.fn();\n mountExpenseForm(document.body, onAdd);\n\n await user.type(screen.getByRole('textbox', { name: 'Description' }), 'Dinner');\n await user.type(screen.getByRole('textbox', { name: 'Amount' }), '45.50');\n await user.click(screen.getByRole('button', { name: 'Add expense' }));\n\n expect(onAdd).toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 });\n expect(screen.getByRole('textbox', { name: 'Amount' }).value).toBe('');\n});Three things to notice. userEvent.setup() comes first and gives you a user session that tracks keyboard and pointer state across calls. Every interaction is awaited: user-event methods are asynchronous, and without await the assertions run before the typing has finished. And the assertions are about outcomes: what onAdd received (the contract with the rest of the app) and what the user now sees.
Keyboard users matter too. await user.tab() moves focus like the Tab key, and await user.keyboard('{Enter}') presses Enter, so you can test that the form works without a mouse.
user-event simulates the browser’s default behaviour for the interaction, but it can’t see your CSS layout. It won’t notice that a modal covers the button visually, or that the “Add expense” button is scrolled off-screen on a phone. jsdom has no layout engine, so sizes and positions are all zero. Those are jobs for end-to-end tests in a real browser, which is where section 4 goes. In unit and component tests, user-event gives you the right event sequence and focus behaviour, which covers the large majority of form bugs.
\nMost form bugs live in the error handling, so give it at least as many tests. Typing abc as the amount and clicking “Add expense” should:
role="alert", which screen readers announce;onAdd;test('explains an invalid amount and keeps the input', async () => {\n const user = userEvent.setup();\n const onAdd = vi.fn();\n mountExpenseForm(document.body, onAdd);\n\n await user.type(screen.getByRole('textbox', { name: 'Description' }), 'Taxi');\n await user.type(screen.getByRole('textbox', { name: 'Amount' }), 'abc');\n await user.click(screen.getByRole('button', { name: 'Add expense' }));\n\n expect(screen.getByRole('alert').textContent).toMatch('Not a valid amount');\n expect(onAdd).not.toHaveBeenCalled();\n expect(screen.getByRole('textbox', { name: 'Amount' }).value).toBe('abc');\n});Each assertion guards a different bug. Drop the alert check and a silent failure passes. Drop the not.toHaveBeenCalled and a form that saves garbage passes. Drop the last one and a form that wipes the user’s input passes.
There is no user-event package in the sandbox, so the exercise starter includes two small helpers: typeInto(element, text), which focuses the field and sends key and input events for each character, and clickOn(element), which sends the pointer and mouse sequence, focuses and clicks (and does nothing on a disabled button). They are synchronous, so you don’t await them. The sandbox also blocks real form submission, so the widget listens for the button’s click instead of a submit event; in your app, a real <form> with a submit handler is better, because it gives you Enter-to-submit for free.
Next, the hardest part of UI testing: things that happen later.
\n","toc":[{"id":"sec-1","text":"fireEvent versus user-event","level":2},{"id":"sec-2","text":"Testing the expense form","level":2},{"id":"sec-3","text":"What user-event won’t do for you","level":3},{"id":"sec-4","text":"The unhappy path is most of the work","level":2},{"id":"sec-5","text":"In the playground","level":2}],"takeaways":["fireEvent dispatches one DOM event; user-event plays the whole sequence a real person causes (pointer, focus, keydown, input, keyup, click).","Create a session with userEvent.setup() and await every interaction, because user-event methods are asynchronous.","Test a form through its outcomes: the callback’s arguments, the error a user would read, and the state of the fields afterwards.","Test the invalid path as carefully as the valid one; “nothing happened” is a behaviour to assert."],"further":[{"title":"Testing Library — user-event introduction","url":"https://testing-library.com/docs/user-event/intro"},{"title":"Testing Library — Firing events","url":"https://testing-library.com/docs/dom-testing-library/api-events"},{"title":"Testing Library — user-event setup","url":"https://testing-library.com/docs/user-event/setup"}],"quiz":[{"q":"The amount field formats input on each keydown. A test uses fireEvent.change(input, { target: { value: '45.50' } }), and the formatting code never runs. Why?
fireEvent.change sets the value and dispatches a single change event, with no key events.","why":"Correct. Nothing pressed a key, so keydown handlers never fire. await user.type(input, '45.50') produces key events for every character."},{"text":"fireEvent only works with React components.","why":"fireEvent comes from @testing-library/dom and works with any DOM; the issue is which events it sends."},{"text":"Change events don’t bubble in jsdom.","why":"Bubbling isn’t the issue; the keydown handler isn’t waiting for a change event at all."}],"answer":0},{"q":"What’s wrong with this test?
\ntest('adds the expense', () => {\n const user = userEvent.setup();\n mountExpenseForm(document.body, onAdd);\n user.type(screen.getByRole('textbox', { name: 'Amount' }), '12');\n user.click(screen.getByRole('button', { name: 'Add expense' }));\n expect(onAdd).toHaveBeenCalled();\n});userEvent.setup() must be called inside beforeEach.","why":"Calling setup() at the start of each test is the recommended pattern; there’s no need for a hook."},{"text":"getByRole can’t find inputs; it should use getByTestId.","why":"Inputs have the role textbox, and with a label they have an accessible name, so getByRole is the right query."},{"text":"The interactions aren’t awaited, so the assertion runs before typing and clicking have finished.","why":"Correct. user-event methods return promises; make the test async and await each call."}],"answer":2},{"q":"Typing 'abc' in the amount field and clicking “Add expense” should show an error. Which set of assertions tests that path best?
onAdd with garbage would pass."},{"text":"The alert shows the message, onAdd was not called, and the typed text is still in the field.","why":"Correct. Each assertion guards a different bug: a silent failure, a bad expense saved, and wiping the user’s input."},{"text":"onAdd was not called.","why":"A version that silently ignores the click passes this too; the user would be left guessing."}],"answer":1}],"exercise":{"kind":"web","mode":"test","subject":"function parseAmount(input) {\n const text = String(input).trim();\n if (!/^\\d+(\\.\\d{1,2})?$/.test(text)) throw new Error(`Not a valid amount: \"${input}\"`);\n const [whole, fraction = ''] = text.split('.');\n const cents = Number(whole) * 100 + Number(fraction.padEnd(2, '0'));\n if (cents === 0) throw new Error('Amount must be greater than zero');\n return cents;\n}\n\n// Mounts the \"Add expense\" form into container.\n// - Text fields labelled \"Description\" and \"Amount\", and an\n// \"Add expense\" button.\n// - On click, if valid: calls onAdd({ description, amountCents }) with the\n// trimmed description and the amount in integer cents, hides any error,\n// then clears both fields.\n// - If invalid: shows the reason in the element with role=\"alert\",\n// does NOT call onAdd, and keeps what the user typed.\n// Blank description -> \"Add a description\"; bad amount -> parseAmount's message.\n// (The playground blocks real form submission, so this reacts to the click.)\nfunction mountExpenseForm(container, onAdd) {\n container.innerHTML = `\n mountExpenseForm(container, onAdd) renders fields labelled Description and Amount and an Add expense button. A valid click calls onAdd({ description, amountCents }) and clears the fields; an invalid one shows the reason in role="alert", skips onAdd and keeps the typed text.
The starter includes the query stand-ins from the last exercise plus typeInto(el, text) and clickOn(el), which mimic user-event (they’re synchronous: no await). Add tests until your suite catches four hidden bugs: one calls onAdd even when the amount is invalid, one doesn’t clear the fields, one passes the amount in dollars instead of cents, and one never shows the alert.
expect(onAdd).toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 }).","After a successful add, read the fields again and check that .value is '' for both.","Invalid path: type ‘abc’ as the amount, click, then check getByRole(container, 'alert').textContent, expect(onAdd).not.toHaveBeenCalled() and that the amount field still holds ‘abc’. The query stand-ins skip hidden elements, just like the real getByRole."],"explanation":"Two tests, six assertions, four bugs. toHaveBeenCalledWith({ description: 'Dinner', amountCents: 4550 }) pins the contract with the rest of the app, so the dollars-for-cents bug fails it (it sends 45.5). Checking the fields after the add catches the form that forgets to clear. On the invalid path, getByRole(container, 'alert') fails when the alert stays hidden, because hidden elements aren’t in the accessibility tree, and not.toHaveBeenCalled() catches the form that saves garbage anyway. Every assertion is about something the user sees or the app receives; none mentions a variable inside the widget.