feat: support *ByRole queries

Author: mdjastrzebski

src/helpers/accessibility.ts

@@ -103,6 +103,10 @@ export function isAccessibilityElement(element: ReactTestInstance | null): boole
     return false;
   }
 
+  if (isHostImage(element) && element.props.alt) {
+    return true;
+  }
+
   if (element.props.accessible !== undefined) {
     return element.props.accessible;
   }
@@ -131,16 +135,28 @@ export function isAccessibilityElement(element: ReactTestInstance | null): boole
 export function getRole(element: ReactTestInstance): Role | AccessibilityRole {
   const explicitRole = element.props.role ?? element.props.accessibilityRole;
   if (explicitRole) {
-    return explicitRole;
+    return normalizeRole(explicitRole);
   }
 
   if (isHostText(element)) {
     return 'text';
   }
 
+  if (isHostImage(element) && element.props.alt) {
+    return 'img';
+  }
+
   return 'none';
 }
 
+export function normalizeRole(role: string): Role | AccessibilityRole {
+  if (role === 'image') {
+    return 'img';
+  }
+
+  return role as Role | AccessibilityRole;
+}
+
 export function computeAriaModal(element: ReactTestInstance): boolean | undefined {
   return element.props['aria-modal'] ?? element.props.accessibilityViewIsModal;
 }

src/helpers/format-default.ts

@@ -9,6 +9,7 @@ const propsToDisplay = [
   'accessibilityLabelledBy',
   'accessibilityRole',
   'accessibilityViewIsModal',
+  'alt',
   'aria-busy',
   'aria-checked',
   'aria-disabled',

src/queries/__tests__/role-value.test.tsx

@@ -77,7 +77,7 @@ describe('accessibility value', () => {
 
     expect(() => screen.getByRole('adjustable', { name: 'Hello', value: { min: 5 } }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", name: "Hello", min value: 5
+      "Unable to find an element with role: adjustable, name: Hello, min value: 5
 
       <Text
         accessibilityRole="adjustable"
@@ -100,7 +100,7 @@ describe('accessibility value', () => {
     `);
     expect(() => screen.getByRole('adjustable', { name: 'World', value: { min: 10 } }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", name: "World", min value: 10
+      "Unable to find an element with role: adjustable, name: World, min value: 10
 
       <Text
         accessibilityRole="adjustable"
@@ -123,7 +123,7 @@ describe('accessibility value', () => {
     `);
     expect(() => screen.getByRole('adjustable', { name: 'Hello', value: { min: 5 } }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", name: "Hello", min value: 5
+      "Unable to find an element with role: adjustable, name: Hello, min value: 5
 
       <Text
         accessibilityRole="adjustable"
@@ -146,7 +146,7 @@ describe('accessibility value', () => {
     `);
     expect(() => screen.getByRole('adjustable', { selected: true, value: { min: 10 } }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", selected state: true, min value: 10
+      "Unable to find an element with role: adjustable, selected state: true, min value: 10
 
       <Text
         accessibilityRole="adjustable"

src/queries/__tests__/role.test.tsx

@@ -4,6 +4,7 @@ import {
   Pressable,
   Text,
   TextInput,
+  Image,
   TouchableOpacity,
   TouchableWithoutFeedback,
   View,
@@ -17,11 +18,11 @@ const TEXT_LABEL = 'cool text';
 const NO_MATCHES_TEXT: any = 'not-existent-element';
 
 const getMultipleInstancesFoundMessage = (value: string) => {
-  return `Found multiple elements with role: "${value}"`;
+  return `Found multiple elements with role: ${value}`;
 };
 
 const getNoInstancesFoundMessage = (value: string) => {
-  return `Unable to find an element with role: "${value}"`;
+  return `Unable to find an element with role: ${value}`;
 };
 
 const Typography = ({ children, ...rest }: any) => {
@@ -224,6 +225,15 @@ describe('supports name option', () => {
     expect(screen.getByRole('header', { name: 'About' })).toBe(screen.getByTestId('target-header'));
     expect(screen.getByRole('header', { name: 'About' }).props.testID).toBe('target-header');
   });
+
+  test('supports host Image element with "alt" prop', () => {
+    render(<Image alt="An elephant" testID="image" />);
+
+    const expectedElement = screen.getByTestId('image');
+    expect(screen.getByRole('img', { name: 'An elephant' })).toBe(expectedElement);
+    expect(screen.getByRole('image', { name: 'An elephant' })).toBe(expectedElement);
+    expect(screen.getByRole(/img/, { name: 'An elephant' })).toBe(expectedElement);
+  });
 });
 
 describe('supports accessibility states', () => {
@@ -768,7 +778,7 @@ describe('error messages', () => {
     render(<View />);
 
     expect(() => screen.getByRole('button')).toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "button"
+      "Unable to find an element with role: button
 
       <View />"
     `);
@@ -778,7 +788,7 @@ describe('error messages', () => {
     render(<View />);
 
     expect(() => screen.getByRole('button', { name: 'Save' })).toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "button", name: "Save"
+      "Unable to find an element with role: button, name: Save
 
       <View />"
     `);
@@ -789,7 +799,7 @@ describe('error messages', () => {
 
     expect(() => screen.getByRole('button', { name: 'Save', disabled: true }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "button", name: "Save", disabled state: true
+      "Unable to find an element with role: button, name: Save, disabled state: true
 
       <View />"
     `);
@@ -800,7 +810,7 @@ describe('error messages', () => {
 
     expect(() => screen.getByRole('button', { name: 'Save', disabled: true, selected: true }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "button", name: "Save", disabled state: true, selected state: true
+      "Unable to find an element with role: button, name: Save, disabled state: true, selected state: true
 
       <View />"
     `);
@@ -811,7 +821,7 @@ describe('error messages', () => {
 
     expect(() => screen.getByRole('button', { disabled: true }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "button", disabled state: true
+      "Unable to find an element with role: button, disabled state: true
 
       <View />"
     `);
@@ -822,7 +832,7 @@ describe('error messages', () => {
 
     expect(() => screen.getByRole('adjustable', { value: { min: 1 } }))
       .toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", min value: 1
+      "Unable to find an element with role: adjustable, min value: 1
 
       <View />"
     `);
@@ -832,7 +842,7 @@ describe('error messages', () => {
         value: { min: 1, max: 2, now: 1, text: /hello/ },
       }),
     ).toThrowErrorMatchingInlineSnapshot(`
-      "Unable to find an element with role: "adjustable", min value: 1, max value: 2, now value: 1, text value: /hello/
+      "Unable to find an element with role: adjustable, min value: 1, max value: 2, now value: 1, text value: /hello/
 
       <View />"
     `);
@@ -852,7 +862,7 @@ test('byRole queries support hidden option', () => {
   expect(screen.queryByRole('button', { includeHiddenElements: false })).toBeFalsy();
   expect(() => screen.getByRole('button', { includeHiddenElements: false }))
     .toThrowErrorMatchingInlineSnapshot(`
-    "Unable to find an element with role: "button"
+    "Unable to find an element with role: button
 
     <View
       accessibilityRole="button"
@@ -889,7 +899,7 @@ describe('matches only accessible elements', () => {
     expect(screen.queryByRole('button', { name: 'Action' })).toBeFalsy();
   });
 
-  test('ignores elements with accessible={undefined} and that are implicitely not accessible', () => {
+  test('ignores elements with accessible={undefined} and that are implicitly not accessible', () => {
     render(
       <View accessibilityRole="menu">
         <Text>Action</Text>
@@ -903,31 +913,31 @@ test('error message renders the element tree, preserving only helpful props', as
   render(<View accessibilityRole="button" key="3" />);
 
   expect(() => screen.getByRole('link')).toThrowErrorMatchingInlineSnapshot(`
-    "Unable to find an element with role: "link"
+    "Unable to find an element with role: link
 
     <View
       accessibilityRole="button"
     />"
   `);
 
   expect(() => screen.getAllByRole('link')).toThrowErrorMatchingInlineSnapshot(`
-    "Unable to find an element with role: "link"
+    "Unable to find an element with role: link
 
     <View
       accessibilityRole="button"
     />"
   `);
 
   await expect(screen.findByRole('link')).rejects.toThrowErrorMatchingInlineSnapshot(`
-    "Unable to find an element with role: "link"
+    "Unable to find an element with role: link
 
     <View
       accessibilityRole="button"
     />"
   `);
 
   await expect(screen.findAllByRole('link')).rejects.toThrowErrorMatchingInlineSnapshot(`
-    "Unable to find an element with role: "link"
+    "Unable to find an element with role: link
 
     <View
       accessibilityRole="button"

src/queries/role.ts

@@ -5,6 +5,7 @@ import {
   accessibilityValueKeys,
   getRole,
   isAccessibilityElement,
+  normalizeRole,
 } from '../helpers/accessibility';
 import { findAll } from '../helpers/find-all';
 import {
@@ -38,6 +39,10 @@ export type ByRoleOptions = CommonQueryOptions &
     value?: AccessibilityValueMatcher;
   };
 
+const matchRole = (node: ReactTestInstance, role: ByRoleMatcher) => {
+  return matchStringProp(getRole(node), role);
+};
+
 const matchAccessibleNameIfNeeded = (node: ReactTestInstance, name?: TextMatch) => {
   if (name == null) return true;
 
@@ -60,12 +65,13 @@ const queryAllByRole = (
   instance: ReactTestInstance,
 ): QueryAllByQuery<ByRoleMatcher, ByRoleOptions> =>
   function queryAllByRoleFn(role, options) {
+    const normalizedRole = typeof role === 'string' ? normalizeRole(role) : role;
     return findAll(
       instance,
       (node) =>
         // run the cheapest checks first, and early exit to avoid unneeded computations
         isAccessibilityElement(node) &&
-        matchStringProp(getRole(node), role) &&
+        matchRole(node, normalizedRole) &&
         matchAccessibleStateIfNeeded(node, options) &&
         matchAccessibilityValueIfNeeded(node, options?.value) &&
         matchAccessibleNameIfNeeded(node, options?.name),
@@ -74,10 +80,10 @@ const queryAllByRole = (
   };
 
 const formatQueryParams = (role: TextMatch, options: ByRoleOptions = {}) => {
-  const params = [`role: "${String(role)}"`];
+  const params = [`role: ${String(role)}`];
 
   if (options.name) {
-    params.push(`name: "${String(options.name)}"`);
+    params.push(`name: ${String(options.name)}`);
   }
 
   accessibilityStateKeys.forEach((stateKey) => {