feat: ...byRole type queries accepts second arg

src/__tests__/a11yAPI.test.js

@@ -7,6 +7,8 @@ const BUTTON_LABEL = 'cool button';
 const BUTTON_HINT = 'click this button';
 const TEXT_LABEL = 'cool text';
 const TEXT_HINT = 'static text';
+const SINGLE_OCCURANCE = 'more words';
+const TWO_OCCURANCE = 'cooler text';
 // Little hack to make all the methods happy with type
 const NO_MATCHES_TEXT: any = 'not-existent-element';
 const FOUND_TWO_INSTANCES = 'Expected 1 but found 2 instances';
@@ -70,6 +72,22 @@ function Section() {
   );
 }
 
+function ButtonsWithText() {
+  return (
+    <>
+      <TouchableOpacity accessibilityRole="button">
+        <Text>{TWO_OCCURANCE}</Text>
+      </TouchableOpacity>
+      <TouchableOpacity accessibilityRole="button">
+        <Text>{TWO_OCCURANCE}</Text>
+      </TouchableOpacity>
+      <TouchableOpacity accessibilityRole="button">
+        <Text>{SINGLE_OCCURANCE}</Text>
+      </TouchableOpacity>
+    </>
+  );
+}
+
 test('getByA11yLabel, queryByA11yLabel, findByA11yLabel', async () => {
   const { getByA11yLabel, queryByA11yLabel, findByA11yLabel } = render(
     <Section />
@@ -192,6 +210,34 @@ test('getByA11yRole, queryByA11yRole, findByA11yRole', async () => {
   await expect(findByA11yRole('link')).rejects.toThrow(FOUND_TWO_INSTANCES);
 });
 
+test('getByA11yRole, queryByA11yRole, findByA11yRole with name', async () => {
+  const { getByA11yRole, queryByA11yRole, findByA11yRole } = render(
+    <ButtonsWithText />
+  );
+
+  expect(() => getByA11yRole(/button/g, { name: TWO_OCCURANCE })).toThrow(
+    FOUND_TWO_INSTANCES
+  );
+  getByA11yRole(/button/g, { name: SINGLE_OCCURANCE });
+
+  expect(queryByA11yRole(/button/g, { name: NO_MATCHES_TEXT })).toBeNull();
+  expect(() => queryByA11yRole(/button/g, { name: TWO_OCCURANCE })).toThrow(
+    FOUND_TWO_INSTANCES
+  );
+
+  await findByA11yRole('button', {
+    name: SINGLE_OCCURANCE,
+  });
+  await expect(
+    findByA11yRole('button', { ...waitForOptions, name: NO_MATCHES_TEXT })
+  ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole', 'button'));
+  await expect(
+    findByA11yRole('button', {
+      name: TWO_OCCURANCE,
+    })
+  ).rejects.toThrow(FOUND_TWO_INSTANCES);
+});
+
 test('getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole', async () => {
   const { getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole } = render(
     <Section />
@@ -211,6 +257,8 @@ test('getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole', async () => {
   ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole'));
 });
 
+test.todo('getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole with name');
+
 // TODO: accessibilityStates was removed from RN 0.62
 test.skip('getByA11yStates, queryByA11yStates', () => {
   const { getByA11yStates, queryByA11yStates } = render(<Section />);

src/helpers/a11yAPI.js

@@ -10,6 +10,15 @@ type QueryAllReturn = Array<ReactTestInstance>;
 type FindReturn = Promise<GetReturn>;
 type FindAllReturn = Promise<GetAllReturn>;
 
+type QueryOptions = {
+  name: string | RegExp,
+};
+
+export type WaitForOptionsWithName = {
+  ...WaitForOptions,
+  ...$Exact<QueryOptions>,
+};
+
 export type A11yAPI = {|
   // Label
   getByA11yLabel: (string | RegExp) => GetReturn,
@@ -40,18 +49,18 @@ export type A11yAPI = {|
   findAllByHintText: (string | RegExp, ?WaitForOptions) => FindAllReturn,
 
   // Role
-  getByA11yRole: (A11yRole | RegExp) => GetReturn,
-  getByRole: (A11yRole | RegExp) => GetReturn,
-  getAllByA11yRole: (A11yRole | RegExp) => GetAllReturn,
-  getAllByRole: (A11yRole | RegExp) => GetAllReturn,
-  queryByA11yRole: (A11yRole | RegExp) => QueryReturn,
-  queryByRole: (A11yRole | RegExp) => QueryReturn,
-  queryAllByA11yRole: (A11yRole | RegExp) => QueryAllReturn,
-  queryAllByRole: (A11yRole | RegExp) => QueryAllReturn,
-  findByA11yRole: (A11yRole, ?WaitForOptions) => FindReturn,
-  findByRole: (A11yRole, ?WaitForOptions) => FindReturn,
-  findAllByA11yRole: (A11yRole, ?WaitForOptions) => FindAllReturn,
-  findAllByRole: (A11yRole, ?WaitForOptions) => FindAllReturn,
+  getByA11yRole: (A11yRole | RegExp, ?QueryOptions, ?QueryOptions) => GetReturn,
+  getByRole: (A11yRole | RegExp, ?QueryOptions) => GetReturn,
+  getAllByA11yRole: (A11yRole | RegExp, ?QueryOptions) => GetAllReturn,
+  getAllByRole: (A11yRole | RegExp, ?QueryOptions) => GetAllReturn,
+  queryByA11yRole: (A11yRole | RegExp, ?QueryOptions) => QueryReturn,
+  queryByRole: (A11yRole | RegExp, ?QueryOptions) => QueryReturn,
+  queryAllByA11yRole: (A11yRole | RegExp, ?QueryOptions) => QueryAllReturn,
+  queryAllByRole: (A11yRole | RegExp, ?QueryOptions) => QueryAllReturn,
+  findByA11yRole: (A11yRole, ?WaitForOptionsWithName) => FindReturn,
+  findByRole: (A11yRole, ?WaitForOptionsWithName) => FindReturn,
+  findAllByA11yRole: (A11yRole, ?WaitForOptionsWithName) => FindAllReturn,
+  findAllByRole: (A11yRole, ?WaitForOptionsWithName) => FindAllReturn,
 
   // States
   getByA11yStates: (A11yStates | Array<A11yStates>) => GetReturn,

src/helpers/makeA11yQuery.js

@@ -1,6 +1,7 @@
 // @flow
 import waitFor from '../waitFor';
-import type { WaitForOptions } from '../waitFor';
+import { getQueriesForElement } from '../within';
+import type { WaitForOptionsWithName } from './a11yAPI';
 import {
   ErrorWithStack,
   prepareErrorMessage,
@@ -26,15 +27,30 @@ type QueryNames = {
   findAllBy: Array<string>,
 };
 
+type QueryOptions = {
+  name: string | RegExp,
+};
+
 const makeA11yQuery = <P: mixed, M: mixed>(
   name: string,
   queryNames: QueryNames,
   matcherFn: (prop: P, value: M) => boolean
 ): ((instance: ReactTestInstance) => { ... }) => (
   instance: ReactTestInstance
 ) => {
-  const getBy = (matcher: M) => {
+  const getBy = (matcher: M, options?: QueryOptions) => {
     try {
+      if (options?.name) {
+        return instance.find((node) => {
+          const matchesRole =
+            isNodeValid(node) && matcherFn(node.props[name], matcher);
+
+          if (!matchesRole) return false;
+
+          return !!getQueriesForElement(node).queryByText(options.name);
+        });
+      }
+
       return instance.find(
         (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
       );
@@ -46,10 +62,23 @@ const makeA11yQuery = <P: mixed, M: mixed>(
     }
   };
 
-  const getAllBy = (matcher: M) => {
-    const results = instance.findAll(
-      (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
-    );
+  const getAllBy = (matcher: M, options?: QueryOptions) => {
+    let results = [];
+
+    if (options?.name) {
+      results = instance.find((node) => {
+        const matchesRole =
+          isNodeValid(node) && matcherFn(node.props[name], matcher);
+
+        if (!matchesRole) return false;
+
+        return !!getQueriesForElement(node).queryByText(options.name);
+      });
+    } else {
+      results = instance.findAll(
+        (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
+      );
+    }
 
     if (results.length === 0) {
       throw new ErrorWithStack(
@@ -61,28 +90,28 @@ const makeA11yQuery = <P: mixed, M: mixed>(
     return results;
   };
 
-  const queryBy = (matcher: M) => {
+  const queryBy = (matcher: M, options?: QueryOptions) => {
     try {
-      return getBy(matcher);
+      return getBy(matcher, options);
     } catch (error) {
       return createQueryByError(error, queryBy);
     }
   };
 
-  const queryAllBy = (matcher: M) => {
+  const queryAllBy = (matcher: M, options?: QueryOptions) => {
     try {
-      return getAllBy(matcher);
+      return getAllBy(matcher, options);
     } catch (error) {
       return [];
     }
   };
 
-  const findBy = (matcher: M, waitForOptions?: WaitForOptions) => {
-    return waitFor(() => getBy(matcher), waitForOptions);
+  const findBy = (matcher: M, waitForOptions?: WaitForOptionsWithName) => {
+    return waitFor(() => getBy(matcher, waitForOptions));
   };
 
-  const findAllBy = (matcher: M, waitForOptions?: WaitForOptions) => {
-    return waitFor(() => getAllBy(matcher), waitForOptions);
+  const findAllBy = (matcher: M, waitForOptions?: WaitForOptionsWithName) => {
+    return waitFor(() => getAllBy(matcher, waitForOptions));
   };
 
   return {