@testing-library/jest-native
v5.4.3
Published
Custom jest matchers to test the state of React Native
Downloads
1,765,638
Readme
Table of Contents
- The problem
- This solution
- Compatibility
- Installation
- Usage
- Matchers
- Inspiration
- Other solutions
- Contributors
The problem
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.
This solution
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.
Compatibility
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.
Installation
This module should be installed as one of your project's devDependencies
:
Using yarn
yarn add --dev @testing-library/jest-native
Using 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.
Usage
Extending Jest matchers
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 });
TypeScript support
In order to setup proper TypeScript type checking use either one of the following approches.
1. Use TypeScript Jest setup file.
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.
2. Use declarations.d.ts
file
Alternatively, 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.
Matchers
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}
(forTextInput
only)
Examples
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()
.
Examples
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.
Examples
const { getByTestId } = render(<View testID="empty" />);
expect(getByTestId('empty')).toBeEmptyElement();
Note This matcher has been previously named
toBeEmpty()
, 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.
Examples
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 the
screen
object.Note If you're using React Native Testing Library v12 or later, you need to install Jest Native v5.4.2 or later.
Examples
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.
Examples
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
.
Examples
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.
Examples
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:
- it does not have its style property
display
set tonone
. - it does not have its style property
opacity
set to0
. - it is not a
Modal
component or it does not have the propvisible
set tofalse
. - it is not hidden from accessibility as checked by
isHiddenFromAccessibility
function from React Native Testing Library - its ancestor elements are also visible.
Examples
const { 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.
Examples
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.
Examples
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/ });
Inspiration
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.
Other solutions
None known, you can add the first!
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!