Add support for ByRole with name (#1127)

Co-authored-by: Kiran Jd <kiranjd8@gmail.com>

Author: AugustinLF

src/queries/__tests__/role.test.tsx

@@ -42,6 +42,7 @@ test('getByRole, queryByRole, findByRole', async () => {
   expect(() => getByRole(NO_MATCHES_TEXT)).toThrow(
     getNoInstancesFoundMessage(NO_MATCHES_TEXT)
   );
+
   expect(queryByRole(NO_MATCHES_TEXT)).toBeNull();
 
   expect(() => getByRole('link')).toThrow(
@@ -77,3 +78,60 @@ test('getAllByRole, queryAllByRole, findAllByRole', async () => {
     getNoInstancesFoundMessage(NO_MATCHES_TEXT)
   );
 });
+
+describe('supports name option', () => {
+  test('returns an element that has the corresponding role and a children with the name', () => {
+    const { getByRole } = render(
+      <TouchableOpacity accessibilityRole="button" testID="target-button">
+        <Text>Save</Text>
+      </TouchableOpacity>
+    );
+
+    // assert on the testId to be sure that the returned element is the one with the accessibilityRole
+    expect(getByRole('button', { name: 'Save' }).props.testID).toBe(
+      'target-button'
+    );
+  });
+
+  test('returns an element that has the corresponding role when several children include the name', () => {
+    const { getByRole } = render(
+      <TouchableOpacity accessibilityRole="button" testID="target-button">
+        <Text>Save</Text>
+        <Text>Save</Text>
+      </TouchableOpacity>
+    );
+
+    // assert on the testId to be sure that the returned element is the one with the accessibilityRole
+    expect(getByRole('button', { name: 'Save' }).props.testID).toBe(
+      'target-button'
+    );
+  });
+
+  test('returns an element that has the corresponding role and a children with a matching accessibilityLabel', () => {
+    const { getByRole } = render(
+      <TouchableOpacity accessibilityRole="button" testID="target-button">
+        <Text accessibilityLabel="Save" />
+      </TouchableOpacity>
+    );
+
+    // assert on the testId to be sure that the returned element is the one with the accessibilityRole
+    expect(getByRole('button', { name: 'Save' }).props.testID).toBe(
+      'target-button'
+    );
+  });
+
+  test('returns an element that has the corresponding role and a matching accessibilityLabel', () => {
+    const { getByRole } = render(
+      <TouchableOpacity
+        accessibilityRole="button"
+        testID="target-button"
+        accessibilityLabel="Save"
+      ></TouchableOpacity>
+    );
+
+    // assert on the testId to be sure that the returned element is the one with the accessibilityRole
+    expect(getByRole('button', { name: 'Save' }).props.testID).toBe(
+      'target-button'
+    );
+  });
+});

src/queries/role.ts

@@ -1,6 +1,7 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import { TextMatch } from '../matches';
 import { matchStringProp } from '../helpers/matchers/matchStringProp';
+import { TextMatch } from '../matches';
+import { getQueriesForElement } from '../within';
 import { makeQueries } from './makeQueries';
 import type {
   FindAllByQuery,
@@ -11,14 +12,31 @@ import type {
   QueryByQuery,
 } from './makeQueries';
 
+type ByRoleOptions = {
+  name?: TextMatch;
+};
+
+const matchAccessibleNameIfNeeded = (
+  node: ReactTestInstance,
+  name?: TextMatch
+) => {
+  if (name == null) return true;
+
+  const { queryAllByText, queryAllByLabelText } = getQueriesForElement(node);
+  return (
+    queryAllByText(name).length > 0 || queryAllByLabelText(name).length > 0
+  );
+};
+
 const queryAllByRole = (
   instance: ReactTestInstance
-): ((role: TextMatch) => Array<ReactTestInstance>) =>
-  function queryAllByRoleFn(role) {
+): ((role: TextMatch, options?: ByRoleOptions) => Array<ReactTestInstance>) =>
+  function queryAllByRoleFn(role, options) {
     return instance.findAll(
       (node) =>
         typeof node.type === 'string' &&
-        matchStringProp(node.props.accessibilityRole, role)
+        matchStringProp(node.props.accessibilityRole, role) &&
+        matchAccessibleNameIfNeeded(node, options?.name)
     );
   };
 
@@ -34,12 +52,12 @@ const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
 );
 
 export type ByRoleQueries = {
-  getByRole: GetByQuery<TextMatch>;
-  getAllByRole: GetAllByQuery<TextMatch>;
-  queryByRole: QueryByQuery<TextMatch>;
-  queryAllByRole: QueryAllByQuery<TextMatch>;
-  findByRole: FindByQuery<TextMatch>;
-  findAllByRole: FindAllByQuery<TextMatch>;
+  getByRole: GetByQuery<TextMatch, ByRoleOptions>;
+  getAllByRole: GetAllByQuery<TextMatch, ByRoleOptions>;
+  queryByRole: QueryByQuery<TextMatch, ByRoleOptions>;
+  queryAllByRole: QueryAllByQuery<TextMatch, ByRoleOptions>;
+  findByRole: FindByQuery<TextMatch, ByRoleOptions>;
+  findAllByRole: FindAllByQuery<TextMatch, ByRoleOptions>;
 };
 
 export const bindByRoleQueries = (

typings/index.flow.js

@@ -202,6 +202,11 @@ interface UnsafeByPropsQueries {
     | Array<ReactTestInstance>
     | [];
 }
+
+interface ByRoleOptions {
+  name?: string;
+}
+
 interface A11yAPI {
   // Label
   getByLabelText: (matcher: TextMatch) => GetReturn;
@@ -244,16 +249,27 @@ interface A11yAPI {
   ) => FindAllReturn;
 
   // Role
-  getByRole: (matcher: A11yRole | RegExp) => GetReturn;
-  getAllByRole: (matcher: A11yRole | RegExp) => GetAllReturn;
-  queryByRole: (matcher: A11yRole | RegExp) => QueryReturn;
-  queryAllByRole: (matcher: A11yRole | RegExp) => QueryAllReturn;
+  getByRole: (matcher: A11yRole | RegExp, role?: ByRoleOptions) => GetReturn;
+  getAllByRole: (
+    matcher: A11yRole | RegExp,
+    role?: ByRoleOptions
+  ) => GetAllReturn;
+  queryByRole: (
+    matcher: A11yRole | RegExp,
+    role?: ByRoleOptions
+  ) => QueryReturn;
+  queryAllByRole: (
+    matcher: A11yRole | RegExp,
+    role?: ByRoleOptions
+  ) => QueryAllReturn;
   findByRole: (
     matcher: A11yRole | RegExp,
+    role?: ByRoleOptions,
     waitForOptions?: WaitForOptions
   ) => FindReturn;
   findAllByRole: (
     matcher: A11yRole | RegExp,
+    role?: ByRoleOptions,
     waitForOptions?: WaitForOptions
   ) => FindAllReturn;
 

website/docs/Queries.md

@@ -189,6 +189,10 @@ render(<MyComponent />);
 const element = screen.getByRole('button');
 ```
 
+#### Options
+
+`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
+
 ### `ByA11yState`, `ByAccessibilityState`
 
 > getByA11yState, getAllByA11yState, queryByA11yState, queryAllByA11yState, findByA11yState, findAllByA11yState
@@ -305,7 +309,8 @@ To override normalization to remove some Unicode characters whilst keeping some
 
 ```typescript
 screen.getByText(node, 'text', {
-  normalizer: (str) => getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
+  normalizer: (str) =>
+    getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
 });
 ```