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
```