CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-testing-library--jest-native

Custom jest matchers to test the state of React Native

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Jest Native

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.

Package Information

  • Package Name: @testing-library/jest-native
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @testing-library/jest-native

Core Imports

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

For selective imports:

import { toBeDisabled, toHaveTextContent, toHaveStyle } from '@testing-library/jest-native';

expect.extend({ toBeDisabled, toHaveTextContent, toHaveStyle });

Basic Usage

import { render } from '@testing-library/react-native';
import '@testing-library/jest-native/extend-expect';

const MyComponent = () => (
  <View>
    <Text testID="greeting">Hello World</Text>
    <TextInput testID="input" value="test" editable={false} />
    <Button title="Submit" disabled={true} />
  </View>
);

test('component rendering and states', () => {
  const { getByTestId, getByText } = render(<MyComponent />);
  
  // Text content assertion
  expect(getByTestId('greeting')).toHaveTextContent('Hello World');
  
  // Disabled state assertion
  expect(getByTestId('input')).toBeDisabled();
  expect(getByText('Submit')).toBeDisabled();
  
  // Visibility assertion
  expect(getByTestId('greeting')).toBeVisible();
});

Architecture

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

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

Capabilities

Element State Testing

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

/**
 * Tests if a React Native element is disabled
 */
toBeDisabled(): jest.MatcherResult;

/**
 * Tests if a React Native element is enabled (opposite of disabled)
 */
toBeEnabled(): jest.MatcherResult;

Usage Examples:

// Button disabled state
expect(getByText('Submit')).toBeDisabled();
expect(getByText('Cancel')).toBeEnabled();

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

// Accessibility-based disabled state
expect(getByLabelText('Disabled Button')).toBeDisabled();

Element Content Testing

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

/**
 * Tests if a React Native element has no children
 */
toBeEmptyElement(): jest.MatcherResult;

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

/**
 * @deprecated Use toBeEmptyElement instead
 */
toBeEmpty(): jest.MatcherResult;

Usage Examples:

// Text content matching
expect(getByTestId('title')).toHaveTextContent('Welcome');
expect(getByTestId('description')).toHaveTextContent(/Hello.*World/);

// Empty element testing
expect(getByTestId('empty-container')).toBeEmptyElement();

Element Visibility Testing

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

/**
 * Tests if a React Native element is visible
 */
toBeVisible(): jest.MatcherResult;

/**
 * Tests if a React Native element is present on the screen
 */
toBeOnTheScreen(): jest.MatcherResult;

Usage Examples:

// Visibility testing
expect(getByTestId('modal')).toBeVisible();
expect(getByTestId('hidden-element')).not.toBeVisible();

// Screen presence testing
expect(getByTestId('rendered-component')).toBeOnTheScreen();

Element Hierarchy Testing

Test parent-child relationships between React Native elements.

/**
 * Tests if a React Native element contains another element
 * @param element - The element to check for containment
 */
toContainElement(element: ReactTestInstance | null): jest.MatcherResult;

Usage Examples:

// Element containment
const container = getByTestId('container');
const child = getByTestId('child');
expect(container).toContainElement(child);

// Nested component testing
const form = getByTestId('form');
const submitButton = getByText('Submit');
expect(form).toContainElement(submitButton);

Element Properties Testing

Test React Native element props and styling.

/**
 * Tests if a React Native element has a specific prop with optional value check
 * @param attr - Property name to check
 * @param value - Expected value of the property (optional)
 */
toHaveProp(attr: string, value?: unknown): jest.MatcherResult;

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

Usage Examples:

// Prop testing
expect(getByTestId('input')).toHaveProp('placeholder', 'Enter text');
expect(getByTestId('image')).toHaveProp('source');

// Style testing
expect(getByTestId('title')).toHaveStyle({
  fontSize: 24,
  fontWeight: 'bold',
  color: '#333'
});

expect(getByTestId('container')).toHaveStyle({
  flexDirection: 'row',
  justifyContent: 'center'
});

Accessibility Testing

Test React Native accessibility states and values.

/**
 * Tests if a React Native element has specific accessibility state
 * @param state - Expected accessibility state object
 */
toHaveAccessibilityState(state: AccessibilityState): jest.MatcherResult;

/**
 * Tests if a React Native element has specific accessibility value
 * @param value - Expected accessibility value matcher
 */
toHaveAccessibilityValue(value: AccessibilityValueMatcher): jest.MatcherResult;

Usage Examples:

// Accessibility state testing
expect(getByLabelText('Toggle')).toHaveAccessibilityState({
  disabled: false,
  selected: true
});

expect(getByTestId('checkbox')).toHaveAccessibilityState({
  checked: true
});

// Accessibility value testing
expect(getByLabelText('Volume')).toHaveAccessibilityValue({
  min: 0,
  max: 100,
  now: 50
});

expect(getByLabelText('Progress')).toHaveAccessibilityValue({
  text: '50% complete'
});

Types

/**
 * Accessibility value matcher interface
 */
interface AccessibilityValueMatcher {
  min?: number;
  max?: number;
  now?: number;
  text?: string | RegExp;
}

/**
 * Jest Native matchers interface
 */
interface JestNativeMatchers<R> {
  toBeDisabled(): R;
  toBeEmptyElement(): R;
  toBeEnabled(): R;
  toBeOnTheScreen(): R;
  toBeVisible(): R;
  toContainElement(element: ReactTestInstance | null): R;
  toHaveTextContent(text: string | RegExp): R;
  toHaveProp(attr: string, value?: unknown): R;
  toHaveStyle(style: StyleProp<ViewStyle | TextStyle | ImageStyle>): R;
  toHaveAccessibilityState(state: AccessibilityState): R;
  toHaveAccessibilityValue(value: AccessibilityValueMatcher): R;
  /** @deprecated Use toBeEmptyElement instead */
  toBeEmpty(): R;
}

Setup Options

Modern Setup (Recommended)

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

Legacy Setup

For compatibility with older Jest versions or specific configurations:

// jest-setup.ts
import '@testing-library/jest-native/legacy-extend-expect';

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

TypeScript Configuration

Add to declarations.d.ts:

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

Or use the TypeScript Jest setup file approach shown above.

Error Handling

All matchers provide detailed error messages with:

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

Compatibility

  • React Native: >=0.59
  • React: >=16.0.0
  • React Test Renderer: >=16.0.0
  • Jest: Compatible with modern Jest versions
  • TypeScript: Full type safety and IDE support
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@testing-library/jest-native@5.4.x
Publish Source
CLI
Badge
tessl/npm-testing-library--jest-native badge