frontend-testing

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

1. 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_lore for conventions. Never add a second runner.
2. 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.
3. Render realistically. The shared render helper, realistic props from a factory (the test-fixtures-and-factories skill), the network mocked at the fetch/HTTP boundary — not the component's own data hook, which would skip the code under test.
4. Query like a user, in Testing Library's priority order: getByRole with name, getByLabelText, getByPlaceholderText, getByText, getByDisplayValue; then getByAltText/getByTitle; getByTestId last, with a comment. Use getBy* when the element must exist, queryBy* only to assert absence, findBy* for anything async.
5. Interact with userEvent (const user = userEvent.setup(); await user.click, await user.type, await user.keyboard('{Tab}')) rather than fireEvent, so focus, keyboard and pointer sequences are real.
6. 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.
7. 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.
8. 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).
9. Add accessibility checks for new UI: the repo's axe helper on each new state, keyboard reachability of every control, focus moved into and restored after dialogs (the frontend-a11y skill). Axe finds a subset of issues; it does not replace the role-based queries above.
10. 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.
11. Test hooks through a component or renderHook, asserting returned behaviour; async with findBy*/waitFor, fake timers only when explicitly enabled and advanced. Run the suite, then record evidence with the record-evidence skill (test_output).