Queries
Queries are one of the main building blocks for the React Native Testing Library. They enable you to find relevant elements in the element tree, which represents the your application's user interface when running under tests.
Accessing queries
All queries described below are accessible in two main ways: through the screen
object or by capturing the render
function call result.
Using screen
object
import { render, screen } from '@testing-library/react-native';
test('accessing queries using "screen" object', () => {
render(...);
screen.getByRole("button", { name: "Start" });
})
The modern and recommended way of accessing queries is to use the screen
object exported by the @testing-library/react-native
package. This object will contain methods of all available queries bound to the most recently rendered UI.
Using render
result
import { render } from '@testing-library/react-native';
test('accessing queries using "render" result', () => {
const { getByRole } = render(...);
getByRole("button", { name: "Start" });
})
The classic way is to capture query functions, as they are returned from the render
function call. This provides access to the same functions as in the case of the screen
object.
Query parts
Each query is composed of two parts: variant and predicate, which are separated by the by
word in the middle of the name.
Consider the following query:
getByRole()
For this query, getBy*
is the query variant, and *ByRole
is the predicate.
Query variant
The query variants describe the expected number (and timing) of matching elements, so they differ in their return type.
Variant | Assertion | Return type | Is Async? |
---|---|---|---|
getBy* | Exactly one matching element | ReactTestInstance | No |
getAllBy* | At least one matching element | Array<ReactTestInstance> | No |
queryBy* | Zero or one matching element | ReactTestInstance | null | No |
queryAllBy* | No assertion | Array<ReactTestInstance> | No |
findBy* | Exactly one matching element | Promise<ReactTestInstance> | Yes |
findAllBy* | At least one matching element | Promise<Array<ReactTestInstance>> | Yes |
Queries work as implicit assertions on the number of matching elements and will throw an error when the assertion fails.
getBy*
queries
getByX(...): ReactTestInstance
getBy*
queries return the single matching element 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
getAllByX(...): ReactTestInstance[]
getAllBy*
queries return an array of all matching elements for a query and throw an error if no elements match.
queryBy*
queries
queryByX(...): ReactTestInstance | null
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
queryAllByX(...): ReactTestInstance[]
queryAllBy*
queries return an array of all matching nodes for a query and return an empty array ([]
) when no elements match.
findBy*
queries
findByX(
...,
waitForOptions?: {
timeout?: number,
interval?: number,
},
): Promise<ReactTestInstance>
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 use findAllBy*
queries.
findAllBy*
queries
findAllByX(
...,
waitForOptions?: {
timeout?: number,
interval?: number,
},
): Promise<ReactTestInstance[]>
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 arguments, which can contain timeout
, interval
and onTimeout
properties which have the same meaning as respective options for waitFor
function.
In cases when your findBy*
and findAllBy*
queries throw when unable to find matching elements, it is helpful to pass onTimeout: () => { screen.debug(); }
callback using the waitForOptions
parameter.
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
,TextInput
andSwitch
host elements are these by default.View
host elements need an explicitaccessible
prop set totrue
- Some React Native composite components like
Pressable
&TouchableOpacity
render hostView
element withaccessible
prop 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
/accessibilityRole
and an accessible name (= accessability label or text content). -
disabled
: You can filter elements by their disabled state (coming either fromaria-disabled
prop oraccessbilityState.disabled
prop). The possible values aretrue
orfalse
. Queryingdisabled: false
will also match elements withdisabled: undefined
(see the wiki for more details).- See React Native's accessibilityState docs to learn more about the
disabled
state. - This option can alternatively be expressed using the
toBeEnabled()
/toBeDisabled()
Jest matchers.
- See React Native's accessibilityState docs to learn more about the
-
selected
: You can filter elements by their selected state (coming either fromaria-selected
prop oraccessbilityState.selected
prop). The possible values aretrue
orfalse
. Queryingselected: false
will also match elements withselected: undefined
(see the wiki for more details).- See React Native's accessibilityState docs to learn more about the
selected
state. - This option can alternatively be expressed using the
toBeSelected()
Jest matcher.
- See React Native's accessibilityState docs to learn more about the
-
checked
: You can filter elements by their checked state (coming either fromaria-checked
prop oraccessbilityState.checked
prop). The possible values aretrue
,false
, or"mixed"
.- See React Native's accessibilityState docs to learn more about the
checked
state. - This option can alternatively be expressed using the
toBeChecked()
/toBePartiallyChecked()
Jest matchers.
- See React Native's accessibilityState docs to learn more about the
-
busy
: You can filter elements by their busy state (coming either fromaria-busy
prop oraccessbilityState.busy
prop). The possible values aretrue
orfalse
. Queryingbusy: false
will also match elements withbusy: undefined
(see the wiki for more details).- See React Native's accessibilityState docs to learn more about the
busy
state. - This option can alternatively be expressed using the
toBeBusy()
Jest matcher.
- See React Native's accessibilityState docs to learn more about the
-
expanded
: You can filter elements by their expanded state (coming either fromaria-expanded
prop oraccessbilityState.expanded
prop). The possible values aretrue
orfalse
.- See React Native's accessibilityState docs to learn more about the
expanded
state. - This option can alternatively be expressed using the
toBeExpanded()
/toBeCollapsed()
Jest matchers.
- See React Native's accessibilityState docs to learn more about the
-
value
: Filter elements by their accessibility value, based on eitheraria-valuemin
,aria-valuemax
,aria-valuenow
,aria-valuetext
oraccessibilityValue
props. Accessiblity value conceptually consists of numericmin
,max
andnow
entries, as well as stringtext
entry.- See React Native accessibilityValue docs to learn more about the accessibility value concept.
- This option can alternatively be expressed using the
toHaveAccessibilityValue()
Jest matcher.
*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
/accessibilityLabel
prop - or by matching text content of view referenced by
aria-labelledby
/accessibilityLabelledBy
prop
import { render, screen } from '@testing-library/react-native';
render(<MyComponent />);
const element = screen.getByLabelText('my-label');
*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');
*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');
*ByHintText
getByA11yHint, 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 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.
*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".
*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:
*ByRole
query with relevant state options:disabled
,selected
,checked
,expanded
andbusy
- use built-in Jest matchers to check the state of element found using some other query:
- enabled state:
toBeEnabled()
/toBeDisabled()
- checked state:
toBeChecked()
/toBePartiallyChecked()
- selected state:
toBeSelected()
- expanded state:
toBeExpanded()
/toBeCollapsed()
- busy state:
toBeBusy()
- enabled state:
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
disabled
key underaccessibilityState
prop, e.g.accessibilityState={{}}
- no
accessibilityState
prop 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
checked
key underaccessibilityState
prop, e.g.accessibilityState={{}}
- no
accessibilityState
prop 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*ByRole
query withvalue
option
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.exact
has no effect on regex argument.- In most cases using a
regex
instead 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
render
from @testing-library/react-native
exposes additional queries that should not be used in integration or component testing, but some users (like component library creators) interested in unit testing some components may find helpful.
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.