0
# React Native Testing Library
1
2
React Native Testing Library provides simple and complete testing utilities that encourage good testing practices for React Native applications. Built on react-test-renderer, it focuses on testing components the way users interact with them rather than implementation details, promoting maintainable tests that give confidence in application behavior.
3
4
## Package Information
5
6
- **Package Name**: @testing-library/react-native
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @testing-library/react-native`
10
11
## Core Imports
12
13
```typescript
14
import { render, screen, fireEvent, waitFor, userEvent } from "@testing-library/react-native";
15
```
16
17
For pure mode (manual cleanup):
18
19
```typescript
20
import { render, screen, fireEvent, waitFor, userEvent } from "@testing-library/react-native/pure";
21
```
22
23
For Jest matchers only:
24
25
```typescript
26
import "@testing-library/react-native/matchers";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import React from "react";
33
import { Text, View, Pressable } from "react-native";
34
import { render, screen, fireEvent } from "@testing-library/react-native";
35
36
function Button({ onPress, children }) {
37
return (
38
<Pressable onPress={onPress} testID="button">
39
<Text>{children}</Text>
40
</Pressable>
41
);
42
}
43
44
test("calls onPress when pressed", () => {
45
const handlePress = jest.fn();
46
render(<Button onPress={handlePress}>Press me</Button>);
47
48
// Find element by text or testID
49
const button = screen.getByText("Press me");
50
// or: const button = screen.getByTestId("button");
51
52
// Interact with element
53
fireEvent.press(button);
54
55
// Assert behavior
56
expect(handlePress).toHaveBeenCalledTimes(1);
57
});
58
```
59
60
## Architecture
61
62
React Native Testing Library consists of several key systems:
63
64
- **Rendering System**: Component rendering with React Test Renderer integration, supporting both sync and async modes
65
- **Query System**: Comprehensive element finding capabilities using text, accessibility properties, test IDs, and roles
66
- **Event System**: Realistic user interaction simulation through fireEvent and userEvent APIs
67
- **Async Utilities**: Built-in support for testing asynchronous behavior with waitFor and findBy queries
68
- **Jest Matchers**: Extended assertions for React Native-specific component states and properties
69
- **Screen API**: Global access to queries without destructuring render results
70
71
## Capabilities
72
73
### Component Rendering
74
75
Core rendering functionality for React Native components with deep rendering and lifecycle management.
76
77
```typescript { .api }
78
function render<T>(
79
component: React.ReactElement<T>,
80
options?: RenderOptions
81
): RenderResult;
82
83
interface RenderOptions {
84
wrapper?: React.ComponentType<any>;
85
concurrentRoot?: boolean;
86
createNodeMock?: (element: React.ReactElement) => unknown;
87
unstable_validateStringsRenderedWithinText?: boolean;
88
}
89
90
interface RenderResult {
91
// DOM access
92
root: ReactTestInstance;
93
UNSAFE_root: ReactTestInstance;
94
95
// Utilities
96
debug: DebugFunction;
97
rerender: (element: React.ReactElement) => void;
98
unmount: () => void;
99
toJSON: () => ReactTestRendererJSON | null;
100
101
// All query methods (getBy*, getAllBy*, queryBy*, queryAllBy*, findBy*, findAllBy*)
102
// ... (queries omitted for brevity in overview)
103
}
104
```
105
106
[Component Rendering](./rendering.md)
107
108
### Element Queries
109
110
Comprehensive system for finding elements using various strategies including text content, accessibility properties, test IDs, and roles.
111
112
```typescript { .api }
113
// Text queries
114
function getByText(text: string | RegExp, options?: TextMatchOptions): ReactTestInstance;
115
function getAllByText(text: string | RegExp, options?: TextMatchOptions): ReactTestInstance[];
116
function queryByText(text: string | RegExp, options?: TextMatchOptions): ReactTestInstance | null;
117
function findByText(text: string | RegExp, options?: TextMatchOptions & WaitForOptions): Promise<ReactTestInstance>;
118
119
// TestID queries
120
function getByTestId(testId: string | RegExp, options?: TestIdOptions): ReactTestInstance;
121
function getAllByTestId(testId: string | RegExp, options?: TestIdOptions): ReactTestInstance[];
122
123
// Role queries
124
function getByRole(role: string, options?: RoleOptions): ReactTestInstance;
125
function getAllByRole(role: string, options?: RoleOptions): ReactTestInstance[];
126
127
// Accessibility queries
128
function getByLabelText(text: string | RegExp, options?: LabelTextOptions): ReactTestInstance;
129
function getByHintText(text: string | RegExp, options?: HintTextOptions): ReactTestInstance;
130
```
131
132
[Element Queries](./queries.md)
133
134
### User Interactions
135
136
Realistic user interaction simulation supporting press events, text input, scrolling, and other React Native-specific gestures.
137
138
```typescript { .api }
139
// FireEvent - synchronous events
140
declare const fireEvent: {
141
press(element: ReactTestInstance): void;
142
changeText(element: ReactTestInstance, text: string): void;
143
scroll(element: ReactTestInstance, eventData?: object): void;
144
// ... additional event types
145
};
146
147
// UserEvent - more realistic interactions
148
declare const userEvent: {
149
setup(config?: UserEventConfig): UserEventInstance;
150
press(element: ReactTestInstance): Promise<void>;
151
longPress(element: ReactTestInstance, options?: PressOptions): Promise<void>;
152
type(element: ReactTestInstance, text: string, options?: TypeOptions): Promise<void>;
153
clear(element: ReactTestInstance): Promise<void>;
154
paste(element: ReactTestInstance, text: string): Promise<void>;
155
scrollTo(element: ReactTestInstance, options: ScrollToOptions): Promise<void>;
156
};
157
```
158
159
[User Interactions](./interactions.md)
160
161
### Async Testing Utilities
162
163
Built-in utilities for handling asynchronous behavior, waiting for conditions, and testing time-dependent components.
164
165
```typescript { .api }
166
function waitFor<T>(
167
expectation: () => T,
168
options?: WaitForOptions
169
): Promise<T>;
170
171
function waitForElementToBeRemoved<T>(
172
callback: (() => T) | T,
173
options?: WaitForOptions
174
): Promise<void>;
175
176
interface WaitForOptions {
177
timeout?: number;
178
interval?: number;
179
onTimeout?: (error: Error) => Error;
180
}
181
```
182
183
[Async Testing](./async-testing.md)
184
185
### Jest Matchers
186
187
Extended Jest matchers specifically designed for React Native component testing and assertions.
188
189
```typescript { .api }
190
// Visibility and state matchers
191
expect(element).toBeBusy();
192
expect(element).toBeChecked();
193
expect(element).toBeDisabled();
194
expect(element).toBeEnabled();
195
expect(element).toBeVisible();
196
expect(element).toBeOnTheScreen();
197
198
// Content matchers
199
expect(element).toHaveTextContent(text: string | RegExp);
200
expect(element).toHaveDisplayValue(value: string | RegExp);
201
expect(element).toHaveAccessibleName(name: string | RegExp);
202
203
// Property matchers
204
expect(element).toHaveProp(prop: string, value?: any);
205
expect(element).toHaveStyle(style: object);
206
expect(element).toContainElement(element: ReactTestInstance);
207
```
208
209
[Jest Matchers](./matchers.md)
210
211
### Hook Testing
212
213
Specialized utilities for testing React hooks in isolation with proper act wrapping and lifecycle management.
214
215
```typescript { .api }
216
function renderHook<Result, Props>(
217
hook: (props: Props) => Result,
218
options?: RenderHookOptions<Props>
219
): RenderHookResult<Result, Props>;
220
221
interface RenderHookOptions<Props> {
222
initialProps?: Props;
223
wrapper?: React.ComponentType<any>;
224
concurrentRoot?: boolean;
225
}
226
227
interface RenderHookResult<Result, Props> {
228
result: { current: Result };
229
rerender: (props?: Props) => void;
230
unmount: () => void;
231
}
232
```
233
234
[Hook Testing](./hooks.md)
235
236
### Configuration and Setup
237
238
Global configuration options and setup utilities for customizing library behavior across your test suite.
239
240
```typescript { .api }
241
function configure(options: Partial<Config>): void;
242
function resetToDefaults(): void;
243
244
interface Config {
245
asyncUtilTimeout: number;
246
defaultIncludeHiddenElements: boolean;
247
defaultDebugOptions?: Partial<DebugOptions>;
248
concurrentRoot: boolean;
249
}
250
```
251
252
[Configuration](./configuration.md)
253
254
## Core Types
255
256
```typescript { .api }
257
// React Test Renderer types
258
type ReactTestInstance = {
259
type: string | React.ComponentType;
260
props: { [propName: string]: any };
261
parent: ReactTestInstance | null;
262
children: Array<ReactTestInstance | string>;
263
// ... additional properties
264
};
265
266
// Common option types
267
interface TextMatchOptions {
268
exact?: boolean;
269
normalizer?: NormalizerFn;
270
includeHiddenElements?: boolean;
271
}
272
273
interface WaitForOptions {
274
timeout?: number;
275
interval?: number;
276
onTimeout?: (error: Error) => Error;
277
}
278
279
// Utility types
280
type RefObject<T> = { current: T };
281
interface Point { x: number; y: number; }
282
interface Size { width: number; height: number; }
283
```