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 ONE_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>{ONE_OCCURANCE}</Text>
+      </TouchableOpacity>
+    </>
+  );
+}
+
 test('getByA11yLabel, queryByA11yLabel, findByA11yLabel', async () => {
   const { getByA11yLabel, queryByA11yLabel, findByA11yLabel } = render(
     <Section />
@@ -186,12 +204,40 @@ test('getByA11yRole, queryByA11yRole, findByA11yRole', async () => {
 
   const asyncButton = await findByA11yRole('button');
   expect(asyncButton.props.accessibilityRole).toEqual('button');
-  await expect(findByA11yRole(NO_MATCHES_TEXT, waitForOptions)).rejects.toThrow(
-    getNoInstancesFoundMessage('accessibilityRole')
-  );
+  await expect(
+    findByA11yRole(NO_MATCHES_TEXT, {}, waitForOptions)
+  ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole'));
   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', { name: TWO_OCCURANCE })).toThrow(
+    FOUND_TWO_INSTANCES
+  );
+  getByA11yRole('button', { name: ONE_OCCURANCE });
+
+  expect(queryByA11yRole('button', { name: NO_MATCHES_TEXT })).toBeNull();
+  expect(() => queryByA11yRole('button', { name: TWO_OCCURANCE })).toThrow(
+    FOUND_TWO_INSTANCES
+  );
+
+  await findByA11yRole('button', {
+    name: ONE_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 />
@@ -207,10 +253,32 @@ test('getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole', async () => {
 
   await expect(findAllByA11yRole('link')).resolves.toHaveLength(2);
   await expect(
-    findAllByA11yRole(NO_MATCHES_TEXT, waitForOptions)
+    findAllByA11yRole(NO_MATCHES_TEXT, {}, waitForOptions)
   ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole'));
 });
 
+test('getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole with name', async () => {
+  const { getAllByA11yRole, queryAllByA11yRole, findAllByA11yRole } = render(
+    <ButtonsWithText />
+  );
+
+  expect(getAllByA11yRole('button', { name: TWO_OCCURANCE })).toHaveLength(2);
+  expect(getAllByA11yRole('button', { name: ONE_OCCURANCE })).toHaveLength(1);
+  expect(queryAllByA11yRole('button', { name: TWO_OCCURANCE })).toHaveLength(2);
+
+  expect(() => getAllByA11yRole('button', { name: NO_MATCHES_TEXT })).toThrow(
+    getNoInstancesFoundMessage('accessibilityRole', 'button')
+  );
+  expect(queryAllByA11yRole('button', { name: NO_MATCHES_TEXT })).toEqual([]);
+
+  await expect(
+    findAllByA11yRole('button', { name: TWO_OCCURANCE })
+  ).resolves.toHaveLength(2);
+  await expect(
+    findAllByA11yRole('button', { name: NO_MATCHES_TEXT })
+  ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole', 'button'));
+});
+
 // TODO: accessibilityStates was removed from RN 0.62
 test.skip('getByA11yStates, queryByA11yStates', () => {
   const { getByA11yStates, queryByA11yStates } = render(<Section />);

src/helpers/a11yAPI.js

@@ -10,6 +10,9 @@ type QueryAllReturn = Array<ReactTestInstance>;
 type FindReturn = Promise<GetReturn>;
 type FindAllReturn = Promise<GetAllReturn>;
 
+export type QueryOptions = {
+  name?: string | RegExp,
+};
 export type A11yAPI = {|
   // Label
   getByA11yLabel: (string | RegExp) => GetReturn,
@@ -40,18 +43,22 @@ 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, ?QueryOptions, ?WaitForOptions) => FindReturn,
+  findByRole: (A11yRole, ?QueryOptions, ?WaitForOptions) => FindReturn,
+  findAllByA11yRole: (
+    A11yRole,
+    ?QueryOptions,
+    ?WaitForOptions
+  ) => FindAllReturn,
+  findAllByRole: (A11yRole, ?QueryOptions, ?WaitForOptions) => FindAllReturn,
 
   // States
   getByA11yStates: (A11yStates | Array<A11yStates>) => GetReturn,

src/helpers/makeA11yQuery.js

@@ -1,6 +1,8 @@
 // @flow
 import waitFor from '../waitFor';
+import { getQueriesForElement } from '../within';
 import type { WaitForOptions } from '../waitFor';
+import type { QueryOptions } from './a11yAPI';
 import {
   ErrorWithStack,
   prepareErrorMessage,
@@ -33,8 +35,27 @@ const makeA11yQuery = <P: mixed, M: mixed>(
 ): ((instance: ReactTestInstance) => { ... }) => (
   instance: ReactTestInstance
 ) => {
-  const getBy = (matcher: M) => {
+  const filterWithName = (
+    node: ReactTestInstance,
+    options: QueryOptions,
+    matcher: M
+  ) => {
+    const matchesRole =
+      isNodeValid(node) && matcherFn(node.props[name], matcher);
+
+    return (
+      matchesRole && !!getQueriesForElement(node).queryByText(options.name)
+    );
+  };
+
+  const getBy = (matcher: M, queryOptions?: QueryOptions) => {
     try {
+      if (queryOptions?.name) {
+        return instance.find((node) =>
+          filterWithName(node, queryOptions, matcher)
+        );
+      }
+
       return instance.find(
         (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
       );
@@ -46,10 +67,18 @@ 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.findAll((node) =>
+        filterWithName(node, options, matcher)
+      );
+    } else {
+      results = instance.findAll(
+        (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
+      );
+    }
 
     if (results.length === 0) {
       throw new ErrorWithStack(
@@ -61,28 +90,36 @@ 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,
+    queryOptions?: QueryOptions,
+    waitForOptions?: WaitForOptions
+  ) => {
+    return waitFor(() => getBy(matcher, queryOptions), waitForOptions);
   };
 
-  const findAllBy = (matcher: M, waitForOptions?: WaitForOptions) => {
-    return waitFor(() => getAllBy(matcher), waitForOptions);
+  const findAllBy = (
+    matcher: M,
+    queryOptions: QueryOptions,
+    waitForOptions?: WaitForOptions
+  ) => {
+    return waitFor(() => getAllBy(matcher, queryOptions), waitForOptions);
   };
 
   return {