React Native Testing
CallstackOfficialPublished by Callstack
- Skill
- Guidelines
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a comprehensive reference for testing React Native components using React Native Testing Library (RNTL). It covers the critical differences between RNTL v13 (React 18) and v14 (React 19+), including sync versus async rendering patterns. The guide emphasizes best practices such as using the screen object for queries, prioritizing accessibility-based queries like getByRole, and preferring userEvent over fireEvent for realistic interaction simulation. It also includes guidance on Jest matchers, handling async elements with findBy, and avoiding common anti-patterns.
What it does
- Provides version-specific guidance for RNTL v13 and v14.
- Defines query priorities and usage for finding elements.
- Explains the correct usage of userEvent versus fireEvent.
- Lists standard Jest matchers for component assertions.
- Outlines common testing anti-patterns to avoid.
- Demonstrates how to handle async elements and providers.
When to use it
- When writing new unit or integration tests for React Native components.
- When reviewing existing test suites for adherence to RNTL best practices.
- When debugging failing tests or flaky async interactions.
- When migrating or upgrading RNTL versions between v13 and v14.
Advantages
- Ensures tests are written using semantic, accessibility-focused queries.
- Reduces flakiness by promoting correct async handling with findBy.
- Prevents common pitfalls like unnecessary act() calls or improper waitFor usage.
- Provides clear version-specific API guidance.
Usage examples
- “How do I test a button click that triggers an async state update?”
- The agent will recommend using userEvent.press() followed by an await screen.findBy* query to assert the resulting UI change, avoiding manual waitFor blocks.
- “Should I use getByTestId to find my input field?”
- The agent will advise using getByRole with an accessible name instead, noting that testID should be a last resort.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/callstackincubator/react-native-testing/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip react-native-testing.zip -d .agents/skills
Documentation by Callstack
RNTL Test Writing Guide
IMPORTANT: Your training data about @testing-library/react-native may be outdated or incorrect — API signatures, sync/async behavior, and available functions differ between v13 and v14. Always rely on this skill's reference files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.
Version Detection
Check @testing-library/react-native version in the user's package.json:
v14.x → load references/api-reference-v14.md (React 19+, async APIs,
test-renderer)v13.x → load references/api-reference-v13.md (React 18+, sync APIs,
react-test-renderer)
Use the version-specific reference for render patterns, fireEvent sync/async behavior, screen API, configuration, and dependencies.
Query Priority
Use in this order: getByRole > getByLabelText > getByPlaceholderText > getByText > getByDisplayValue > getByTestId (last resort).
Query Variants
| Variant | Use case | Returns | Async |
|---|---|---|---|
getBy* | Element must exist | element instance (throws) | No |
getAllBy* | Multiple must exist | element instance[] (throws) | No |
queryBy* | Check non-existence ONLY | element instance | null | No |
queryAllBy* | Count elements | element instance[] | No |
findBy* | Wait for element | Promise<element instance> | Yes |
findAllBy* | Wait for multiple | Promise<element instance[]> | Yes |
Interactions
Prefer userEvent over fireEvent. userEvent is always async.
const user = userEvent.setup();
await user.press(element); // full press sequence
await user.longPress(element, { duration: 800 }); // long press
await user.type(textInput, 'Hello'); // char-by-char typing
await user.clear(textInput); // clear TextInput
await user.paste(textInput, 'pasted text'); // paste into TextInput
await user.scrollTo(scrollView, { y: 100 }); // scrollfireEvent — use only when userEvent doesn't support the event. See version-specific reference for sync/async behavior:
fireEvent.press(element);
fireEvent.changeText(textInput, 'new text');
fireEvent(element, 'blur');Assertions (Jest Matchers)
Available automatically with any @testing-library/react-native import.
| Matcher | Use for |
|---|---|
toBeOnTheScreen() | Element exists in tree |
toBeVisible() | Element visible (not hidden/display:none) |
toBeEnabled() / toBeDisabled() | Disabled state via aria-disabled |
toBeChecked() / toBePartiallyChecked() | Checked state |
toBeSelected() | Selected state |
toBeExpanded() / toBeCollapsed() | Expanded state |
toBeBusy() | Busy state |
toHaveTextContent(text) | Text content match |
toHaveDisplayValue(value) | TextInput display value |
toHaveAccessibleName(name) | Accessible name |
toHaveAccessibilityValue(val) | Accessibility value |
toHaveStyle(style) | Style match |
toHaveProp(name, value?) | Prop check (last resort) |
toContainElement(el) | Contains child element |
toBeEmptyElement() | No children |
Rules
Use
screenfor queries, not destructuring fromrender()Use
getByRolefirst with{ name: '...' }optionUse
queryBy*ONLY for.not.toBeOnTheScreen()checksUse
findBy*for async elements, NOTwaitFor+getBy*Never put side-effects in
waitFor(nofireEvent/userEventinside)One assertion per
waitForNever pass empty callbacks to
waitForDon't wrap in
act()-render,fireEvent,userEventhandle itDon't call
cleanup()- automatic after each testPrefer ARIA props (
role,aria-label,aria-disabled) over legacyaccessibility*propsUse RNTL matchers over raw prop assertions
*ByRole Quick Reference
Common roles: button, text, heading (alias: header), searchbox, switch, checkbox, radio, img, link, alert, menu, menuitem, tab, tablist, progressbar, slider, spinbutton, timer, toolbar.
getByRole options: { name, disabled, selected, checked, busy, expanded, value: { min, max, now, text } }.
For *ByRole to match, the element must be an accessibility element:
Text,TextInput,Switchare by defaultViewneedsaccessible={true}(or usePressable/TouchableOpacity)
waitFor
// Correct: action first, then wait for result
fireEvent.press(button);
await waitFor(() => {
expect(screen.getByText('Result')).toBeOnTheScreen();
});
// Better: use findBy* instead
fireEvent.press(button);
expect(await screen.findByText('Result')).toBeOnTheScreen();Options: waitFor(cb, { timeout: 1000, interval: 50 }). Works with Jest fake timers automatically.
Fake Timers
Recommended with userEvent (press/longPress involve real durations):
jest.useFakeTimers();
test('with fake timers', async () => {
const user = userEvent.setup();
render(<Component />);
await user.press(screen.getByRole('button'));
// ...
});Custom Render
Wrap providers using wrapper option:
function renderWithProviders(ui: React.ReactElement) {
return render(ui, {
wrapper: ({ children }) => (
<ThemeProvider>
<AuthProvider>{children}</AuthProvider>
</ThemeProvider>
),
});
}References
v13 API Reference — Complete v13 API: sync render, queries, matchers, userEvent, React 19 compat
v14 API Reference — Complete v14 API: async render, queries, matchers, userEvent, migration
Anti-Patterns — Common mistakes to avoid
Files
- ATTRIBUTION.mdAdded by AutoGineer936 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md7.1 KiB
- references/anti-patterns.md6.9 KiB
- references/api-reference-v13.md19.5 KiB
- references/api-reference-v14.md18.6 KiB
references/anti-patterns.md
RNTL Anti-Patterns
Table of Contents
Wrong query variant
Not using *ByRole
Wrong assertions
waitFor misuse
Unnecessary act()
fireEvent instead of userEvent
Destructuring render
Using UNSAFE_root
Manual cleanup
Legacy accessibility props
Forgetting to await (v14)
Using removed APIs (v14)
Wrong query variant
// BAD: queryBy* when element should exist
const button = screen.queryByRole('button');
expect(button).toBeOnTheScreen();
// GOOD: getBy* when element should exist
const button = screen.getByRole('button');
expect(button).toBeOnTheScreen();
// BAD: getBy* for non-existence check (throws instead of failing gracefully)
expect(screen.getByText('Error')).not.toBeOnTheScreen();
// GOOD: queryBy* for non-existence check
expect(screen.queryByText('Error')).not.toBeOnTheScreen();
// BAD: waitFor + getBy* for async elements
await waitFor(() => {
expect(screen.getByText('Loaded')).toBeOnTheScreen();
});
// GOOD: findBy* for async elements
expect(await screen.findByText('Loaded')).toBeOnTheScreen();Not using *ByRole
// BAD: testID when accessible query works
<Pressable testID="submit-btn" role="button">
<Text>Submit</Text>
</Pressable>;
screen.getByTestId('submit-btn');
// GOOD: query by role and accessible name
screen.getByRole('button', { name: 'Submit' });
// BAD: getByText for a button (less semantic)
screen.getByText('Submit');
// GOOD: getByRole with name (more semantic, tests accessibility)
screen.getByRole('button', { name: 'Submit' });Wrong assertions
// BAD: asserting on props directly
expect(button.props['aria-disabled']).toBe(true);
expect(button.props.style.backgroundColor).toBe('red');
// GOOD: use RNTL matchers
expect(button).toBeDisabled();
expect(button).toHaveStyle({ backgroundColor: 'red' });
// BAD: redundant null check (getBy already throws)
const el = screen.getByText('Hello');
expect(el).not.toBeNull();
// GOOD: use toBeOnTheScreen
expect(screen.getByText('Hello')).toBeOnTheScreen();waitFor misuse
// BAD: side-effect inside waitFor (press runs on every retry)
await waitFor(() => {
fireEvent.press(screen.getByRole('button'));
expect(screen.getByText('Result')).toBeOnTheScreen();
});
// GOOD: side-effect outside, assertion inside
fireEvent.press(screen.getByRole('button'));
await waitFor(() => {
expect(screen.getByText('Result')).toBeOnTheScreen();
});
// BETTER: use findBy*
fireEvent.press(screen.getByRole('button'));
expect(await screen.findByText('Result')).toBeOnTheScreen();
// BAD: empty waitFor callback
await waitFor(() => {});
// BAD: multiple assertions in single waitFor
await waitFor(() => {
expect(screen.getByText('Title')).toBeOnTheScreen();
expect(screen.getByText('Subtitle')).toBeOnTheScreen();
});
// GOOD: one assertion per waitFor, rest after
await waitFor(() => {
expect(screen.getByText('Title')).toBeOnTheScreen();
});
expect(screen.getByText('Subtitle')).toBeOnTheScreen();Unnecessary act()
// BAD: wrapping render in act
act(() => {
render(<Component />);
});
// GOOD: render handles act internally
render(<Component />);
// BAD: wrapping fireEvent in act
act(() => {
fireEvent.press(button);
});
// GOOD: fireEvent handles act internally
fireEvent.press(button);
// BAD: wrapping userEvent in act
await act(async () => {
await user.press(button);
});
// GOOD: userEvent handles act internally
await user.press(button);fireEvent instead of userEvent
// BAD: fireEvent.press (only fires onPress, no pressIn/pressOut)
fireEvent.press(button);
// GOOD: userEvent.press (full press lifecycle)
const user = userEvent.setup();
await user.press(button);
// BAD: fireEvent.changeText (sets text all at once, no focus/blur/keyPress)
fireEvent.changeText(input, 'Hello');
// GOOD: user.type (char-by-char with full event sequence)
await user.type(input, 'Hello');Destructuring render
// BAD: destructuring queries from render
const { getByText, getByRole } = render(<Component />);
getByText('Hello');
// GOOD: use screen object
render(<Component />);
screen.getByText('Hello');Using UNSAFE_root
// BAD: traversing the tree manually
const { UNSAFE_root } = render(<Component />);
const el = UNSAFE_root.findAll((node) => node.props.testID === 'foo')[0];
// GOOD: use proper queries
render(<Component />);
screen.getByTestId('foo');Manual cleanup
// BAD: calling cleanup manually (it's automatic)
afterEach(() => {
cleanup();
});
// GOOD: just don't - RNTL auto-cleans after each testLegacy accessibility props
// BAD: legacy accessibility props
<Pressable accessibilityRole="button" accessibilityLabel="Submit">
<Text>Submit</Text>
</Pressable>
// GOOD: ARIA-compatible props
<Pressable role="button" aria-label="Submit">
<Text>Submit</Text>
</Pressable>
// BAD: legacy state props
<Pressable accessibilityState={{ disabled: true, checked: true }}>
// GOOD: ARIA state props
<Pressable aria-disabled aria-checked>Forgetting to await (v14)
In RNTL v14, render, fireEvent, rerender, unmount, renderHook, and act are async. Forgetting await causes subtle bugs where tests pass but assertions run before operations complete.
// BAD: missing await on render (v14)
render(<Component />);
expect(screen.getByText('Hello')).toBeOnTheScreen(); // may fail intermittently
// GOOD: await render (v14)
await render(<Component />);
expect(screen.getByText('Hello')).toBeOnTheScreen();
// BAD: missing await on fireEvent (v14)
fireEvent.press(screen.getByRole('button'));
// state updates may not have flushed yet
// GOOD: await fireEvent (v14)
await fireEvent.press(screen.getByRole('button'));
// BAD: missing await on act (v14)
act(() => {
result.current.increment();
});
// GOOD: await act (v14)
await act(() => {
result.current.increment();
});Using removed APIs (v14)
These APIs exist in v13 but are removed in v14. Using them will cause import or runtime errors.
// BAD: using renderAsync in v14 (removed — render is already async)
import { renderAsync } from '@testing-library/react-native';
await renderAsync(<Component />);
// GOOD: use render in v14
import { render } from '@testing-library/react-native';
await render(<Component />);
// BAD: using fireEventAsync in v14 (removed — fireEvent is already async)
import { fireEventAsync } from '@testing-library/react-native';
await fireEventAsync.press(button);
// GOOD: use fireEvent in v14
import { fireEvent } from '@testing-library/react-native';
await fireEvent.press(button);
// BAD: using UNSAFE_root in v14 (removed)
screen.UNSAFE_root;
// GOOD: use container or root in v14
screen.container;
screen.root;
// BAD: using concurrentRoot option in v14 (removed — always on)
render(<Component />, { concurrentRoot: false });
// GOOD: just render without concurrentRoot
await render(<Component />);
// BAD: using update() in v14 (removed)
screen.update(<Component newProp />);
// GOOD: use rerender in v14
await screen.rerender(<Component newProp />);Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Callstack
- Publisher
- Callstack (Official)
- Source
- callstackincubator/agent-skills · plugins/vendored/.agents/skills/react-native-testing · commit 59e9d17
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Callstack.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react-native-testing.zip