Test frontend code by behaviour, not implementation
Testing Library's guiding principle: the more your tests resemble the way your software
is used, the more confidence they give you. A good component test renders with realistic
props and providers, finds things by role and label, clicks and types, and asserts what
the user sees or what the app sent. It survives refactors because it never reaches for
internals. Full journeys belong to the e2e-browser-test skill; this covers everything
below it, where most UI confidence is cheapest to buy.
Procedure
- Use the repo's runner and library. Vitest/Jest with Testing Library (React, Vue,
Svelte, Angular flavours) or the framework's own harness, the repo's render helper that
wires providers (router, query client, store, theme, i18n), and its network mock layer
(MSW or a fetch mock). Call
search_lorefor conventions. Never add a second runner. - Map each acceptance criterion to a user-visible outcome — "shows an error under the email field when it is invalid", "disables Submit while saving". Each gets a test named after that outcome; that test must fail if the criterion's behaviour breaks.
- Render realistically. The shared render helper, realistic props from a factory
(the
test-fixtures-and-factoriesskill), the network mocked at the fetch/HTTP boundary — not the component's own data hook, which would skip the code under test. - Query like a user, in Testing Library's priority order:
getByRolewithname,getByLabelText,getByPlaceholderText,getByText,getByDisplayValue; thengetByAltText/getByTitle;getByTestIdlast, with a comment. UsegetBy*when the element must exist,queryBy*only to assert absence,findBy*for anything async. - Interact with
userEvent(const user = userEvent.setup();await user.click,await user.type,await user.keyboard('{Tab}')) rather thanfireEvent, so focus, keyboard and pointer sequences are real. - Cover every state the ticket introduces: default, loading, empty, error, success, disabled, and each interaction path including keyboard-only and submit. For data components, make the mocked request fail (500, network error) and assert the error UI and the retry path, not only the happy render.
- Cover the async races the UI can hit when an AC touches them: a double-click on Submit sends one request; a slow response for an old search does not overwrite a newer one (resolve mocked responses out of order); unmounting mid-request produces no update or warning; optimistic updates roll back when the request fails.
- Assert visible outcomes. Text, roles,
aria-invalid,disabled, focus position, navigation to the right path, the request sent with the right payload. Never internal state, CSS class names, or render counts (unless the ticket is about renders). - Add accessibility checks for new UI: the repo's
axehelper on each new state, keyboard reachability of every control, focus moved into and restored after dialogs (thefrontend-a11yskill). Axe finds a subset of issues; it does not replace the role-based queries above. - Keep snapshots small. A reviewed snapshot of a stable presentational fragment is fine; a page-sized snapshot nobody reads is noise. Visual regression belongs to the repo's visual tooling.
- Test hooks through a component or
renderHook, asserting returned behaviour; async withfindBy*/waitFor, fake timers only when explicitly enabled and advanced. Run the suite, then record evidence with therecord-evidenceskill (test_output).
Done when
- Every AC in scope has a named test asserting its user-visible outcome.
- Every introduced state (including error and empty) and interaction path is covered.
- New UI has axe and keyboard checks; the suite passes with no
act()warnings, no unhandled promise rejections and no fixed sleeps.
Rules
- The repo's runner, Testing Library, render helper and network mock; nothing parallel.
- Queries by role and label; test ids are justified exceptions.
- Assert what the user sees or what the app sent; never internals.
- Work on the delivery branch the runner prepared (verify with
git branch --show-current), never a protected branch.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While rendering realistically you learn the render helper, the provider wiring and the network-mock conventions every UI test must use. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
