@testing-library/jest-native

To use the custom matchers in your tests, you can either extend Jest globally or selectively.

Global Extension

Import @testing-library/jest-native/extend-expect once in your Jest setup file (e.g., the file configured in setupFilesAfterEnv).

Selective Extension

Import only the specific matchers you need and use expect.extend() to add them to Jest manually.

// Option 1: Global extension (recommended for setup files)
import '@testing-library/jest-native/extend-expect';

// Option 2: Selective extension
import { toBeEmptyElement, toHaveTextContent } from '@testing-library/jest-native';

expect.extend({ toBeEmptyElement, toHaveTextContent });

To enable TypeScript type checking and VS Code intellisense for the custom matchers, use one of the following two methods:

Method 1: TypeScript Jest setup file

Use a .ts file (e.g., jest-setup.ts) in your Jest setupFilesAfterEnv configuration and include the following import:

import '@testing-library/jest-native/extend-expect';

Method 2: Declarations file

Create or update a declarations.d.ts file at your project's root and add a triple-slash reference at the top:

/// <reference types="@testing-library/jest-native" />

Install @testing-library/jest-native as a devDependency. This package requires react-test-renderer, react, and react-native to be installed in your project.

# Using npm
npm install --save-dev @testing-library/jest-native

# Using yarn
yarn add --dev @testing-library/jest-native

⚠️ DEPRECATION NOTICE

@testing-library/jest-native is deprecated and no longer actively maintained.

Users are encouraged to migrate to React Native Testing Library, v12.4 or later, which includes modern built-in Jest matchers. A migration guide is available at https://callstack.github.io/react-native-testing-library/docs/migration/jest-matchers.

If you encounter an error when using toBeOnTheScreen, it is likely because the matcher cannot find the screen object from @testing-library/react-native.

Error Message: Could not import screen object from @testing-library/react-native. Using toBeOnTheScreen() matcher requires @testing-library/react-native v10.1.0 or later to be added to your devDependencies.

Solution: Ensure that @testing-library/react-native is installed and that its version is at least v10.1.0.

The toBeOnTheScreen matcher verifies if a React element is part of the current screen tree. It works by comparing the root of the provided element with the root of the @testing-library/react-native screen object.

Requirements: To use this matcher, you must have @testing-library/react-native version v10.1.0 or later installed in your devDependencies.

// Example usage (assuming matchers are configured in jest.setup.js)
expect(element).toBeOnTheScreen();
expect(element).not.toBeOnTheScreen();

The toHaveStyle matcher allows you to assert that a React Native component has specific style properties. It uses StyleSheet.flatten internally, meaning you can pass in partial style objects, arrays of styles, or objects containing style properties, and it will compare them against the flattened styles of the element.

When an assertion fails, the matcher provides a diff highlighting which expected style rules were missing from the received element.

// Example usage of toHaveStyle
expect(element).toHaveStyle({
  backgroundColor: 'red',
  marginTop: 10,
});

// It also works with the .not modifier
expect(element).not.toHaveStyle({
  opacity: 0,
});

The toBeVisible matcher allows you to assert that a React Native component is visible to the user. An element is considered visible if it satisfies all of the following conditions for itself and all of its ancestors:

1. Styles: The display property is not 'none' and the opacity is not 0.
2. Accessibility: The accessibilityElementsHidden prop is not true and importantForAccessibility is not 'no-hide-descendants'.
3. Modals: If the element is a Modal, its visible prop must be true.

If any ancestor fails these checks, the element is considered not visible.

// Example usage with a React Test Renderer instance
expect(element).toBeVisible();

// Example usage with a negative assertion
expect(element).not.toBeVisible();

The @testing-library/jest-native package provides a collection of custom Jest matchers designed for testing React Native components. You can import these matchers directly from the package entrypoint to use them in your Jest tests. These matchers allow you to make assertions about component visibility, accessibility states, props, styles, and more.

import '@testing-library/jest-native';

// After importing, matchers are available on Jest's 'expect' object
expect(element).toBeVisible();
expect(element).toBeDisabled();

The toHaveProp matcher allows you to assert that a React component instance has a specific prop, optionally checking its value.

• To check if a prop exists (regardless of value): Pass undefined as the expectedValue.
• To check if a prop has a specific value: Pass the expected value as the expectedValue.

Note: This matcher operates on ReactTestInstance objects (typically from react-test-renderer).

// Checking if a prop exists
expect(element).toHaveProp('disabled');

// Checking if a prop has a specific value
expect(element).toHaveProp('value', 'hello world');

The toHaveAccessibilityState matcher allows you to assert that a React Native element has a specific accessibilityState. You can pass a partial AccessibilityState object to the matcher; it will only validate the keys you provide, ignoring others.

Supported state keys include:

• disabled
• selected
• checked
• busy
• expanded

If a key is omitted from your expected object, it is treated as undefined and will not cause the test to fail.

// Example usage with a partial state
expect(element).toHaveAccessibilityState({
  disabled: true,
  selected: false,
});

// Example using the .not modifier
expect(element).not.toHaveAccessibilityState({
  busy: true,
});

The toHaveAccessibilityValue matcher allows you to assert that a React Native element has specific accessibilityValue properties. You can check for a specific min, max, now value, or a text value (which supports both strings and Regular Expressions).

To use this matcher, pass an object containing the properties you want to validate to toHaveAccessibilityValue.

// Example assertion
expect(element).toHaveAccessibilityValue({
  min: 0,
  max: 100,
  now: 50,
  text: '50\ actually 50%'
});

// Example with RegExp for text
expect(element).toHaveAccessibilityValue({
  text: /50/
});