0
# Jest Native
1

2
Jest Native provides custom Jest matchers specifically designed for testing React Native components and applications. It extends Jest's assertion capabilities with React Native-specific matchers that understand component states, accessibility properties, and React Native-specific behaviors like visibility, styling, and component hierarchy relationships.
3

4
## Package Information
5

6
- **Package Name**: @testing-library/jest-native
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @testing-library/jest-native`
10

11
## Core Imports
12

13
```typescript
14
import '@testing-library/jest-native/extend-expect';
15
```
16

17
For selective imports:
18

19
```typescript
20
import { toBeDisabled, toHaveTextContent, toHaveStyle } from '@testing-library/jest-native';
21

22
expect.extend({ toBeDisabled, toHaveTextContent, toHaveStyle });
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { render } from '@testing-library/react-native';
29
import '@testing-library/jest-native/extend-expect';
30

31
const MyComponent = () => (
32
  <View>
33
    <Text testID="greeting">Hello World</Text>
34
    <TextInput testID="input" value="test" editable={false} />
35
    <Button title="Submit" disabled={true} />
36
  </View>
37
);
38

39
test('component rendering and states', () => {
40
  const { getByTestId, getByText } = render(<MyComponent />);
41
  
42
  // Text content assertion
43
  expect(getByTestId('greeting')).toHaveTextContent('Hello World');
44
  
45
  // Disabled state assertion
46
  expect(getByTestId('input')).toBeDisabled();
47
  expect(getByText('Submit')).toBeDisabled();
48
  
49
  // Visibility assertion
50
  expect(getByTestId('greeting')).toBeVisible();
51
});
52
```
53

54
## Architecture
55

56
Jest Native extends Jest's `expect` object with custom matchers that work with ReactTestInstance objects from react-test-renderer. The matchers are designed to:
57

58
- **Understand React Native Components**: Work with React Native-specific elements like View, Text, TextInput, Button, etc.
59
- **Support Accessibility**: Test accessibility states, values, and properties
60
- **Handle Component Hierarchy**: Test parent-child relationships and element containment
61
- **Provide Type Safety**: Full TypeScript support with proper type definitions
62
- **Offer Flexible Setup**: Support both global extension and selective imports
63

64
## Capabilities
65

66
### Element State Testing
67

68
Test whether React Native elements are enabled or disabled based on component props and accessibility states.
69

70
```typescript { .api }
71
/**
72
 * Tests if a React Native element is disabled
73
 */
74
toBeDisabled(): jest.MatcherResult;
75

76
/**
77
 * Tests if a React Native element is enabled (opposite of disabled)
78
 */
79
toBeEnabled(): jest.MatcherResult;
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
// Button disabled state
86
expect(getByText('Submit')).toBeDisabled();
87
expect(getByText('Cancel')).toBeEnabled();
88

89
// TextInput editable state
90
expect(getByTestId('readonly-input')).toBeDisabled();
91
expect(getByTestId('editable-input')).toBeEnabled();
92

93
// Accessibility-based disabled state
94
expect(getByLabelText('Disabled Button')).toBeDisabled();
95
```
96

97
### Element Content Testing
98

99
Test whether React Native elements have specific content or are empty.
100

101
```typescript { .api }
102
/**
103
 * Tests if a React Native element has no children
104
 */
105
toBeEmptyElement(): jest.MatcherResult;
106

107
/**
108
 * Tests if a React Native element has specific text content
109
 * @param text - Text to match (string or regex)
110
 */
111
toHaveTextContent(text: string | RegExp): jest.MatcherResult;
112

113
/**
114
 * @deprecated Use toBeEmptyElement instead
115
 */
116
toBeEmpty(): jest.MatcherResult;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
// Text content matching
123
expect(getByTestId('title')).toHaveTextContent('Welcome');
124
expect(getByTestId('description')).toHaveTextContent(/Hello.*World/);
125

126
// Empty element testing
127
expect(getByTestId('empty-container')).toBeEmptyElement();
128
```
129

130
### Element Visibility Testing
131

132
Test whether React Native elements are visible or present on the screen.
133

134
```typescript { .api }
135
/**
136
 * Tests if a React Native element is visible
137
 */
138
toBeVisible(): jest.MatcherResult;
139

140
/**
141
 * Tests if a React Native element is present on the screen
142
 */
143
toBeOnTheScreen(): jest.MatcherResult;
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
// Visibility testing
150
expect(getByTestId('modal')).toBeVisible();
151
expect(getByTestId('hidden-element')).not.toBeVisible();
152

153
// Screen presence testing
154
expect(getByTestId('rendered-component')).toBeOnTheScreen();
155
```
156

157
### Element Hierarchy Testing
158

159
Test parent-child relationships between React Native elements.
160

161
```typescript { .api }
162
/**
163
 * Tests if a React Native element contains another element
164
 * @param element - The element to check for containment
165
 */
166
toContainElement(element: ReactTestInstance | null): jest.MatcherResult;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
// Element containment
173
const container = getByTestId('container');
174
const child = getByTestId('child');
175
expect(container).toContainElement(child);
176

177
// Nested component testing
178
const form = getByTestId('form');
179
const submitButton = getByText('Submit');
180
expect(form).toContainElement(submitButton);
181
```
182

183
### Element Properties Testing
184

185
Test React Native element props and styling.
186

187
```typescript { .api }
188
/**
189
 * Tests if a React Native element has a specific prop with optional value check
190
 * @param attr - Property name to check
191
 * @param value - Expected value of the property (optional)
192
 */
193
toHaveProp(attr: string, value?: unknown): jest.MatcherResult;
194

195
/**
196
 * Tests if a React Native element has specific styles
197
 * @param style - Style object to match
198
 */
199
toHaveStyle(style: StyleProp<ViewStyle | TextStyle | ImageStyle>): jest.MatcherResult;
200
```
201

202
**Usage Examples:**
203

204
```typescript
205
// Prop testing
206
expect(getByTestId('input')).toHaveProp('placeholder', 'Enter text');
207
expect(getByTestId('image')).toHaveProp('source');
208

209
// Style testing
210
expect(getByTestId('title')).toHaveStyle({
211
  fontSize: 24,
212
  fontWeight: 'bold',
213
  color: '#333'
214
});
215

216
expect(getByTestId('container')).toHaveStyle({
217
  flexDirection: 'row',
218
  justifyContent: 'center'
219
});
220
```
221

222
### Accessibility Testing
223

224
Test React Native accessibility states and values.
225

226
```typescript { .api }
227
/**
228
 * Tests if a React Native element has specific accessibility state
229
 * @param state - Expected accessibility state object
230
 */
231
toHaveAccessibilityState(state: AccessibilityState): jest.MatcherResult;
232

233
/**
234
 * Tests if a React Native element has specific accessibility value
235
 * @param value - Expected accessibility value matcher
236
 */
237
toHaveAccessibilityValue(value: AccessibilityValueMatcher): jest.MatcherResult;
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
// Accessibility state testing
244
expect(getByLabelText('Toggle')).toHaveAccessibilityState({
245
  disabled: false,
246
  selected: true
247
});
248

249
expect(getByTestId('checkbox')).toHaveAccessibilityState({
250
  checked: true
251
});
252

253
// Accessibility value testing
254
expect(getByLabelText('Volume')).toHaveAccessibilityValue({
255
  min: 0,
256
  max: 100,
257
  now: 50
258
});
259

260
expect(getByLabelText('Progress')).toHaveAccessibilityValue({
261
  text: '50% complete'
262
});
263
```
264

265
## Types
266

267
```typescript { .api }
268
/**
269
 * Accessibility value matcher interface
270
 */
271
interface AccessibilityValueMatcher {
272
  min?: number;
273
  max?: number;
274
  now?: number;
275
  text?: string | RegExp;
276
}
277

278
/**
279
 * Jest Native matchers interface
280
 */
281
interface JestNativeMatchers<R> {
282
  toBeDisabled(): R;
283
  toBeEmptyElement(): R;
284
  toBeEnabled(): R;
285
  toBeOnTheScreen(): R;
286
  toBeVisible(): R;
287
  toContainElement(element: ReactTestInstance | null): R;
288
  toHaveTextContent(text: string | RegExp): R;
289
  toHaveProp(attr: string, value?: unknown): R;
290
  toHaveStyle(style: StyleProp<ViewStyle | TextStyle | ImageStyle>): R;
291
  toHaveAccessibilityState(state: AccessibilityState): R;
292
  toHaveAccessibilityValue(value: AccessibilityValueMatcher): R;
293
  /** @deprecated Use toBeEmptyElement instead */
294
  toBeEmpty(): R;
295
}
296
```
297

298
## Setup Options
299

300
### Modern Setup (Recommended)
301

302
```typescript
303
// jest-setup.ts
304
import '@testing-library/jest-native/extend-expect';
305
```
306

307
### Legacy Setup
308

309
For compatibility with older Jest versions or specific configurations:
310

311
```typescript
312
// jest-setup.ts
313
import '@testing-library/jest-native/legacy-extend-expect';
314
```
315

316
This adds matchers with `legacy_` prefix (e.g., `legacy_toBeDisabled`).
317

318
### TypeScript Configuration
319

320
Add to `declarations.d.ts`:
321

322
```typescript
323
/// <reference types="@testing-library/jest-native" />
324
```
325

326
Or use the TypeScript Jest setup file approach shown above.
327

328
## Error Handling
329

330
All matchers provide detailed error messages with:
331

332
- Clear descriptions of what was expected vs. what was received
333
- Pretty-printed element structures for debugging
334
- Helpful context about component states and properties
335
- Support for negated assertions (using `.not`)
336

337
## Compatibility
338

339
- **React Native**: >=0.59
340
- **React**: >=16.0.0
341
- **React Test Renderer**: >=16.0.0
342
- **Jest**: Compatible with modern Jest versions
343
- **TypeScript**: Full type safety and IDE support