testing-library
Use when testing React components with @testing-library/react — DOM queries, user interactions, async rendering, and accessibility assertions. Also use for React 19 Suspense testing patterns, Vitest integration, and Storybook portable story reuse.
| Model | Source |
|---|---|
| sonnet | pack: frontend |
Full Reference
┏━ 🔧 testing-library ━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Use when testing React components with @testin… ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
@testing-library/react v16
Section titled “@testing-library/react v16”Test components like users use them — not like developers built them.
Quick Reference
Section titled “Quick Reference”| Package | Version | Role |
|---|---|---|
@testing-library/react | v16.x | Core render + screen queries |
@testing-library/dom | peer dep | Must install explicitly (v16 breaking change) |
@testing-library/user-event | v14.x | Realistic user interaction simulation |
@types/react-dom | latest | TypeScript type checking |
Install: npm install --save-dev @testing-library/react @testing-library/dom @testing-library/user-event @types/react-dom
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Query Priority
Section titled “Query Priority”Use queries in this order. Higher = more accessible, more resilient, more like a real user.
getByRole— #1 always. Matches ARIA roles. Tests accessibility implicitly.getByLabelText— form fields. Mirrors how screen readers navigate.getByPlaceholderText— when no label exists (not ideal UX, but testable).getByText— non-interactive elements: headings, paragraphs, spans.getByDisplayValue— filled form elements (input/select/textarea with current value).getByAltText— images and area elements.getByTitle— title attribute. Inconsistent screen reader support — use sparingly.getByTestId— last resort only. Use when no semantic query works.
Test like a user navigates — not like a developer inspects the DOM.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reference Index
Section titled “Reference Index”| File | What it covers |
|---|---|
| setup.md | Install command, Vitest config, Jest config, Next.js + Vite + Storybook notes |
| queries.md | Query variants (getBy/queryBy/findBy), priority guide, all query types with examples |
| events.md | user-event v14 — click, keyboard, type, pointer, clipboard, select, tab |
| async.md | waitFor, findBy*, act(), React 19 Suspense patterns, concurrent features |
| patterns.md | Custom render with providers, forms, modals, navigation, context, MSW, Storybook portable stories |
| accessibility.md | jest-axe/vitest-axe, keyboard nav, ARIA live regions, logRoles, jest-dom matchers |
Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.