React Native Testing Library
Deep API reference for
@testing-library/react-nativev13 and v14.Scope: unit + component tests with Jest + RNTL. For end-to-end UI flows on real devices/simulators, use Maestro — declarative YAML flows, no code, runs against the built app. RNTL and Maestro are complementary, not alternatives.
IMPORTANT: API signatures, sync/async behavior, and available functions differ between v13 and v14. Always check the project's package.json and load the matching version reference rather than relying on memorized patterns.
Version Detection
Check @testing-library/react-native in package.json:
- v14.x → load reference-v14-api (React 19+, async APIs,
test-renderer) - v13.x → load reference-v13-api (React 18+, sync APIs,
react-test-renderer)
Core References
| Topic | Description | Reference |
|---|---|---|
| Core patterns | Query priority, render/screen, userEvent vs fireEvent, waitFor, 11 core rules | core-patterns |
| v13 API (React 18) | Sync render, full method tables, fireEvent sync, React 19 compat shims | reference-v13-api |
| v14 API (React 19) | Async render, await-based APIs, removed APIs, v13→v14 migration codemods | reference-v14-api |
| Anti-patterns | Wrong queries, waitFor misuse, unnecessary act, destructuring, missing await | best-practices-anti-patterns |
Key Recommendations
- Always use
screenfor queries — never destructure fromrender() getByRolefirst with{ name: '...' }option (most accessibility-aware)findBy*for async elements — notwaitFor+getBy*userEventoverfireEvent— more realistic interaction simulationqueryBy*only for non-existence assertions (.not.toBeOnTheScreen())- v14: always
awaitevery API (includingrender,fireEvent,act)