Queries
Query Variants
getBy*queries are shown by default in the query documentation -below.
getBy* queries
getBy* queries return the first matching node for a query, and throw an error if no elements match or if more than one match is found. If you need to find more than one element, then use getAllBy.
getAllBy* queries
getAllBy* queries return an array of all matching nodes for a query, and throw an error if no elements match.
queryBy* queries
queryBy* queries return the first matching node for a query, and return null if no elements match. This is useful for asserting an element that is not present. This throws if more than one match is found (use queryAllBy instead).
queryAllBy* queries
queryAllBy* queries return an array of all matching nodes for a query, and return an empty array ([]) when no elements match.
findBy* queries
findBy* queries return a promise which resolves when a matching element is found. The promise is rejected if no elements match or if more than one match is found after a default timeout of 1000 ms. If you need to find more than one element, then use findAllBy*.
findAllBy* queries
findAllBy* queries return a promise which resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms.
findBy* and findAllBy* queries accept optional waitForOptions object argument which can contain timeout, interval and onTimeout properies which have the same meaning as respective options for waitFor function.
In cases when your findBy* and findAllBy* queries throw when not able to find matching elements it is useful to pass onTimeout: () => { screen.debug(); } callback using waitForOptions parameter.
In order to properly use findBy* and findAllBy* queries you need at least React >=16.9.0 (featuring async act) or React Native >=0.61 (which comes with React >=16.9.0).
Query Predicates
Note: most methods like this one return a ReactTestInstance with following properties that you may be interested in:
type ReactTestInstance = {
type: string | Function;
props: { [propName: string]: any };
parent: ReactTestInstance | null;
children: Array<ReactTestInstance | string>;
};
ByRole
getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
getByRole(
role: TextMatch,
options?: {
name?: TextMatch
disabled?: boolean,
selected?: boolean,
checked?: boolean | 'mixed',
busy?: boolean,
expanded?: boolean,
value: {
min?: number;
max?: number;
now?: number;
text?: TextMatch;
},
includeHiddenElements?: boolean;
}
): ReactTestInstance;
Returns a ReactTestInstance with matching role or accessibilityRole prop.
In order for *ByRole queries to match an element it needs to be considered an accessibility element:
Text,TextInputandSwitchhost elements are these by default.Viewhost elements need an explicitaccessibleprop set totrue- Some React Native composite components like
Pressable&TouchableOpacityrender hostViewelement withaccessibleprop already set.
import { render, screen } from '@testing-library/react-native';
render(
<Pressable accessibilityRole="button" disabled>
<Text>Hello</Text>
</Pressable>
);
const element = screen.getByRole('button');
const element2 = screen.getByRole('button', { name: 'Hello' });
const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
Options
name: Finds an element with given role/accessibilityRole and an accessible name (equivalent to byText or byLabelText query).
disabled: You can filter elements by their disabled state (coming either from aria-disabled prop or accessbilityState.disabled prop). The possible values are true or false. Querying disabled: false will also match elements with disabled: undefined (see the wiki for more details). See React Native's accessibilityState docs to learn more about the disabled state.
selected: You can filter elements by their selected state (coming either from aria-selected prop or accessbilityState.selected prop). The possible values are true or false. Querying selected: false will also match elements with selected: undefined (see the wiki for more details). See React Native's accessibilityState docs to learn more about the selected state.
checked: You can filter elements by their checked state (coming either from aria-checked prop or accessbilityState.checked prop). The possible values are true, false, or "mixed". See React Native's accessibilityState docs to learn more about the checked state.
busy: You can filter elements by their busy state (coming either from aria-busy prop or accessbilityState.busy prop). The possible values are true or false. Querying busy: false will also match elements with busy: undefined (see the wiki for more details). See React Native's accessibilityState docs to learn more about the busy state.
expanded: You can filter elements by their expanded state (coming either from aria-expanded prop or accessbilityState.expanded prop). The possible values are true or false. See React Native's accessibilityState docs to learn more about the expanded state.
value: Filter elements by their accessibility value, based on either aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext or accessibilityValue props. Accessiblity value conceptually consists of numeric min, max and now entries, as well as string text entry. See React Native accessibilityValue docs to learn more about the accessibility value concept.
ByText
getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText
getByText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
}
): ReactTestInstance;
Returns a ReactTestInstance with matching text – may be a string or regular expression.
This method will join <Text> siblings to find matches, similarly to how React Native handles these components. This will allow for querying for strings that will be visually rendered together, but may be semantically separate React components.
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByText('banana');
ByPlaceholderText
getByPlaceholderText, getAllByPlaceholderText, queryByPlaceholderText, queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText
getByPlaceholderText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
}
): ReactTestInstance;
Returns a ReactTestInstance for a TextInput with a matching placeholder – may be a string or regular expression.
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByPlaceholderText('username');
ByDisplayValue
getByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue
getByDisplayValue(
value: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a ReactTestInstance for a TextInput with a matching display value – may be a string or regular expression.
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByDisplayValue('username');
ByTestId
getByTestId, getAllByTestId, queryByTestId, queryAllByTestId, findByTestId, findAllByTestId
getByTestId(
testId: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a ReactTestInstance with matching testID prop. testID – may be a string or a regular expression.
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByTestId('unique-id');
In the spirit of the guiding principles, it is recommended to use this only after the other queries don't work for your use case. Using testID attributes do not resemble how your software is used and should be avoided if possible. However, they are particularly useful for end-to-end testing on real devices, e.g. using Detox and it's an encouraged technique to use there. Learn more from the blog post "Making your UI tests resilient to change".
ByLabelText
getByLabelText, getAllByLabelText, queryByLabelText, queryAllByLabelText, findByLabelText, findAllByLabelText
getByLabelText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a ReactTestInstance with matching label:
- either by matching
aria-label/accessibilityLabelprop - or by matching text content of view referenced by
aria-labelledby/accessibilityLabelledByprop
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByLabelText('my-label');
ByHintText, ByA11yHint, ByAccessibilityHint
getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint +
+- - +getByHintText, getAllByHintText, queryByHintText, queryAllByHintText, findByHintText, findAllByHintTextQueries
Query Variants
getBy*queries are shown by default in the query documentation +below.
getBy*queries
getBy*queries return the first matching node for a query, and throw an error if no elements match or if more than one match is found. If you need to find more than one element, then usegetAllBy.
getAllBy*queries
getAllBy*queries return an array of all matching nodes for a query, and throw an error if no elements match.
queryBy*queries
queryBy*queries return the first matching node for a query, and returnnullif no elements match. This is useful for asserting an element that is not present. This throws if more than one match is found (usequeryAllByinstead).
queryAllBy*queries
queryAllBy*queries return an array of all matching nodes for a query, and return an empty array ([]) when no elements match.
findBy*queries
findBy*queries return a promise which resolves when a matching element is found. The promise is rejected if no elements match or if more than one match is found after a default timeout of 1000 ms. If you need to find more than one element, then usefindAllBy*.
findAllBy*queries
findAllBy*queries return a promise which resolves to an array of matching elements. The promise is rejected if no elements match after a default timeout of 1000 ms.info
findBy*andfindAllBy*queries accept optionalwaitForOptionsobject argument which can containtimeout,intervalandonTimeoutproperies which have the same meaning as respective options forwaitForfunction.infoIn cases when your
findBy*andfindAllBy*queries throw when not able to find matching elements it is useful to passonTimeout: () => { screen.debug(); }callback usingwaitForOptionsparameter.infoIn order to properly use
findBy*andfindAllBy*queries you need at least React >=16.9.0 (featuring asyncact) or React Native >=0.61 (which comes with React >=16.9.0).Query Predicates
Note: most methods like this one return a
ReactTestInstancewith following properties that you may be interested in:type ReactTestInstance = {
type: string | Function;
props: { [propName: string]: any };
parent: ReactTestInstance | null;
children: Array<ReactTestInstance | string>;
};
ByRolegetByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
getByRole(
role: TextMatch,
options?: {
name?: TextMatch
disabled?: boolean,
selected?: boolean,
checked?: boolean | 'mixed',
busy?: boolean,
expanded?: boolean,
value: {
min?: number;
max?: number;
now?: number;
text?: TextMatch;
},
includeHiddenElements?: boolean;
}
): ReactTestInstance;Returns a
ReactTestInstancewith matchingroleoraccessibilityRoleprop.infoIn order for
*ByRolequeries to match an element it needs to be considered an accessibility element:
Text,TextInputandSwitchhost elements are these by default.Viewhost elements need an explicitaccessibleprop set totrue- Some React Native composite components like
Pressable&TouchableOpacityrender hostViewelement withaccessibleprop already set.import { render, screen } from '@testing-library/react-native';
render(
<Pressable accessibilityRole="button" disabled>
<Text>Hello</Text>
</Pressable>
);
const element = screen.getByRole('button');
const element2 = screen.getByRole('button', { name: 'Hello' });
const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });Options
name: Finds an element with givenrole/accessibilityRoleand an accessible name (equivalent tobyTextorbyLabelTextquery).
disabled: You can filter elements by their disabled state (coming either fromaria-disabledprop oraccessbilityState.disabledprop). The possible values aretrueorfalse. Queryingdisabled: falsewill also match elements withdisabled: undefined(see the wiki for more details). See React Native's accessibilityState docs to learn more about thedisabledstate.
selected: You can filter elements by their selected state (coming either fromaria-selectedprop oraccessbilityState.selectedprop). The possible values aretrueorfalse. Queryingselected: falsewill also match elements withselected: undefined(see the wiki for more details). See React Native's accessibilityState docs to learn more about theselectedstate.
checked: You can filter elements by their checked state (coming either fromaria-checkedprop oraccessbilityState.checkedprop). The possible values aretrue,false, or"mixed". See React Native's accessibilityState docs to learn more about thecheckedstate.
busy: You can filter elements by their busy state (coming either fromaria-busyprop oraccessbilityState.busyprop). The possible values aretrueorfalse. Queryingbusy: falsewill also match elements withbusy: undefined(see the wiki for more details). See React Native's accessibilityState docs to learn more about thebusystate.
expanded: You can filter elements by their expanded state (coming either fromaria-expandedprop oraccessbilityState.expandedprop). The possible values aretrueorfalse. See React Native's accessibilityState docs to learn more about theexpandedstate.
value: Filter elements by their accessibility value, based on eitheraria-valuemin,aria-valuemax,aria-valuenow,aria-valuetextoraccessibilityValueprops. Accessiblity value conceptually consists of numericmin,maxandnowentries, as well as stringtextentry. See React Native accessibilityValue docs to learn more about the accessibility value concept.
ByTextgetByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText
getByText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
}
): ReactTestInstance;Returns a
ReactTestInstancewith matching text – may be a string or regular expression.This method will join
<Text>siblings to find matches, similarly to how React Native handles these components. This will allow for querying for strings that will be visually rendered together, but may be semantically separate React components.import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByText('banana');
ByPlaceholderTextgetByPlaceholderText, getAllByPlaceholderText, queryByPlaceholderText, queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText
getByPlaceholderText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
}
): ReactTestInstance;Returns a
ReactTestInstancefor aTextInputwith a matching placeholder – may be a string or regular expression.import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByPlaceholderText('username');
ByDisplayValuegetByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue
getByDisplayValue(
value: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a
ReactTestInstancefor aTextInputwith a matching display value – may be a string or regular expression.import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByDisplayValue('username');
ByTestIdgetByTestId, getAllByTestId, queryByTestId, queryAllByTestId, findByTestId, findAllByTestId
getByTestId(
testId: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a
ReactTestInstancewith matchingtestIDprop.testID– may be a string or a regular expression.import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByTestId('unique-id');infoIn the spirit of the guiding principles, it is recommended to use this only after the other queries don't work for your use case. Using
testIDattributes do not resemble how your software is used and should be avoided if possible. However, they are particularly useful for end-to-end testing on real devices, e.g. using Detox and it's an encouraged technique to use there. Learn more from the blog post "Making your UI tests resilient to change".
ByLabelTextgetByLabelText, getAllByLabelText, queryByLabelText, queryAllByLabelText, findByLabelText, findAllByLabelText
getByLabelText(
text: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a
ReactTestInstancewith matching label:
- either by matching
aria-label/accessibilityLabelprop- or by matching text content of view referenced by
aria-labelledby/accessibilityLabelledBypropimport { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByLabelText('my-label');
ByHintText,ByA11yHint,ByAccessibilityHintgetByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint, findByAccessibilityHint, findAllByAccessibilityHint -getByHintText, getAllByHintText, queryByHintText, queryAllByHintText, findByHintText, findAllByHintText
getByHintText(
hint: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a
ReactTestInstancewith matchingaccessibilityHintprop.import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByHintText('Plays a song');infoPlease consult Apple guidelines on how
accessibilityHintshould be used.
ByA11yState,ByAccessibilityState(deprecated)cautionThis query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
*ByRolequery with relevant state options:disabled,selected,checked,expandedandbusytoHaveAccessibilityState()Jest matcher to check the state of element found using some other querygetByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState, findByA11yState, findAllByA11yState -getByAccessibilityState, getAllByAccessibilityState, queryByAccessibilityState, queryAllByAccessibilityState, findByAccessibilityState, findAllByAccessibilityState
getByA11yState(
state: {
disabled?: boolean,
selected?: boolean,
checked?: boolean | 'mixed',
busy?: boolean,
expanded?: boolean,
},
options?: {
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a
ReactTestInstancewith matchingaccessibilityStateprop or ARIA state props:aria-disabled,aria-selected,aria-checked,aria-busy, andaria-expanded.import { render, screen } from '@testing-library/react-native';
render(<Component />);
const element = screen.getByA11yState({ disabled: true });noteDefault state for:
disabled,selected, andbusykeysPassing
falsematcher value will match both elements with explicitfalsestate value and without explicit state value.For instance,
getByA11yState({ disabled: false })will match elements with following props:
accessibilityState={{ disabled: false, ... }}- no
disabledkey underaccessibilityStateprop, e.g.accessibilityState={{}}- no
accessibilityStateprop at allDefault state for:
checkedandexpandedkeysPassing
falsematcher value will only match elements with explicitfalsestate value.For instance,
getByA11yState({ checked: false })will only match elements with:
accessibilityState={{ checked: false, ... }}but will not match elements with following props:
- no
checkedkey underaccessibilityStateprop, e.g.accessibilityState={{}}- no
accessibilityStateprop at allThe difference in handling default values is made to reflect observed accessibility behaviour on iOS and Android platforms.
ByA11yValue,ByAccessibilityValue(deprecated)cautionThis query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
toHaveAccessibilityValue()Jest matcher to check the state of element found using some other query*ByRolequery withvalueoptiongetByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue, findByA11yValue, findAllByA11yValue -getByAccessibilityValue, getAllByAccessibilityValue, queryByAccessibilityValue, queryAllByAccessibilityValue, findByAccessibilityValue, findAllByAccessibilityValue
getByA11yValue(
value: {
min?: number;
max?: number;
now?: number;
text?: TextMatch;
},
options?: {
includeHiddenElements?: boolean;
},
): ReactTestInstance;Returns a host element with matching accessibility value based on
aria-valuemin,aria-valuemax,aria-valuenow,aria-valuetext&accessibilityValueprops. Only value entires provided to the query will be used to match elements. Element might have additional accessibility value entries and still be matched.When querying by
textentry a string or regex might be used.import { render, screen } from '@testing-library/react-native';
render(
<View accessibilityValue={{ min: 0, max: 100, now: 25, text: '25%' }} />
);
const element = screen.getByA11yValue({ now: 25 });
const element2 = screen.getByA11yValue({ text: /25/ });Common options
Usually query first argument can be a string or a regex. All queries take at least the
hiddenoption as an optionnal second argument and some queries accept more options which change string matching behaviour. See TextMatch for more info.
includeHiddenElementsoptionAll queries have the
includeHiddenElementsoption which affects whether elements hidden from accessibility are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements.You can configure the default value with the
configurefunction.This option is also available as
hiddenalias for compatibility with React Testing Library.Examples
render(<Text style={{ display: 'none' }}>Hidden from accessibility</Text>);
// Exclude hidden elements
expect(
screen.queryByText('Hidden from accessibility', { includeHiddenElements: false })
).not.toBeOnTheScreen();
// Include hidden elements
expect(screen.getByText('Hidden from accessibility')).toBeOnTheScreen();
expect(
screen.getByText('Hidden from accessibility', { includeHiddenElements: true })
).toBeOnTheScreen();TextMatch type
type TextMatch = string | RegExp;Most of the query APIs take a
TextMatchas an argument, which means the argument can be either a string or regex.Examples
Given the following render:
render(<Text>Hello World</Text>);Will find a match:
// Matching a string:
screen.getByText('Hello World'); // full string match
screen.getByText('llo Worl', { exact: false }); // substring match
screen.getByText('hello world', { exact: false }); // ignore case-sensitivity
// Matching a regex:
screen.getByText(/World/); // substring match
screen.getByText(/world/i); // substring match, ignore case
screen.getByText(/^hello world$/i); // full string match, ignore case-sensitivity
screen.getByText(/Hello W?oRlD/i); // advanced regexWill NOT find a match
// substring does not match
screen.getByText('llo Worl');
// full string does not match
screen.getByText('Goodbye World');
// case-sensitive regex with different case
screen.getByText(/hello world/);Options
Precision
type TextMatchOptions = {
exact?: boolean;
normalizer?: (text: string) => string;
};Queries that take a
TextMatchalso accept an object as the second argument that can contain options that affect the precision of string matching:
exact: Defaults totrue; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive.
exacthas no effect on regex argument.- In most cases using a
regexinstead of a string gives you more control over fuzzy matching and should be preferred over{ exact: false }.normalizer: An optional function which overrides normalization behavior. See Normalization.
exactoption defaults totruebut if you want to search for a text slice or make text matching case-insensitive you can override it. That being said we advise you to use regex in more complex scenarios.Normalization
Before running any matching logic against text, it is automatically normalized. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.
If you want to prevent that normalization, or provide alternative normalization (e.g. to remove Unicode control characters), you can provide a
normalizerfunction in the options object. This function will be given a string and is expected to return a normalized version of that string.infoSpecifying a value for
normalizerreplaces the built-in normalization, but you can callgetDefaultNormalizerto obtain a built-in normalizer, either to adjust that normalization or to call it from your own normalizer.
getDefaultNormalizertake options object which allows the selection of behaviour:
trim: Defaults totrue. Trims leading and trailing whitespace.collapseWhitespace: Defaults totrue. Collapses inner whitespace (newlines, tabs repeated spaces) into a single space.Normalization Examples
To perform a match against text without trimming:
screen.getByText(node, 'text', {
normalizer: getDefaultNormalizer({ trim: false }),
});To override normalization to remove some Unicode characters whilst keeping some (but not all) of the built-in normalization behavior:
screen.getByText(node, 'text', {
normalizer: (str) =>
getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
});Legacy unit testing helpers
Use sparingly and responsibly, escape hatches here
renderfrom@testing-library/react-nativeexposes additional queries that should not be used in component integration testing, but some users (like component library creators) interested in unit testing some components may find helpful.Queries helpful in unit testing
The interface is the same as for other queries, but we won't provide full names so that they're harder to find by search engines.
UNSAFE_ByTypeUNSAFE_getByType, UNSAFE_getAllByType, UNSAFE_queryByType, UNSAFE_queryAllByType
Returns a
ReactTestInstancewith matching a React component type.cautionThis query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.
UNSAFE_ByPropsUNSAFE_getByProps, UNSAFE_getAllByProps, UNSAFE_queryByProps, UNSAFE_queryAllByProps
Returns a
ReactTestInstancewith matching props object.cautionThis query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.
getByHintText(
hint: TextMatch,
options?: {
exact?: boolean;
normalizer?: (text: string) => string;
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a ReactTestInstance with matching accessibilityHint prop.
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByHintText('Plays a song');
Please consult Apple guidelines on how accessibilityHint should be used.
ByA11yState, ByAccessibilityState (deprecated)
This query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
*ByRolequery with relevant state options:disabled,selected,checked,expandedandbusytoHaveAccessibilityState()Jest matcher to check the state of element found using some other query
getByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState, findByA11yState, findAllByA11yState +getByAccessibilityState, getAllByAccessibilityState, queryByAccessibilityState, queryAllByAccessibilityState, findByAccessibilityState, findAllByAccessibilityState
getByA11yState(
state: {
disabled?: boolean,
selected?: boolean,
checked?: boolean | 'mixed',
busy?: boolean,
expanded?: boolean,
},
options?: {
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a ReactTestInstance with matching accessibilityState prop or ARIA state props: aria-disabled, aria-selected, aria-checked, aria-busy, and aria-expanded.
import { render, screen } from '@testing-library/react-native';
render(<Component />);
const element = screen.getByA11yState({ disabled: true });
Default state for: disabled, selected, and busy keys
Passing false matcher value will match both elements with explicit false state value and without explicit state value.
For instance, getByA11yState({ disabled: false }) will match elements with following props:
accessibilityState={{ disabled: false, ... }}- no
disabledkey underaccessibilityStateprop, e.g.accessibilityState={{}} - no
accessibilityStateprop at all
Default state for: checked and expanded keys
Passing false matcher value will only match elements with explicit false state value.
For instance, getByA11yState({ checked: false }) will only match elements with:
accessibilityState={{ checked: false, ... }}
but will not match elements with following props:
- no
checkedkey underaccessibilityStateprop, e.g.accessibilityState={{}} - no
accessibilityStateprop at all
The difference in handling default values is made to reflect observed accessibility behaviour on iOS and Android platforms.
ByA11yValue, ByAccessibilityValue (deprecated)
This query has been marked deprecated, as is typically too general to give meaningful results. Therefore, it's better to use one of following options:
toHaveAccessibilityValue()Jest matcher to check the state of element found using some other query*ByRolequery withvalueoption
getByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue, findByA11yValue, findAllByA11yValue +getByAccessibilityValue, getAllByAccessibilityValue, queryByAccessibilityValue, queryAllByAccessibilityValue, findByAccessibilityValue, findAllByAccessibilityValue
getByA11yValue(
value: {
min?: number;
max?: number;
now?: number;
text?: TextMatch;
},
options?: {
includeHiddenElements?: boolean;
},
): ReactTestInstance;
Returns a host element with matching accessibility value based on aria-valuemin, aria-valuemax, aria-valuenow, aria-valuetext & accessibilityValue props. Only value entires provided to the query will be used to match elements. Element might have additional accessibility value entries and still be matched.
When querying by text entry a string or regex might be used.
import { render, screen } from '@testing-library/react-native';
render(
<View accessibilityValue={{ min: 0, max: 100, now: 25, text: '25%' }} />
);
const element = screen.getByA11yValue({ now: 25 });
const element2 = screen.getByA11yValue({ text: /25/ });
Common options
Usually query first argument can be a string or a regex. All queries take at least the hidden option as an optionnal second argument and some queries accept more options which change string matching behaviour. See TextMatch for more info.
includeHiddenElements option
All queries have the includeHiddenElements option which affects whether elements hidden from accessibility are matched by the query. By default queries will not match hidden elements, because the users of the app would not be able to see such elements.
You can configure the default value with the configure function.
This option is also available as hidden alias for compatibility with React Testing Library.
Examples
render(<Text style={{ display: 'none' }}>Hidden from accessibility</Text>);
// Exclude hidden elements
expect(
screen.queryByText('Hidden from accessibility', { includeHiddenElements: false })
).not.toBeOnTheScreen();
// Include hidden elements
expect(screen.getByText('Hidden from accessibility')).toBeOnTheScreen();
expect(
screen.getByText('Hidden from accessibility', { includeHiddenElements: true })
).toBeOnTheScreen();
TextMatch type
type TextMatch = string | RegExp;
Most of the query APIs take a TextMatch as an argument, which means the argument can be either a string or regex.
Examples
Given the following render:
render(<Text>Hello World</Text>);
Will find a match:
// Matching a string:
screen.getByText('Hello World'); // full string match
screen.getByText('llo Worl', { exact: false }); // substring match
screen.getByText('hello world', { exact: false }); // ignore case-sensitivity
// Matching a regex:
screen.getByText(/World/); // substring match
screen.getByText(/world/i); // substring match, ignore case
screen.getByText(/^hello world$/i); // full string match, ignore case-sensitivity
screen.getByText(/Hello W?oRlD/i); // advanced regex
Will NOT find a match
// substring does not match
screen.getByText('llo Worl');
// full string does not match
screen.getByText('Goodbye World');
// case-sensitive regex with different case
screen.getByText(/hello world/);
Options
Precision
type TextMatchOptions = {
exact?: boolean;
normalizer?: (text: string) => string;
};
Queries that take a TextMatch also accept an object as the second argument that can contain options that affect the precision of string matching:
exact: Defaults totrue; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive.exacthas no effect on regex argument.- In most cases using a
regexinstead of a string gives you more control over fuzzy matching and should be preferred over{ exact: false }.
normalizer: An optional function which overrides normalization behavior. See Normalization.
exact option defaults to true but if you want to search for a text slice or make text matching case-insensitive you can override it. That being said we advise you to use regex in more complex scenarios.
Normalization
Before running any matching logic against text, it is automatically normalized. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.
If you want to prevent that normalization, or provide alternative normalization (e.g. to remove Unicode control characters), you can provide a normalizer function in the options object. This function will be given a string and is expected to return a normalized version of that string.
Specifying a value for normalizer replaces the built-in normalization, but you can call getDefaultNormalizer to obtain a built-in normalizer, either to adjust that normalization or to call it from your own normalizer.
getDefaultNormalizer take options object which allows the selection of behaviour:
trim: Defaults totrue. Trims leading and trailing whitespace.collapseWhitespace: Defaults totrue. Collapses inner whitespace (newlines, tabs repeated spaces) into a single space.
Normalization Examples
To perform a match against text without trimming:
screen.getByText(node, 'text', {
normalizer: getDefaultNormalizer({ trim: false }),
});
To override normalization to remove some Unicode characters whilst keeping some (but not all) of the built-in normalization behavior:
screen.getByText(node, 'text', {
normalizer: (str) =>
getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
});
Legacy unit testing helpers
Use sparingly and responsibly, escape hatches here
render from @testing-library/react-native exposes additional queries that should not be used in component integration testing, but some users (like component library creators) interested in unit testing some components may find helpful.
Queries helpful in unit testing
The interface is the same as for other queries, but we won't provide full names so that they're harder to find by search engines.
UNSAFE_ByType
UNSAFE_getByType, UNSAFE_getAllByType, UNSAFE_queryByType, UNSAFE_queryAllByType
Returns a ReactTestInstance with matching a React component type.
This query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.
UNSAFE_ByProps
UNSAFE_getByProps, UNSAFE_getAllByProps, UNSAFE_queryByProps, UNSAFE_queryAllByProps
Returns a ReactTestInstance with matching props object.
This query has been marked unsafe, since it requires knowledge about implementation details of the component. Use responsibly.