Testing Library is a family of lightweight testing utilities built on top of DOM Testing Library, designed to test web components as users interact with them rather than testing implementation details. It emphasizes accessibility-first queries (like getByRole) and realistic user interactions (via user-event), making tests more resilient to refactors and closer to actual user behavior. The key insight: if your test resembles how users interact with your app, it gives you more confidence your application works correctly.
What This Cheat Sheet Covers
This topic spans 18 focused tables and 104 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: Query Type VariantsTable 2: Priority Query Methods (Accessibility-First)Table 3: Secondary Query Methods (Fallbacks)Table 4: Query Options and TextMatch PatternsTable 5: User Interaction APIs (user-event vs fireEvent)Table 6: Async Utilities and WaitingTable 7: Screen and Within HelpersTable 8: Debugging ToolsTable 9: Custom Render and Setup PatternsTable 10: Testing Custom HooksTable 11: Configuration OptionsTable 12: jest-dom Matchers (Companion Library)Table 13: Framework AdaptersTable 14: user-event Setup and OptionsTable 15: Best PracticesTable 16: Common Anti-Patterns to AvoidTable 17: Integration with Mock Service Worker (MSW)Table 18: Advanced Patterns and Edge Cases
Table 1: Query Type Variants
| Variant | Example | Description |
|---|---|---|
getByRole('button') | Returns element immediately • throws error if not found or multiple matches • use when element must be present | |
queryByRole('button') | Returns element or null • does not throw • use for asserting element absence | |
await findByRole('button') | Returns Promise (default 1000ms timeout) • retries until element appears • use for async elements |