Skip to content

Commit fd08a4c

Browse files
mdjastrzebskimdjastrzebski
authored
chore: update docs (#1448)
1 parent 20c5e44 commit fd08a4c

File tree

1 file changed

+64
-59
lines changed

1 file changed

+64
-59
lines changed

‎website/docs/Queries.md

Lines changed: 64 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -14,25 +14,21 @@ title: Queries
1414
- [findAllBy](#findallby)
1515
- [Queries](#queries)
1616
- [Options](#options)
17+
- [`ByRole`](#byrole)
1718
- [`ByText`](#bytext)
1819
- [`ByPlaceholderText`](#byplaceholdertext)
1920
- [`ByDisplayValue`](#bydisplayvalue)
2021
- [`ByTestId`](#bytestid)
2122
- [`ByLabelText`](#bylabeltext)
2223
- [`ByHintText`, `ByA11yHint`, `ByAccessibilityHint`](#byhinttext-bya11yhint-byaccessibilityhint)
23-
- [`ByRole`](#byrole)
24-
- [Options](#options-1)
2524
- [`ByA11yState`, `ByAccessibilityState` (deprecated)](#bya11ystate-byaccessibilitystate-deprecated)
26-
- [Default state for: `disabled`, `selected`, and `busy` keys](#default-state-for-disabled-selected-and-busy-keys)
27-
- [Default state for: `checked` and `expanded` keys](#default-state-for-checked-and-expanded-keys)
2825
- [`ByA11yValue`, `ByAccessibilityValue` (deprecated)](#bya11yvalue-byaccessibilityvalue-deprecated)
2926
- [Common options](#common-options)
3027
- [`includeHiddenElements` option](#includehiddenelements-option)
3128
- [TextMatch](#textmatch)
3229
- [Examples](#examples)
3330
- [Precision](#precision)
3431
- [Normalization](#normalization)
35-
- [Normalization Examples](#normalization-examples)
3632
- [Unit testing helpers](#unit-testing-helpers)
3733
- [`UNSAFE_ByType`](#unsafe_bytype)
3834
- [`UNSAFE_ByProps`](#unsafe_byprops)
@@ -95,6 +91,69 @@ type ReactTestInstance = {
9591

9692
Usually query first argument can be a **string** or a **regex**. All queries take at least the [`hidden`](#hidden-option) option as an optionnal second argument and some queries accept more options which change string matching behaviour. See [TextMatch](#textmatch) for more info.
9793

94+
### `ByRole`
95+
96+
> getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
97+
98+
```ts
99+
getByRole(
100+
role: TextMatch,
101+
options?: {
102+
name?: TextMatch
103+
disabled?: boolean,
104+
selected?: boolean,
105+
checked?: boolean | 'mixed',
106+
busy?: boolean,
107+
expanded?: boolean,
108+
value: {
109+
min?: number;
110+
max?: number;
111+
now?: number;
112+
text?: TextMatch;
113+
},
114+
includeHiddenElements?: boolean;
115+
}
116+
): ReactTestInstance;
117+
```
118+
119+
Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
120+
121+
:::info
122+
In order for `*ByRole` queries to match an element it needs to be considered an accessibility element:
123+
1. `Text`, `TextInput` and `Switch` host elements are these by default.
124+
2. `View` host elements need an explicit [`accessible`](https://reactnative.dev/docs/accessibility#accessible) prop set to `true`
125+
3. Some React Native composite components like `Pressable` & `TouchableOpacity` render host `View` element with `accessible` prop already set.
126+
:::
127+
128+
```jsx
129+
import { render, screen } from '@testing-library/react-native';
130+
131+
render(
132+
<Pressable accessibilityRole="button" disabled>
133+
<Text>Hello</Text>
134+
</Pressable>
135+
);
136+
const element = screen.getByRole('button');
137+
const element2 = screen.getByRole('button', { name: 'Hello' });
138+
const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
139+
```
140+
141+
#### Options
142+
143+
`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
144+
145+
`disabled`: You can filter elements by their disabled state. The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.
146+
147+
`selected`: You can filter elements by their selected state. The possible values are `true` or `false`. Querying `selected: false` will also match elements with `selected: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `selected` state.
148+
149+
`checked`: You can filter elements by their checked state. The possible values are `true`, `false`, or `"mixed"`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `checked` state.
150+
151+
`busy`: You can filter elements by their busy state. The possible values are `true` or `false`. Querying `busy: false` will also match elements with `busy: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `busy` state.
152+
153+
`expanded`: You can filter elements by their expanded state. The possible values are `true` or `false`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `expanded` state.
154+
155+
`value`: Filter elements by their accessibility, available value entries include numeric `min`, `max` & `now`, as well as string or regex `text` key. See React Native [accessibilityValue](https://reactnative.dev/docs/accessibility#accessibilityvalue) docs to learn more about this prop.
156+
98157
### `ByText`
99158

100159
> getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText
@@ -253,61 +312,7 @@ const element = screen.getByHintText('Plays a song');
253312
Please consult [Apple guidelines on how `accessibilityHint` should be used](https://developer.apple.com/documentation/objectivec/nsobject/1615093-accessibilityhint).
254313
:::
255314

256-
### `ByRole`
257-
258-
> getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole
259-
260-
```ts
261-
getByRole(
262-
role: TextMatch,
263-
options?: {
264-
name?: TextMatch
265-
disabled?: boolean,
266-
selected?: boolean,
267-
checked?: boolean | 'mixed',
268-
busy?: boolean,
269-
expanded?: boolean,
270-
value: {
271-
min?: number;
272-
max?: number;
273-
now?: number;
274-
text?: TextMatch;
275-
},
276-
includeHiddenElements?: boolean;
277-
}
278-
): ReactTestInstance;
279-
```
280-
281-
Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
282315

283-
```jsx
284-
import { render, screen } from '@testing-library/react-native';
285-
286-
render(
287-
<Pressable accessibilityRole="button" disabled>
288-
<Text>Hello</Text>
289-
</Pressable>
290-
);
291-
const element = screen.getByRole('button');
292-
const element2 = screen.getByRole('button', { name: 'Hello' });
293-
const element3 = screen.getByRole('button', { name: 'Hello', disabled: true });
294-
```
295-
296-
#### Options
297-
298-
`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
299-
300-
`disabled`: You can filter elements by their disabled state. The possible values are `true` or `false`. Querying `disabled: false` will also match elements with `disabled: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `disabled` state.
301-
302-
`selected`: You can filter elements by their selected state. The possible values are `true` or `false`. Querying `selected: false` will also match elements with `selected: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `selected` state.
303-
304-
`checked`: You can filter elements by their checked state. The possible values are `true`, `false`, or `"mixed"`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `checked` state.
305-
306-
`busy`: You can filter elements by their busy state. The possible values are `true` or `false`. Querying `busy: false` will also match elements with `busy: undefined` (see the [wiki](https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State) for more details). See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `busy` state.
307-
308-
`expanded`: You can filter elements by their expanded state. The possible values are `true` or `false`. See [React Native's accessibilityState](https://reactnative.dev/docs/accessibility#accessibilitystate) docs to learn more about the `expanded` state.
309-
310-
`value`: Filter elements by their accessibility, available value entries include numeric `min`, `max` & `now`, as well as string or regex `text` key. See React Native [accessibilityValue](https://reactnative.dev/docs/accessibility#accessibilityvalue) docs to learn more about this prop.
311316

312317
### `ByA11yState`, `ByAccessibilityState` (deprecated)
313318

0 commit comments

Comments
 (0)