0
# Component Rendering
1

2
Core rendering functionality for React Native components providing deep rendering capabilities, lifecycle management, and both synchronous and asynchronous rendering modes.
3

4
## Capabilities
5

6
### Render Function
7

8
Primary component rendering function that deeply renders React Native components using React Test Renderer.
9

10
```typescript { .api }
11
/**
12
 * Renders test component deeply using React Test Renderer and exposes helpers
13
 * to assert on the output.
14
 * @param component - React element to render
15
 * @param options - Optional rendering configuration
16
 * @returns RenderResult with queries and utilities
17
 */
18
function render<T>(
19
  component: React.ReactElement<T>, 
20
  options?: RenderOptions
21
): RenderResult;
22

23
interface RenderOptions {
24
  /** React Component wrapper to render around the component */
25
  wrapper?: React.ComponentType<any>;
26
  /** Set to false to disable concurrent rendering (defaults to true) */
27
  concurrentRoot?: boolean;
28
  /** Function to create mock nodes for native elements */
29
  createNodeMock?: (element: React.ReactElement) => unknown;
30
  /** Validate strings are rendered within Text components */
31
  unstable_validateStringsRenderedWithinText?: boolean;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import React from "react";
39
import { View, Text } from "react-native";
40
import { render } from "@testing-library/react-native";
41

42
// Basic rendering
43
const MyComponent = () => (
44
  <View>
45
    <Text>Hello World</Text>
46
  </View>
47
);
48

49
test("renders component", () => {
50
  const { getByText } = render(<MyComponent />);
51
  expect(getByText("Hello World")).toBeOnTheScreen();
52
});
53

54
// With wrapper for providers
55
const ThemeProvider = ({ children }) => (
56
  <ThemeContext.Provider value={theme}>
57
    {children}
58
  </ThemeContext.Provider>
59
);
60

61
test("renders with theme provider", () => {
62
  const { getByText } = render(<MyComponent />, {
63
    wrapper: ThemeProvider
64
  });
65
});
66

67
// With createNodeMock for ref testing
68
test("renders with node mocks", () => {
69
  const mockScrollTo = jest.fn();
70
  const { getByTestId } = render(<ScrollViewComponent />, {
71
    createNodeMock: (element) => {
72
      if (element.type === "RCTScrollView") {
73
        return { scrollTo: mockScrollTo };
74
      }
75
      return null;
76
    }
77
  });
78
});
79
```
80

81
### Render Result
82

83
Complete result object returned by render function containing queries, utilities, and component access.
84

85
```typescript { .api }
86
interface RenderResult {
87
  /** Root element of the rendered component tree */
88
  root: ReactTestInstance;
89
  /** Legacy root access (deprecated) */
90
  UNSAFE_root: ReactTestInstance;
91
  
92
  /** Debug the rendered component tree */
93
  debug: DebugFunction;
94
  /** Re-render component with new props */
95
  rerender: (element: React.ReactElement) => void;
96
  /** Unmount the component */
97
  unmount: () => void;
98
  /** Get JSON representation of the rendered tree */
99
  toJSON: () => ReactTestRendererJSON | null;
100
  
101
  // Text queries
102
  getByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance;
103
  getAllByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance[];
104
  queryByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance | null;
105
  queryAllByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance[];
106
  findByText: (text: string | RegExp, options?: TextMatchOptions & WaitForOptions) => Promise<ReactTestInstance>;
107
  findAllByText: (text: string | RegExp, options?: TextMatchOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
108
  
109
  // TestID queries
110
  getByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance;
111
  getAllByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance[];
112
  queryByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance | null;
113
  queryAllByTestId: (testId: string | RegExp, options?: TestIdOptions) => ReactTestInstance[];
114
  findByTestId: (testId: string | RegExp, options?: TestIdOptions & WaitForOptions) => Promise<ReactTestInstance>;
115
  findAllByTestId: (testId: string | RegExp, options?: TestIdOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
116
  
117
  // Role queries
118
  getByRole: (role: string, options?: RoleOptions) => ReactTestInstance;
119
  getAllByRole: (role: string, options?: RoleOptions) => ReactTestInstance[];
120
  queryByRole: (role: string, options?: RoleOptions) => ReactTestInstance | null;
121
  queryAllByRole: (role: string, options?: RoleOptions) => ReactTestInstance[];
122
  findByRole: (role: string, options?: RoleOptions & WaitForOptions) => Promise<ReactTestInstance>;
123
  findAllByRole: (role: string, options?: RoleOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
124
  
125
  // Label text queries
126
  getByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance;
127
  getAllByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance[];
128
  queryByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance | null;
129
  queryAllByLabelText: (text: string | RegExp, options?: LabelTextOptions) => ReactTestInstance[];
130
  findByLabelText: (text: string | RegExp, options?: LabelTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
131
  findAllByLabelText: (text: string | RegExp, options?: LabelTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
132
  
133
  // Hint text queries  
134
  getByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
135
  getAllByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
136
  queryByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
137
  queryAllByHintText: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
138
  findByHintText: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
139
  findAllByHintText: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
140
  
141
  // Accessibility hint aliases
142
  getByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
143
  getAllByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
144
  queryByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
145
  queryAllByA11yHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
146
  findByA11yHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
147
  findAllByA11yHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
148
  
149
  getByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance;
150
  getAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
151
  queryByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance | null;
152
  queryAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions) => ReactTestInstance[];
153
  findByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
154
  findAllByAccessibilityHint: (text: string | RegExp, options?: HintTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
155
  
156
  // Placeholder text queries
157
  getByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance;
158
  getAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance[];
159
  queryByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance | null;
160
  queryAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions) => ReactTestInstance[];
161
  findByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions & WaitForOptions) => Promise<ReactTestInstance>;
162
  findAllByPlaceholderText: (text: string | RegExp, options?: PlaceholderTextOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
163
  
164
  // Display value queries
165
  getByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance;
166
  getAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance[];
167
  queryByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance | null;
168
  queryAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions) => ReactTestInstance[];
169
  findByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions & WaitForOptions) => Promise<ReactTestInstance>;
170
  findAllByDisplayValue: (value: string | RegExp, options?: DisplayValueOptions & WaitForOptions) => Promise<ReactTestInstance[]>;
171
  
172
  // Unsafe queries (advanced usage)
173
  UNSAFE_getByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance;
174
  UNSAFE_getAllByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance[];
175
  UNSAFE_queryByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance | null;
176
  UNSAFE_queryAllByType: (type: React.ComponentType | string, options?: TypeOptions) => ReactTestInstance[];
177
  
178
  UNSAFE_getByProps: (props: object, options?: PropsOptions) => ReactTestInstance;
179
  UNSAFE_getAllByProps: (props: object, options?: PropsOptions) => ReactTestInstance[];
180
  UNSAFE_queryByProps: (props: object, options?: PropsOptions) => ReactTestInstance | null;
181
  UNSAFE_queryAllByProps: (props: object, options?: PropsOptions) => ReactTestInstance[];
182
}
183
```
184

185
### Async Rendering
186

187
Asynchronous rendering function for components that require async setup or concurrent rendering.
188

189
```typescript { .api }
190
/**
191
 * Async version of render for concurrent rendering scenarios
192
 * @param component - React element to render
193
 * @param options - Optional async rendering configuration
194
 * @returns Promise resolving to RenderAsyncResult
195
 */
196
function renderAsync<T>(
197
  component: React.ReactElement<T>,
198
  options?: RenderAsyncOptions
199
): Promise<RenderAsyncResult>;
200

201
interface RenderAsyncOptions {
202
  wrapper?: React.ComponentType<any>;
203
  concurrentRoot?: boolean;
204
  createNodeMock?: (element: React.ReactElement) => unknown;
205
  unstable_validateStringsRenderedWithinText?: boolean;
206
}
207

208
interface RenderAsyncResult {
209
  // Same as RenderResult but with async methods
210
  root: ReactTestInstance;
211
  UNSAFE_root: ReactTestInstance;
212
  debug: DebugFunction;
213
  rerenderAsync: (element: React.ReactElement) => Promise<void>;
214
  updateAsync: (element: React.ReactElement) => Promise<void>;
215
  unmountAsync: () => Promise<void>;
216
  toJSON: () => ReactTestRendererJSON | null;
217
  
218
  // All the same query methods as RenderResult
219
  // ... (queries omitted for brevity)
220
}
221
```
222

223
**Usage Examples:**
224

225
```typescript
226
import { renderAsync } from "@testing-library/react-native";
227

228
test("async component rendering", async () => {
229
  const AsyncComponent = () => {
230
    const [data, setData] = useState(null);
231
    
232
    useEffect(() => {
233
      fetchData().then(setData);
234
    }, []);
235
    
236
    return data ? <Text>{data.message}</Text> : <Text>Loading...</Text>;
237
  };
238

239
  const { findByText } = await renderAsync(<AsyncComponent />);
240
  
241
  // Wait for async data to load
242
  await expect(findByText("Loaded message")).resolves.toBeOnTheScreen();
243
});
244
```
245

246
### Debug Function
247

248
Utility function for debugging rendered component trees during test development.
249

250
```typescript { .api }
251
/**
252
 * Debug function for inspecting rendered component tree
253
 * @param element - Optional element to debug (defaults to entire tree)
254
 * @param maxLength - Maximum length of output
255
 * @param options - Debug formatting options  
256
 */
257
interface DebugFunction {
258
  (element?: ReactTestInstance, maxLength?: number, options?: DebugOptions): void;
259
}
260

261
interface DebugOptions {
262
  mapProps?: (props: Record<string, any>) => Record<string, any>;
263
  maxLength?: number;
264
}
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
test("debug component tree", () => {
271
  const { debug, getByTestId } = render(<MyComponent />);
272
  
273
  // Debug entire tree
274
  debug();
275
  
276
  // Debug specific element
277
  const button = getByTestId("submit-button");
278
  debug(button);
279
  
280
  // Debug with options
281
  debug(button, 1000, { 
282
    mapProps: (props) => ({ ...props, onPress: "[Function]" })
283
  });
284
});
285
```
286

287
## Screen Global API
288

289
Global screen object providing access to queries without destructuring render result.
290

291
```typescript { .api }
292
/**
293
 * Global screen object with all query methods
294
 * Available after calling render()
295
 */
296
declare const screen: {
297
  // All the same methods as RenderResult
298
  debug: DebugFunction;
299
  root: ReactTestInstance;
300
  UNSAFE_root: ReactTestInstance;
301
  
302
  // All query methods (getBy*, getAllBy*, queryBy*, queryAllBy*, findBy*, findAllBy*)
303
  getByText: (text: string | RegExp, options?: TextMatchOptions) => ReactTestInstance;
304
  // ... (all other query methods)
305
};
306
```
307

308
**Usage Examples:**
309

310
```typescript
311
import { render, screen } from "@testing-library/react-native";
312

313
test("using screen API", () => {
314
  render(<MyComponent />);
315
  
316
  // Use screen instead of destructuring
317
  const button = screen.getByText("Press me");
318
  const input = screen.getByPlaceholderText("Enter name");
319
  
320
  // Debug using screen
321
  screen.debug();
322
});
323
```
324

325
## Cleanup and Lifecycle
326

327
Cleanup functions for managing component lifecycle and test isolation.
328

329
```typescript { .api }
330
/**
331
 * Clean up rendered components synchronously
332
 */
333
function cleanup(): void;
334

335
/**
336
 * Clean up rendered components asynchronously
337
 * @returns Promise that resolves when cleanup is complete
338
 */
339
function cleanupAsync(): Promise<void>;
340
```
341

342
**Usage Examples:**
343

344
```typescript
345
import { render, cleanup, cleanupAsync } from "@testing-library/react-native/pure";
346

347
afterEach(() => {
348
  cleanup(); // or cleanupAsync() for async cleanup
349
});
350

351
// Manual cleanup in specific tests
352
test("manual cleanup", async () => {
353
  render(<MyComponent />);
354
  // ... test logic
355
  
356
  await cleanupAsync();
357
  
358
  render(<AnotherComponent />);
359
  // ... more test logic
360
});
361
```