feat: predicate query

src/queries/__tests__/predicate.test.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { View, Text, TextInput, Button } from 'react-native';
+import { ReactTestInstance } from 'react-test-renderer';
+import { render } from '../..';
+
+test('getByPredicate returns only native elements', () => {
+  const testIdPredicate = (testID: string) => (element: ReactTestInstance) => {
+    return element.props.testID === testID;
+  };
+
+  const textInputPredicate = function matchTextInput(
+    element: ReactTestInstance
+  ) {
+    // @ts-expect-error - ReatTestInstance type is missing host element typing
+    return element.type === 'TextInput';
+  };
+
+  const { getByPredicate, getAllByPredicate } = render(
+    <View>
+      <Text testID="text">Text</Text>
+      <TextInput testID="textInput" />
+      <View testID="view" />
+      <Button testID="button" title="Button" onPress={jest.fn()} />
+    </View>
+  );
+
+  expect(getByPredicate(testIdPredicate('text'))).toBeTruthy();
+  expect(getByPredicate(testIdPredicate('textInput'))).toBeTruthy();
+  expect(getByPredicate(testIdPredicate('view'))).toBeTruthy();
+  expect(getByPredicate(testIdPredicate('button'))).toBeTruthy();
+
+  expect(getAllByPredicate(testIdPredicate('text'))).toHaveLength(1);
+  expect(getAllByPredicate(testIdPredicate('textInput'))).toHaveLength(1);
+  expect(getAllByPredicate(testIdPredicate('view'))).toHaveLength(1);
+  expect(getAllByPredicate(testIdPredicate('button'))).toHaveLength(1);
+
+  expect(getByPredicate(textInputPredicate)).toBeTruthy();
+});
+
+test('getByPredicate error messages', () => {
+  function hasStylePredicate(element: ReactTestInstance) {
+    return element.props.style !== undefined;
+  }
+
+  const textInputPredicate = function textInputPredicate(
+    element: ReactTestInstance
+  ) {
+    // @ts-expect-error - ReatTestInstance type is missing host element typing
+    return element.type === 'TextInput';
+  };
+
+  const testIdPredicate = (testID: string) => (element: ReactTestInstance) => {
+    return element.props.testID === testID;
+  };
+
+  const { getByPredicate, getAllByPredicate } = render(
+    <View>
+      <Text testID="text">Text</Text>
+    </View>
+  );
+
+  expect(() => getByPredicate(hasStylePredicate))
+    .toThrowErrorMatchingInlineSnapshot(`
+    "Unable to find an element matching predicate: function hasStylePredicate(element) {
+        return element.props.style !== undefined;
+      }"
+  `);
+
+  expect(() => getByPredicate(textInputPredicate))
+    .toThrowErrorMatchingInlineSnapshot(`
+    "Unable to find an element matching predicate: function textInputPredicate(element) {
+        // @ts-expect-error - ReatTestInstance type is missing host element typing
+        return element.type === 'TextInput';
+      }"
+  `);
+
+  expect(() => getByPredicate(testIdPredicate('myComponent')))
+    .toThrowErrorMatchingInlineSnapshot(`
+    "Unable to find an element matching predicate: element => {
+        return element.props.testID === testID;
+      }"
+  `);
+  expect(() => getAllByPredicate(testIdPredicate('myComponent')))
+    .toThrowErrorMatchingInlineSnapshot(`
+    "Unable to find an element matching predicate: element => {
+        return element.props.testID === testID;
+      }"
+  `);
+});

src/queries/predicate.ts

@@ -0,0 +1,63 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { isHostElement } from '../helpers/component-tree';
+import { findAll } from '../helpers/findAll';
+import { makeQueries } from './makeQueries';
+import type {
+  FindAllByQuery,
+  FindByQuery,
+  GetAllByQuery,
+  GetByQuery,
+  QueryAllByQuery,
+  QueryByQuery,
+} from './makeQueries';
+import { CommonQueryOptions } from './options';
+
+type PredicateFn = (instance: ReactTestInstance) => boolean;
+type ByPredicateQueryOptions = CommonQueryOptions;
+
+function queryAllByPredicate(instance: ReactTestInstance) {
+  return function queryAllByPredicateFn(
+    predicate: PredicateFn,
+    options?: ByPredicateQueryOptions
+  ): Array<ReactTestInstance> {
+    const results = findAll(
+      instance,
+      (node) => isHostElement(node) && predicate(node),
+      options
+    );
+
+    return results;
+  };
+}
+
+const getMultipleError = (predicate: PredicateFn) =>
+  `Found multiple elements matching predicate: ${predicate}`;
+
+const getMissingError = (predicate: PredicateFn) =>
+  `Unable to find an element matching predicate: ${predicate}`;
+
+const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
+  queryAllByPredicate,
+  getMissingError,
+  getMultipleError
+);
+
+export type ByTestIdQueries = {
+  getByPredicate: GetByQuery<PredicateFn, ByPredicateQueryOptions>;
+  getAllByPredicate: GetAllByQuery<PredicateFn, ByPredicateQueryOptions>;
+  queryByPredicate: QueryByQuery<PredicateFn, ByPredicateQueryOptions>;
+  queryAllByPredicate: QueryAllByQuery<PredicateFn, ByPredicateQueryOptions>;
+  findByPredicate: FindByQuery<PredicateFn, ByPredicateQueryOptions>;
+  findAllByPredicate: FindAllByQuery<PredicateFn, ByPredicateQueryOptions>;
+};
+
+export const bindByPredicateQueries = (
+  instance: ReactTestInstance
+): ByTestIdQueries => ({
+  getByPredicate: getBy(instance),
+  getAllByPredicate: getAllBy(instance),
+  queryByPredicate: queryBy(instance),
+  queryAllByPredicate: queryAllBy(instance),
+  findByPredicate: findBy(instance),
+  findAllByPredicate: findAllBy(instance),
+});

src/screen.ts

@@ -107,6 +107,12 @@ const defaultScreen: RenderResult = {
   queryAllByText: notImplemented,
   findByText: notImplemented,
   findAllByText: notImplemented,
+  getByPredicate: notImplemented,
+  getAllByPredicate: notImplemented,
+  queryByPredicate: notImplemented,
+  queryAllByPredicate: notImplemented,
+  findByPredicate: notImplemented,
+  findAllByPredicate: notImplemented,
 };
 
 export let screen: RenderResult = defaultScreen;

src/within.ts

@@ -10,6 +10,7 @@ import { bindByA11yStateQueries } from './queries/a11yState';
 import { bindByA11yValueQueries } from './queries/a11yValue';
 import { bindUnsafeByTypeQueries } from './queries/unsafeType';
 import { bindUnsafeByPropsQueries } from './queries/unsafeProps';
+import { bindByPredicateQueries } from './queries/predicate';
 
 export function within(instance: ReactTestInstance) {
   return {
@@ -22,6 +23,7 @@ export function within(instance: ReactTestInstance) {
     ...bindByRoleQueries(instance),
     ...bindByA11yStateQueries(instance),
     ...bindByA11yValueQueries(instance),
+    ...bindByPredicateQueries(instance),
     ...bindUnsafeByTypeQueries(instance),
     ...bindUnsafeByPropsQueries(instance),
   };

typings/index.flow.js

@@ -389,6 +389,38 @@ interface A11yAPI {
   ) => FindAllReturn;
 }
 
+type PredicateFn = (node: ReactTestInstance) => boolean;
+type ByPredicateOptions = CommonQueryOptions;
+
+interface ByPredicateQueries {
+  getByPredicate: (
+    predicate: PredicateFn,
+    options?: ByPredicateOptions
+  ) => ReactTestInstance;
+  getAllByPredicate: (
+    predicate: PredicateFn,
+    options?: ByPredicateOptions
+  ) => Array<ReactTestInstance>;
+  queryByPredicate: (
+    predicate: PredicateFn,
+    options?: ByPredicateOptions
+  ) => ReactTestInstance | null;
+  queryAllByPredicate: (
+    predicate: PredicateFn,
+    options?: ByPredicateOptions
+  ) => Array<ReactTestInstance> | [];
+  findByPredicate: (
+    predicate: PredicateFn,
+    queryOptions?: ByPredicateOptions,
+    waitForOptions?: WaitForOptions
+  ) => FindReturn;
+  findAllByPredicate: (
+    predicate: PredicateFn,
+    queryOptions?: ByPredicateOptions,
+    waitForOptions?: WaitForOptions
+  ) => FindAllReturn;
+}
+
 interface Thenable {
   then: (resolve: () => any, reject?: () => any) => any;
 }
@@ -412,6 +444,7 @@ type Queries = ByTextQueries &
   ByTestIdQueries &
   ByDisplayValueQueries &
   ByPlaceholderTextQueries &
+  ByPredicateQueries &
   UnsafeByTypeQueries &
   UnsafeByPropsQueries &
   A11yAPI;

website/docs/Queries.md

@@ -26,6 +26,7 @@ title: Queries
     - [Default state for: `disabled`, `selected`, and `busy` keys](#default-state-for-disabled-selected-and-busy-keys)
     - [Default state for: `checked` and `expanded` keys](#default-state-for-checked-and-expanded-keys)
   - [`ByA11Value`, `ByAccessibilityValue`](#bya11value-byaccessibilityvalue)
+  - [`ByPredicate`](#bypredicate)
 - [Common options](#common-options)
   - [`includeHiddenElements` option](#includehiddenelements-option)
 - [TextMatch](#textmatch)
@@ -391,6 +392,23 @@ const element = screen.getByA11yValue({ now: 25 });
 const element2 = screen.getByA11yValue({ text: /25/ });
 ```
 
+### `ByPredicate`
+
+> getByPredicate, getAllByPredicate, queryByPredicate, queryAllByPredicate, findByPredicate, findAllByPredicate
+
+```ts
+getByPredicate(
+  predicate: (element: ReactTestInstance) => boolean,
+  options?: {
+    includeHiddenElements?: boolean;
+  }
+): ReactTestInstance;
+```
+
+Returns a host element matching a custom `predicate` function.
+
+This query type is an escape hatch and should be used with care. In most cases you using the standard queries like `getByRole` or `getByText` will lead to test more-resembling user perspective. Use this query with care in rare cases where more flexibility is needed.
+
 ## Common options
 
 ### `includeHiddenElements` option