Product
Introducing Java Support in Socket
We're excited to announce that Socket now supports the Java programming language.
@testing-library/jest-native
Advanced tools
Custom jest matchers to test the state of React Native
@testing-library/jest-native is a set of custom jest matchers to test the state of React Native components. It extends jest-dom to provide more specific matchers for React Native components, making it easier to write tests that are more readable and maintainable.
toHaveTextContent
This matcher checks if a React Native component contains the specified text content. It is useful for verifying that text elements render the correct content.
expect(element).toHaveTextContent('Hello World')
toBeDisabled
This matcher checks if a button or other interactive element is disabled. It helps ensure that the UI behaves correctly based on the component's state.
expect(button).toBeDisabled()
toHaveStyle
This matcher checks if a component has the specified style properties. It is useful for verifying that styles are applied correctly to components.
expect(element).toHaveStyle({ color: 'red' })
toBeVisible
This matcher checks if a component is visible in the UI. It helps ensure that elements are rendered and visible to the user as expected.
expect(element).toBeVisible()
jest-dom provides custom jest matchers to test the state of the DOM. While it is primarily designed for web applications, it offers similar functionality to @testing-library/jest-native for testing the state of DOM elements. However, it does not provide matchers specific to React Native components.
react-native-testing-library is a lightweight solution for testing React Native components. It provides utilities to render components and query elements, similar to @testing-library/react. While it does not offer custom jest matchers like @testing-library/jest-native, it is often used in conjunction with it to provide a comprehensive testing solution for React Native applications.
You want to use jest to write tests that assert various things about the state of a React Native app. As part of that goal, you want to avoid all the repetitive patterns that arise in doing so like checking for a native element's props, its text content, its styles, and more.
The jest-native
library provides a set of custom jest matchers that you can use to extend jest.
These will make your tests more declarative, clear to read and to maintain.
These matchers should, for the most part, be agnostic enough to work with any React Native testing utilities, but they are primarily intended to be used with React Native Testing Library. Any issues raised with existing matchers or any newly proposed matchers must be viewed through compatibility with that library and its guiding principles first.
This module should be installed as one of your project's devDependencies
:
yarn
yarn add --dev @testing-library/jest-native
npm
npm install --save-dev @testing-library/jest-native
You will need react-test-renderer
, react
, and react-native
installed in order to use this
package.
Import @testing-library/jest-native/extend-expect
once (for instance in your
tests setup file) and you're good
to go:
import '@testing-library/jest-native/extend-expect';
Alternatively, you can selectively import only the matchers you intend to use, and extend jest's
expect
yourself:
import { toBeEmptyElement, toHaveTextContent } from '@testing-library/jest-native';
expect.extend({ toBeEmptyElement, toHaveTextContent });
In order to setup proper TypeScript type checking use either one of the following approches.
Use jest-setup.ts
file (instead of jest-setup.js
file) which is added to Jest config's setupFilesAfterEnv
option.
The Jest setup file should contain following line:
import '@testing-library/jest-native/extend-expect';
This should enable TypeScript checkign for both tsc
and VS Code intellisense.
declarations.d.ts
fileAlternatively, create declarations.d.ts
file at the root level of your project, if it does not exist already.
Add following line at the top of your declarations.d.ts
:
/// <reference types="@testing-library/jest-native" />
This should enable TypeScript checkign for both tsc
and VS Code intellisense.
jest-native
has only been tested to work with
React Native Testing Library. Keep in
mind that these queries are intended only to work with elements corresponding to
host components.
toBeDisabled
toBeDisabled();
Check whether or not an element is disabled from a user perspective.
This matcher will check if the element or its parent has any of the following props :
disabled
accessibilityState={{ disabled: true }}
editable={false}
(for TextInput
only)const { getByTestId } = render(
<View>
<Button disabled testID="button" title="submit" onPress={(e) => e} />
<TextInput accessibilityState={{ disabled: true }} testID="input" value="text" />
</View>,
);
expect(getByTestId('button')).toBeDisabled();
expect(getByTestId('input')).toBeDisabled();
toBeEnabled
toBeEnabled();
Check whether or not an element is enabled from a user perspective.
Works similarly to expect().not.toBeDisabled()
.
const { getByTestId } = render(
<View>
<Button testID="button" title="submit" onPress={(e) => e} />
<TextInput testID="input" value="text" />
</View>,
);
expect(getByTestId('button')).toBeEnabled();
expect(getByTestId('input')).toBeEnabled();
toBeEmptyElement
toBeEmptyElement();
Check that the given element has no content.
const { getByTestId } = render(<View testID="empty" />);
expect(getByTestId('empty')).toBeEmptyElement();
Note
This matcher has been previously namedtoBeEmpty()
, but we changed that name in order to avoid conflict with Jest Extendend matcher with the same name.
toContainElement
toContainElement(element: ReactTestInstance | null);
Check if an element contains another element as a descendant. Again, will only work for native elements.
const { queryByTestId } = render(
<View testID="grandparent">
<View testID="parent">
<View testID="child" />
</View>
<Text testID="text-element" />
</View>,
);
const grandparent = queryByTestId('grandparent');
const parent = queryByTestId('parent');
const child = queryByTestId('child');
const textElement = queryByTestId('text-element');
expect(grandparent).toContainElement(parent);
expect(grandparent).toContainElement(child);
expect(grandparent).toContainElement(textElement);
expect(parent).toContainElement(child);
expect(parent).not.toContainElement(grandparent);
toBeOnTheScreen
toBeOnTheScreen();
Check that the element is present in the element tree.
You can check that an already captured element has not been removed from the element tree.
Note
This matcher requires React Native Testing Library v10.1 or later, as it includes thescreen
object.Note
If you're using React Native Testing Library v12 or later, you need to install Jest Native v5.4.2 or later.
render(
<View>
<View testID="child" />
</View>,
);
const child = screen.getByTestId('child');
expect(child).toBeOnTheScreen();
screen.update(<View />);
expect(child).not.toBeOnTheScreen();
toHaveProp
toHaveProp(prop: string, value?: any);
Check that the element has a given prop.
You can optionally check that the attribute has a specific expected value.
const { queryByTestId } = render(
<View>
<Text allowFontScaling={false} testID="text">
text
</Text>
<Button disabled testID="button" title="ok" />
</View>,
);
expect(queryByTestId('button')).toHaveProp('accessible');
expect(queryByTestId('button')).not.toHaveProp('disabled');
expect(queryByTestId('button')).not.toHaveProp('title', 'ok');
toHaveTextContent
toHaveTextContent(text: string | RegExp, options?: { normalizeWhitespace: boolean });
Check if an element or its children have the supplied text.
This will perform a partial, case-sensitive match when a string match is provided. To perform a
case-insensitive match, you can use a RegExp
with the /i
modifier.
To enforce matching the complete text content, pass a RegExp
.
const { queryByTestId } = render(<Text testID="count-value">2</Text>);
expect(queryByTestId('count-value')).toHaveTextContent('2');
expect(queryByTestId('count-value')).toHaveTextContent(2);
expect(queryByTestId('count-value')).toHaveTextContent(/2/);
expect(queryByTestId('count-value')).not.toHaveTextContent('21');
toHaveStyle
toHaveStyle(style: object[] | object);
Check if an element has the supplied styles.
You can pass either an object of React Native style properties, or an array of objects with style properties. You cannot pass properties from a React Native stylesheet.
const styles = StyleSheet.create({ text: { fontSize: 16 } });
const { queryByText } = render(
<Text
style={[
{ color: 'black', fontWeight: '600', transform: [{ scale: 2 }, { rotate: '45deg' }] },
styles.text,
]}
>
Hello World
</Text>,
);
expect(getByText('Hello World')).toHaveStyle({ color: 'black' });
expect(getByText('Hello World')).toHaveStyle({ fontWeight: '600' });
expect(getByText('Hello World')).toHaveStyle({ fontSize: 16 });
expect(getByText('Hello World')).toHaveStyle([{ fontWeight: '600' }, { color: 'black' }]);
expect(getByText('Hello World')).toHaveStyle({ color: 'black', fontWeight: '600', fontSize: 16 });
expect(getByText('Hello World')).toHaveStyle({ transform: [{ scale: 2 }, { rotate: '45deg' }] });
expect(getByText('Hello World')).not.toHaveStyle({ color: 'white' });
expect(getByText('Hello World')).not.toHaveStyle({ transform: [{ scale: 2 }] });
expect(getByText('Hello World')).not.toHaveStyle({
transform: [{ rotate: '45deg' }, { scale: 2 }],
});
toBeVisible
toBeVisible();
Check that the given element is visible to the user.
An element is visible if all the following conditions are met:
display
set to none
.opacity
set to 0
.Modal
component or it does not have the prop visible
set to false
.isHiddenFromAccessibility
function from React Native Testing Libraryconst { getByTestId } = render(<View testID="empty-view" />);
expect(getByTestId('empty-view')).toBeVisible();
const { getByTestId } = render(<View testID="view-with-opacity" style={{ opacity: 0.2 }} />);
expect(getByTestId('view-with-opacity')).toBeVisible();
const { getByTestId } = render(<Modal testID="empty-modal" />);
expect(getByTestId('empty-modal')).toBeVisible();
const { getByTestId } = render(
<Modal>
<View>
<View testID="view-within-modal" />
</View>
</Modal>,
);
expect(getByTestId('view-within-modal')).toBeVisible();
const { getByTestId } = render(<View testID="invisible-view" style={{ opacity: 0 }} />);
expect(getByTestId('invisible-view')).not.toBeVisible();
const { getByTestId } = render(<View testID="display-none-view" style={{ display: 'none' }} />);
expect(getByTestId('display-none-view')).not.toBeVisible();
const { getByTestId } = render(
<View style={{ opacity: 0 }}>
<View>
<View testID="view-within-invisible-view" />
</View>
</View>,
);
expect(getByTestId('view-within-invisible-view')).not.toBeVisible();
const { getByTestId } = render(
<View style={{ display: 'none' }}>
<View>
<View testID="view-within-display-none-view" />
</View>
</View>,
);
expect(getByTestId('view-within-display-none-view')).not.toBeVisible();
const { getByTestId } = render(
<Modal visible={false}>
<View>
<View testID="view-within-not-visible-modal" />
</View>
</Modal>,
);
// Children elements of not visible modals are not rendered.
expect(queryByTestId('view-within-modal')).toBeNull();
const { getByTestId } = render(<Modal testID="not-visible-modal" visible={false} />);
expect(getByTestId('not-visible-modal')).not.toBeVisible();
const { getByTestId } = render(<View testID="test" accessibilityElementsHidden />);
expect(getByTestId('test')).not.toBeVisible();
const { getByTestId } = render(
<View testID="test" importantForAccessibility="no-hide-descendants" />,
);
expect(getByTestId('test')).not.toBeVisible();
toHaveAccessibilityState
toHaveAccessibilityState(state: {
disabled?: boolean;
selected?: boolean;
checked?: boolean | 'mixed';
busy?: boolean;
expanded?: boolean;
});
Check that the element has given accessibility state entries.
This check is based on accessibilityState
prop but also takes into account the default entries
which have been found by experimenting with accessibility inspector and screen readers on both iOS
and Android.
Some state entries behave as if explicit false
value is the same as not having given state entry,
so their default value is false
:
disabled
selected
busy
The remaining state entries behave as if explicit false
value is different than not having given
state entry, so their default value is undefined
:
checked
expanded
This matcher is compatible with *ByRole
and *ByA11State
queries from React Native Testing
Library.
render(<View testID="view" accessibilityState={{ expanded: true, checked: true }} />);
// Single value match
expect(screen.getByTestId('view')).toHaveAccessibilityState({ expanded: true });
expect(screen.getByTestId('view')).toHaveAccessibilityState({ checked: true });
// Can match multiple entries
expect(screen.getByTestId('view')).toHaveAccessibilityState({ expanded: true, checked: true });
Default values handling:
render(<View testID="view" />);
// Matching states where default value is `false`
expect(screen.getByTestId('view')).toHaveAccessibilityState({ disabled: false });
expect(screen.getByTestId('view')).toHaveAccessibilityState({ selected: false });
expect(screen.getByTestId('view')).toHaveAccessibilityState({ busy: false });
// Matching states where default value is `undefined`
expect(screen.getByTestId('view')).not.toHaveAccessibilityState({ checked: false });
expect(screen.getByTestId('view')).not.toHaveAccessibilityState({ expanded: false });
toHaveAccessibilityValue
toHaveAccessibilityValue(value: {
min?: number;
max?: number;
now?: number;
text?: string | RegExp;
});
Check that the element has given accessibilityValue
prop entries.
This matcher is compatible with *ByRole
and *ByA11Value
queries from React Native Testing
Library.
render(<View testID="view" accessibilityValue={{ min: 0, max: 100, now: 65 }} />);
const view = screen.getByTestId('view');
// Single value match
expect(view).toHaveAccessibilityValue({ now: 65 });
expect(view).toHaveAccessibilityValue({ max: 0 });
// Can match multiple entries
expect(view).toHaveAccessibilityValue({ min: 0, max: 100 });
expect(view).toHaveAccessibilityValue({ min: 0, max: 100, now: 65 });
// All specified entries need to match
expect(view).not.toHaveAccessibilityValue({ now: 45 });
expect(view).not.toHaveAccessibilityValue({ min: 20, max: 100, now: 65 });
render(<View testID="view" accessibilityValue={{ text: 'Almost full' }} />);
const view = screen.getByTestId('view');
expect(view).toHaveAccessibilityValue({ text: 'Almost full' });
expect(view).toHaveAccessibilityValue({ text: /full/ });
This library was made to be a companion for React Native Testing Library.
It was inspired by jest-dom, the companion library for DTL. We emulated as many of those helpers as we could while keeping in mind the guiding principles.
None known, you can add the first!
Thanks goes to these wonderful people (emoji key):
Brandon Carroll 💻 📖 🚇 ⚠️ | Santi 💻 | Marnus Weststrate 💻 | Matthieu Harlé 💻 | Alvaro Catalina 💻 | ilker Yılmaz 📖 | Donovan Hiland 💻 ⚠️ |
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
Custom jest matchers to test the state of React Native
The npm package @testing-library/jest-native receives a total of 329,920 weekly downloads. As such, @testing-library/jest-native popularity was classified as popular.
We found that @testing-library/jest-native demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
We're excited to announce that Socket now supports the Java programming language.
Security News
Socket detected a malicious Python package impersonating a popular browser cookie library to steal passwords, screenshots, webcam images, and Discord tokens.
Security News
Deno 2.0 is now available with enhanced package management, full Node.js and npm compatibility, improved performance, and support for major JavaScript frameworks.