;
+
+interface GetByAPI {
getByName: (name: React.ReactType | string) => ReactTestInstance;
getByType: (type: React.ComponentType
) => ReactTestInstance;
getByText: (text: string | RegExp) => ReactTestInstance;
@@ -28,7 +35,7 @@ export interface GetByAPI {
UNSAFE_getAllByProps: (props: Record) => Array,
}
-export interface QueryByAPI {
+interface QueryByAPI {
queryByName: (name: React.ReactType | string) => ReactTestInstance | null;
queryByType: (type: React.ComponentType
) => ReactTestInstance | null;
queryByText: (name: string | RegExp) => ReactTestInstance | null;
@@ -63,10 +70,42 @@ export interface QueryByAPI {
UNSAFE_queryAllByProps: (props: Record) => Array | [],
}
-type GetReturn = ReactTestInstance;
-type GetAllReturn = Array;
-type QueryReturn = ReactTestInstance | null;
-type QueryAllReturn = Array | [];
+export interface WaitForOptions {
+ timeout: number;
+ interval: number;
+}
+
+interface FindByAPI {
+ findByText: (
+ text: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findByPlaceholder: (
+ placeholder: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findByDisplayValue: (
+ value: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findByTestId: (testID: string, waitForOptions?: WaitForOptions) => FindReturn;
+ findAllByText: (
+ text: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
+ findAllByPlaceholder: (
+ placeholder: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
+ findAllByDisplayValue: (
+ value: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
+ findAllByTestId: (
+ testID: string,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
+}
// Not yet available in DefinitelyTyped
export type A11yValue = {
@@ -82,18 +121,42 @@ type A11yAPI = {
getAllByA11yLabel: (matcher: string | RegExp) => GetAllReturn,
queryByA11yLabel: (matcher: string | RegExp) => QueryReturn,
queryAllByA11yLabel: (matcher: string | RegExp) => QueryAllReturn,
+ findByA11yLabel: (
+ matcher: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findAllByA11yLabel: (
+ matcher: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
// Hint
getByA11yHint: (matcher: string | RegExp) => GetReturn,
getAllByA11yHint: (matcher: string | RegExp) => GetAllReturn,
queryByA11yHint: (matcher: string | RegExp) => QueryReturn,
queryAllByA11yHint: (matcher: string | RegExp) => QueryAllReturn,
+ findByA11yHint: (
+ matcher: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findAllByA11yHint: (
+ matcher: string | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
// Role
getByA11yRole: (matcher: AccessibilityRole | RegExp) => GetReturn,
getAllByA11yRole: (matcher: AccessibilityRole | RegExp) => GetAllReturn,
queryByA11yRole: (matcher: AccessibilityRole | RegExp) => QueryReturn,
queryAllByA11yRole: (matcher: AccessibilityRole | RegExp) => QueryAllReturn,
+ findByA11yRole: (
+ matcher: AccessibilityRole | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findAllByA11yRole: (
+ matcher: AccessibilityRole | RegExp,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
// States
getByA11yStates: (matcher: AccessibilityStates | Array) => GetReturn,
@@ -106,12 +169,28 @@ type A11yAPI = {
getAllByA11yState: (matcher: AccessibilityState) => GetAllReturn,
queryByA11yState: (matcher: AccessibilityState) => QueryReturn,
queryAllByA11yState: (matcher: AccessibilityState) => QueryAllReturn,
+ findByA11yState: (
+ matcher: AccessibilityState,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findAllByA11yState: (
+ matcher: AccessibilityState,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
// Value
getByA11yValue: (matcher: A11yValue) => GetReturn,
getAllByA11yValue: (matcher: A11yValue) => GetAllReturn,
queryByA11yValue: (matcher: A11yValue) => QueryReturn,
queryAllByA11yValue: (matcher: A11yValue) => QueryAllReturn,
+ findByA11yValue: (
+ matcher: A11yValue,
+ waitForOptions?: WaitForOptions
+ ) => FindReturn;
+ findAllByA11yValue: (
+ matcher: A11yValue,
+ waitForOptions?: WaitForOptions
+ ) => FindAllReturn;
};
export interface Thenable {
@@ -123,7 +202,7 @@ export interface RenderOptions {
createNodeMock?: (element: React.ReactElement) => any;
}
-type Queries = GetByAPI & QueryByAPI & A11yAPI;
+type Queries = GetByAPI & QueryByAPI & FindByAPI & A11yAPI;
export interface RenderAPI extends Queries {
update(nextElement: React.ReactElement): void;
diff --git a/website/docs/API.md b/website/docs/API.md
index f3037d779..62176f09b 100644
--- a/website/docs/API.md
+++ b/website/docs/API.md
@@ -351,7 +351,7 @@ Defined as:
function within(instance: ReactTestInstance): Queries
```
-Perform [queries](./Queries.md) scoped to given element.
+Perform [queries](./Queries.md) scoped to given element.
:::note
Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included.
@@ -361,13 +361,14 @@ Please note that additional `render` specific operations like `update`, `unmount
const detailsScreen = within(getByA11yHint('Details Screen'));
expect(detailsScreen.getByText('Some Text')).toBeTruthy();
expect(detailsScreen.getByDisplayValue('Some Value')).toBeTruthy();
-expect(detailsScreen.getByA11yLabel('Some Label')).toBeTruthy();
-expect(detailsScreen.getByA11yHint('Some Label')).toBeTruthy();
+expect(detailsScreen.queryByA11yLabel('Some Label')).toBeTruthy();
+await expect(detailsScreen.findByA11yHint('Some Label')).resolves.toBeTruthy();
```
Use cases for scoped queries include:
-* queries scoped to a single item inside a FlatList containing many items
-* queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation)
+
+- queries scoped to a single item inside a FlatList containing many items
+- queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation)
## `debug`
diff --git a/website/docs/Queries.md b/website/docs/Queries.md
index 461e975b1..ab1465f1a 100644
--- a/website/docs/Queries.md
+++ b/website/docs/Queries.md
@@ -24,6 +24,19 @@ title: Queries
`queryAllBy*` queries return an array of all matching nodes for a query, and return an empty array (`[]`) if no elements match.
+### findBy
+
+`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 4500ms. If you need to find more than one element, then use `findAllBy`.
+
+### findAllBy
+
+`findAllBy` queries return a promise which resolves to an array when any matching elements are found. The promise is rejected if no elements match after a default timeout of 4500ms.
+
+
+:::info
+`findBy` and `findAllBy` queries accept optional `waitForOptions` object argument which can contain `timeout` and `interval` properies which have the same meaning as respective arguments to [`waitForElement`](https://callstack.github.io/react-native-testing-library/docs/api#waitforelement) function.
+:::
+
## Queries
_Note: most methods like this one return a [`ReactTestInstance`](https://reactjs.org/docs/test-renderer.html#testinstance) with following properties that you may be interested in:_
@@ -39,7 +52,7 @@ type ReactTestInstance = {
### `ByText`
-> getByText, getAllByText, queryByText, queryAllByText
+> getByText, getAllByText, queryByText, queryAllByText, findByText, findAllByText
Returns a `ReactTestInstance` with matching text – may be a string or regular expression.
@@ -54,7 +67,7 @@ const element = getByText('banana');
### `ByPlaceholder`
-> getByPlaceholder, getAllByPlaceholder, queryByPlaceholder, queryAllByPlaceholder
+> getByPlaceholder, getAllByPlaceholder, queryByPlaceholder, queryAllByPlaceholder, findByPlaceholder, findAllByPlaceholder
Returns a `ReactTestInstance` for a `TextInput` with a matching placeholder – may be a string or regular expression.
@@ -67,7 +80,7 @@ const element = getByPlaceholder('username');
### `ByDisplayValue`
-> getByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue
+> getByDisplayValue, getAllByDisplayValue, queryByDisplayValue, queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue
Returns a `ReactTestInstance` for a `TextInput` with a matching display value – may be a string or regular expression.
@@ -80,7 +93,7 @@ const element = getByDisplayValue('username');
### `ByTestId`
-> getByTestId, getAllByTestId, queryByTestId, queryAllByTestId
+> getByTestId, getAllByTestId, queryByTestId, queryAllByTestId, findByTestId, findAllByTestId
Returns a `ReactTestInstance` with matching `testID` prop.
@@ -101,8 +114,8 @@ Current implementation of `getByTestId` and `queryByTestId` has a serious flaw,
### `ByA11yLabel`, `ByAccessibilityLabel`
-> getByA11yLabel, getAllByA11yLabel, queryByA11yLabel, queryAllByA11yLabel
-> getByAccessibilityLabel, getAllByAccessibilityLabel, queryByAccessibilityLabel, queryAllByAccessibilityLabel
+> getByA11yLabel, getAllByA11yLabel, queryByA11yLabel, queryAllByA11yLabel, findByA11yLabel, findAllByA11yLabel
+> getByAccessibilityLabel, getAllByAccessibilityLabel, queryByAccessibilityLabel, queryAllByAccessibilityLabel, findByAccessibilityLabel, findAllByAccessibilityLabel
Returns a `ReactTestInstance` with matching `accessibilityLabel` prop.
@@ -115,8 +128,8 @@ const element = getByA11yLabel('my-label');
### `ByA11yHint`, `ByAccessibilityHint`
-> getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint
-> getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint
+> getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint
+> getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint, findByAccessibilityHint, findAllByAccessibilityHint
Returns a `ReactTestInstance` with matching `accessibilityHint` prop.
@@ -144,8 +157,8 @@ const element2 = getByA11yStates('checked');
### `ByA11yRole`, `ByAccessibilityRole`
-> getByA11yRole, getAllByA11yRole, queryByA11yRole, queryAllByA11yRole
-> getByAccessibilityRole, getAllByAccessibilityRole, queryByAccessibilityRole, queryAllByAccessibilityRole
+> getByA11yRole, getAllByA11yRole, queryByA11yRole, queryAllByA11yRole, findByA11yRole, findAllByA11yRole
+> getByAccessibilityRole, getAllByAccessibilityRole, queryByAccessibilityRole, queryAllByAccessibilityRole, findByAccessibilityRole, findAllByAccessibilityRole
Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
@@ -158,8 +171,8 @@ const element = getByA11yRole('button');
### `ByA11yState`, `ByAccessibilityState`
-> getByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState
-> getByAccessibilityState, getAllByAccessibilityState, queryByAccessibilityState, queryAllByAccessibilityState
+> getByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState, findByA11yState, findAllByA11yState
+> getByAccessibilityState, getAllByAccessibilityState, queryByAccessibilityState, queryAllByAccessibilityState, findByAccessibilityState, findAllByAccessibilityState
Returns a `ReactTestInstance` with matching `accessibilityState` prop.
@@ -172,8 +185,8 @@ const element = getByA11yState({ disabled: true });
### `ByA11Value`, `ByAccessibilityValue`
-> getByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue
-> getByAccessibilityValue, getAllByAccessibilityValue, queryByAccessibilityValue, queryAllByAccessibilityValue
+> getByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue, findByA11yValue, findAllByA11yValue
+> getByAccessibilityValue, getAllByAccessibilityValue, queryByAccessibilityValue, queryAllByAccessibilityValue, findByAccessibilityValue, findAllByAccessibilityValue
Returns a `ReactTestInstance` with matching `accessibilityValue` prop.