Fix test naming for consistency, improve types and ensure multiple children matching is supported

Author: AugustinLF

src/queries/__tests__/role.test.tsx

@@ -79,8 +79,8 @@ test('getAllByRole, queryAllByRole, findAllByRole', async () => {
   );
 });
 
-describe('*ByRole with a name', () => {
-  test('Find an element that has the corresponding role and a children with the name', () => {
+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>
@@ -93,10 +93,11 @@ describe('*ByRole with a name', () => {
     );
   });
 
-  test('Find an element that has the corresponding role and a children with a matching accessibilityLabel', () => {
+  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 accessibilityLabel="Save" />
+        <Text>Save</Text>
+        <Text>Save</Text>
       </TouchableOpacity>
     );
 
@@ -106,13 +107,11 @@ describe('*ByRole with a name', () => {
     );
   });
 
-  test('Find an element that has the corresponding role and a matching accessibilityLabel', () => {
+  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"
-        accessibilityLabel="Save"
-      ></TouchableOpacity>
+      <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
@@ -121,7 +120,7 @@ describe('*ByRole with a name', () => {
     );
   });
 
-  test('Can find by name using a regex', () => {
+  test('returns an element that has the corresponding role and a matching accessibilityLabel', () => {
     const { getByRole } = render(
       <TouchableOpacity
         accessibilityRole="button"
@@ -131,7 +130,7 @@ describe('*ByRole with a name', () => {
     );
 
     // 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(
+    expect(getByRole('button', { name: 'Save' }).props.testID).toBe(
       'target-button'
     );
   });

src/queries/role.ts

@@ -1,5 +1,4 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import type { AccessibilityRole } from 'react-native';
 import { matchStringProp } from '../helpers/matchers/matchStringProp';
 import { TextMatch } from '../matches';
 import { getQueriesForElement } from '../within';
@@ -13,37 +12,34 @@ import type {
   QueryByQuery,
 } from './makeQueries';
 
-type Role = AccessibilityRole | TextMatch;
-
 type ByRoleOptions = {
   name?: TextMatch;
 };
 
-const filterByAccessibleName = (
-  node: ReactTestInstance,
-  name: TextMatch | undefined
-) => {
-  if (!name) return true;
+const matchAccessibleName = (node: ReactTestInstance, name?: TextMatch) => {
+  if (name == null) return true;
 
-  const { queryByText, queryByLabelText } = getQueriesForElement(node);
-  return Boolean(queryByText(name) || queryByLabelText(name));
+  const { queryAllByText, queryAllByLabelText } = getQueriesForElement(node);
+  return (
+    queryAllByText(name).length > 0 || queryAllByLabelText(name).length > 0
+  );
 };
 
 const queryAllByRole = (
   instance: ReactTestInstance
-): ((role: Role, options?: ByRoleOptions) => Array<ReactTestInstance>) =>
+): ((role: TextMatch, options?: ByRoleOptions) => Array<ReactTestInstance>) =>
   function queryAllByRoleFn(role, options) {
     return instance.findAll(
       (node) =>
         typeof node.type === 'string' &&
         matchStringProp(node.props.accessibilityRole, role) &&
-        filterByAccessibleName(node, options?.name)
+        matchAccessibleName(node, options?.name)
     );
   };
 
-const getMultipleError = (role: Role) =>
+const getMultipleError = (role: TextMatch) =>
   `Found multiple elements with accessibilityRole: ${String(role)} `;
-const getMissingError = (role: Role) =>
+const getMissingError = (role: TextMatch) =>
   `Unable to find an element with accessibilityRole: ${String(role)}`;
 
 const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
@@ -53,12 +49,12 @@ const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
 );
 
 export type ByRoleQueries = {
-  getByRole: GetByQuery<Role, ByRoleOptions>;
-  getAllByRole: GetAllByQuery<Role, ByRoleOptions>;
-  queryByRole: QueryByQuery<Role, ByRoleOptions>;
-  queryAllByRole: QueryAllByQuery<Role, ByRoleOptions>;
-  findByRole: FindByQuery<Role, ByRoleOptions>;
-  findAllByRole: FindAllByQuery<Role, ByRoleOptions>;
+  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

@@ -203,8 +203,8 @@ interface UnsafeByPropsQueries {
     | [];
 }
 
-interface ByRoleOption {
-  name: string;
+interface ByRoleOptions {
+  name?: string;
 }
 
 interface A11yAPI {
@@ -249,24 +249,27 @@ interface A11yAPI {
   ) => FindAllReturn;
 
   // Role
-  getByRole: (matcher: A11yRole | RegExp, role?: ByRoleOption) => GetReturn;
+  getByRole: (matcher: A11yRole | RegExp, role?: ByRoleOptions) => GetReturn;
   getAllByRole: (
     matcher: A11yRole | RegExp,
-    role?: ByRoleOption
+    role?: ByRoleOptions
   ) => GetAllReturn;
-  queryByRole: (matcher: A11yRole | RegExp, role?: ByRoleOption) => QueryReturn;
+  queryByRole: (
+    matcher: A11yRole | RegExp,
+    role?: ByRoleOptions
+  ) => QueryReturn;
   queryAllByRole: (
     matcher: A11yRole | RegExp,
-    role?: ByRoleOption
+    role?: ByRoleOptions
   ) => QueryAllReturn;
   findByRole: (
     matcher: A11yRole | RegExp,
-    role?: ByRoleOption,
+    role?: ByRoleOptions,
     waitForOptions?: WaitForOptions
   ) => FindReturn;
   findAllByRole: (
     matcher: A11yRole | RegExp,
-    role?: ByRoleOption,
+    role?: ByRoleOptions,
     waitForOptions?: WaitForOptions
   ) => FindAllReturn;
 

website/docs/Queries.md

@@ -191,7 +191,7 @@ const element = screen.getByRole('button');
 
 #### Options
 
-`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `ByText` or `queryByLabelText`).
+`name`: Finds an element with given `accessibilityRole` and an accessible name (equivalent to `byText` or `byLabelText` query).
 
 ### `ByA11yState`, `ByAccessibilityState`