Skip to content
This repository was archived by the owner on Aug 1, 2020. It is now read-only.

Commit f123bf7

Browse files
committed
docs: revise query API
1 parent e364ba5 commit f123bf7

File tree

2 files changed

+56
-101
lines changed

2 files changed

+56
-101
lines changed

docs/api-helpers.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ const inputNode = <TextInput value="words" />;
8585
getNodeText(inputNode); // "words"
8686
```
8787

88-
## `within` and ``getQueriesForElement` APIs
88+
## `within` and `getQueriesForElement` APIs
8989

9090
`within` (an alias to `getQueriesForElement`) takes a `ReactTestRendererInstance` and binds it to
9191
the raw query functions, allowing them to be used without manually specifying a container.

docs/api-queries.md

Lines changed: 55 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -78,22 +78,22 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query.
7878

7979
## Queries
8080

81-
### `ByA11yHint`
81+
### `ByHintText`
8282

83-
> getByA11yHint, queryByA11yHint, getAllByA11yHint, queryAllByA11yHint, findByA11yHint,
84-
> findAllByA11yHint
83+
> getByHintText, queryByHintText, getAllByHintText, queryAllByHintText, findByHintText,
84+
> findAllByHintText
8585
8686
```typescript
87-
getByA11yHint(
88-
container: ReactTestRendererInstance,
87+
getByHintText(
88+
testRenderer: ReactTestRendererInstance,
8989
match: TextMatch,
9090
options?: {
9191
exact?: boolean = true,
9292
trim?: boolean = true,
9393
collapseWhitespace?: boolean = true,
94-
filter?: FilterFn,
94+
selector?: SelectorFn,
9595
normalizer?: NormalizerFn,
96-
}): FiberRoot
96+
}): NativeTestInstance
9797
```
9898

9999
This will search for all elements with an `accessibilityHint` prop and find one that matches the
@@ -102,27 +102,27 @@ given [`TextMatch`](#textmatch).
102102
```js
103103
import { render } from 'react-testing-library';
104104

105-
const { getByA11yHint } = render(<View accessibilityHint="summary" />);
105+
const { getByHintText } = render(<View accessibilityHint="summary" />);
106106

107-
getByA11yHint('summary'); // returns the View node
107+
getByHintText('summary'); // returns the View node
108108
```
109109

110-
### `ByA11yLabel`
110+
### `ByLabelText`
111111

112-
> getByA11yLabel, queryByLabelText, getAllByLabelText, queryAllByLabelText findByLabelText,
112+
> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText findByLabelText,
113113
> findAllByLabelText
114114
115115
```typescript
116-
getByA11yLabel(
117-
container: ReactTestRendererInstance,
116+
getByLabelText(
117+
testRenderer: ReactTestRendererInstance,
118118
match: TextMatch,
119119
options?: {
120120
exact?: boolean = true,
121121
trim?: boolean = true,
122122
collapseWhitespace?: boolean = true,
123-
filter?: FilterFn,
123+
selector?: SelectorFn,
124124
normalizer?: NormalizerFn,
125-
}): FiberRoot
125+
}): NativeTestInstance
126126
```
127127

128128
This will search for all elements with an `accessibilityLabel` prop and find one that matches the
@@ -142,27 +142,22 @@ function Login({ onPress }) {
142142

143143
import { render } from 'native-testing-library';
144144

145-
const { getByA11yLabel } = render(<Login onPress={jest.fn()} />);
145+
const { getByLabelText } = render(<Login onPress={jest.fn()} />);
146146

147-
getByA11yLabel('username'); // returns the TextInput node
147+
getByLabelText('username'); // returns the TextInput node
148148
```
149149

150-
### `ByA11yRole`
150+
### `ByRole`
151151

152-
> getByA11yRole, queryByA11yRole, getAllByA11yRole, queryAllByA11yRole, findByA11yRole,
153-
> findAllByA11yRole
152+
> getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole, findAllByRole
154153
155154
```typescript
156-
getByA11yRole(
157-
container: ReactTestRendererInstance,
155+
getByRole(
156+
testRenderer: ReactTestRendererInstance,
158157
match: TextMatch,
159158
options?: {
160-
exact?: boolean = true,
161-
trim?: boolean = true,
162-
collapseWhitespace?: boolean = true,
163-
filter?: FilterFn,
164-
normalizer?: NormalizerFn,
165-
}): FiberRoot
159+
selector?: SelectorFn,
160+
}): NativeTestInstance
166161
```
167162

168163
This will search for all elements with an `accessibilityRole` prop and find one that matches the
@@ -171,73 +166,30 @@ given [`TextMatch`](#textmatch).
171166
```js
172167
import { render } from 'react-testing-library';
173168

174-
const { getByA11yRole } = render(<View accessibilityRole="summary" />);
175-
176-
getByA11yRole('summary'); // returns the View node
177-
```
178-
179-
### `ByA11yStates`
180-
181-
> getByA11yStates, queryByA11yStates, getAllByA11yStates, queryAllByA11yStates, findByA11yStates,
182-
> findAllByA11yStates
183-
184-
```typescript
185-
getByA11yStates(
186-
container: ReactTestRendererInstance,
187-
match: Array<string>
188-
): FiberRoot
189-
```
190-
191-
This will search for all elements with an `accessibilityStates` prop and find one that matches the
192-
given `Array`.
193-
194-
```js
195-
import { render } from 'react-testing-library';
196-
197-
const { getByA11yStates } = render(<View accessibilityStates={['disabled']} />);
198-
199-
getByA11yStates(['disabled']); // returns the View node
200-
```
201-
202-
### `ByA11yTraits`
203-
204-
> getByA11yTraits, queryByA11yTraits, getAllByA11yTraits, queryAllByA11yTraits, findByA11yTraits,
205-
> findAllByA11yTraits
169+
const { getByRole } = render(<View accessibilityRole="summary" />);
206170

207-
```typescript
208-
getByA11yTraits(
209-
container: ReactTestRendererInstance,
210-
match: Array<string>,
211-
): FiberRoot
171+
getByRole('summary'); // returns the View node
212172
```
213173

214-
This will search for all elements with an `accessibilityTraits` prop and find one that matches the
215-
given `Array`.
174+
> `ByRole` queries will fall back to searching for elements with an `accessibilityTraits` match, but
175+
> they will log a warning on all matches that this prop is being deprecated by react-native.
216176
217-
```js
218-
import { render } from 'react-testing-library';
219-
220-
const { getByA11yTraits } = render(<View accessibilityTraits={['button']} />);
221-
222-
getByA11yTraits(['button']); // returns the View node
223-
```
177+
### `ByPlaceholderText`
224178

225-
### `ByPlaceholder`
226-
227-
> getByPlaceholder, queryByPlaceholder, getAllByPlaceholder, queryAllByPlaceholder,
228-
> findByPlaceholder, findAllByPlaceholder
179+
> getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText, queryAllByPlaceholderText,
180+
> findByPlaceholderText, findAllByPlaceholderText
229181
230182
```typescript
231-
getByPlaceholder(
232-
container: ReactTestRendererInstance,
183+
getByPlaceholderText(
184+
testRenderer: ReactTestRendererInstance,
233185
match: TextMatch,
234186
options?: {
235187
exact?: boolean = true,
236188
trim?: boolean = true,
237189
collapseWhitespace?: boolean = true,
238-
filter?: FilterFn,
190+
selector?: SelectorFn,
239191
normalizer?: NormalizerFn,
240-
}): FiberRoot
192+
}): NativeTestInstance
241193
```
242194

243195
This will search for all elements with a `placeholder` prop and find one that matches the given
@@ -246,9 +198,9 @@ This will search for all elements with a `placeholder` prop and find one that ma
246198
```javascript
247199
import { render } from 'native-testing-library';
248200

249-
const { getByPlaceholder } = render(<TextInput placeholder="Username" />);
201+
const { getByPlaceholderText } = render(<TextInput placeholder="Username" />);
250202

251-
getByPlaceholder('Username'); // returns the TextInput node
203+
getByPlaceholderText('Username'); // returns the TextInput node
252204
```
253205

254206
### `ByText`
@@ -257,18 +209,20 @@ getByPlaceholder('Username'); // returns the TextInput node
257209
258210
```typescript
259211
getByText(
260-
container: ReactTestRendererInstance,
212+
testRenderer: ReactTestRendererInstance,
261213
match: TextMatch,
262214
options?: {
215+
exact?: boolean = true,
263216
trim?: boolean = true,
264217
collapseWhitespace?: boolean = true,
265-
exact?: boolean = true,
218+
selector?: SelectorFn,
266219
normalizer?: NormalizerFn,
267-
}): FiberRoot
220+
}): NativeTestInstance
268221
```
269222

270223
This will search for all elements of type `Text` with `props.children` matching the given. It will
271-
also search `TextInput` elements by their value [`TextMatch`](#textmatch).
224+
also search `TextInput` elements by their value and `Button` elements by their `title`
225+
[`TextMatch`](#textmatch).
272226

273227
```js
274228
import { render } from 'native-testing-library';
@@ -284,18 +238,19 @@ getByText(/about/i); // returns the Text node
284238
285239
```typescript
286240
getByTitle(
287-
container: ReactTestRendererInstance,
241+
testRenderer: ReactTestRendererInstance,
288242
match: TextMatch,
289243
options?: {
244+
exact?: boolean = true,
290245
trim?: boolean = true,
291246
collapseWhitespace?: boolean = true,
292-
exact?: boolean = true,
247+
selector?: SelectorFn,
293248
normalizer?: NormalizerFn,
294-
}): FiberRoot
249+
}): NativeTestInstance
295250
```
296251

297-
This will search for all elements with `props.title` matching the given by their value
298-
[`TextMatch`](#textmatch).
252+
This will search for all `Button` or `RefreshControl` elements with `props.title` matching the given
253+
by their value [`TextMatch`](#textmatch).
299254

300255
```js
301256
import { render } from 'native-testing-library';
@@ -311,19 +266,19 @@ getByTitle(/about/i); // returns the Button node
311266
312267
```typescript
313268
getByValue(
314-
container: ReactTestRendererInstance,
269+
testRenderer: ReactTestRendererInstance,
315270
match: TextMatch,
316271
options?: {
317272
exact?: boolean = true,
318273
trim?: boolean = true,
319274
collapseWhitespace?: boolean = true,
320-
filter?: FilterFn,
275+
selector?: SelectorFn,
321276
normalizer?: NormalizerFn,
322277
}): NormalizerOptions
323278
```
324279

325-
This will search for all elements with a `value` prop and find one that matches the given
326-
[`TextMatch`](#textmatch).
280+
This will search for all `TextInput` elements with a `value` prop or `Picker` elements with a
281+
`selectedValue` prop and find ones that matches the given [`TextMatch`](#textmatch).
327282

328283
```js
329284
import { render } from 'native-testing-library';
@@ -339,15 +294,15 @@ getByValue(/about/i); // returns the Input node
339294
340295
```typescript
341296
getByTestId(
342-
container: ReactTestRendererInstance,
297+
testRenderer: ReactTestRendererInstance,
343298
match: TextMatch,
344299
options?: {
345300
trim?: boolean = true,
346301
collapseWhitespace?: boolean = true,
347302
exact?: boolean = true,
348-
filter?: FilterFn,
303+
selector?: SelectorFn,
349304
normalizer?: NormalizerFn,
350-
}): FiberRoot
305+
}): NativeTestInstance
351306
```
352307

353308
This will search for all elements with a `testID` and find one that matches the given

0 commit comments

Comments
 (0)