feat: toHaveAccessibleName matcher

Author: anishamalde

src/helpers/accessiblity.ts

@@ -4,7 +4,7 @@ import {
   StyleSheet,
 } from 'react-native';
 import { ReactTestInstance } from 'react-test-renderer';
-import { getHostSiblings } from './component-tree';
+import { getHostSiblings, getHostParent } from './component-tree';
 import { getHostComponentNames } from './host-component-names';
 
 type IsInaccessibleOptions = {
@@ -233,3 +233,34 @@ export function isElementSelected(
   const { accessibilityState, 'aria-selected': ariaSelected } = element.props;
   return ariaSelected ?? accessibilityState?.selected ?? false;
 }
+
+export function getAccessibleName(
+  element: ReactTestInstance
+): string | undefined {
+  const labelTextFromLabel = getAccessibilityLabel(element);
+  const labelTextFromLabelledBy = getAccessibilityLabelledBy(element);
+
+  if (labelTextFromLabelledBy) {
+    const parentElement = getHostParent(element);
+
+    if (parentElement) {
+      const labelElement = parentElement.findByProps({
+        nativeID: labelTextFromLabelledBy,
+      });
+
+      if (labelElement) {
+        // Extract and return the text content of the label element
+        const label = labelElement.props.children;
+        return label;
+      }
+    }
+  }
+
+  if (labelTextFromLabel) {
+    return labelTextFromLabel;
+  }
+
+  const ownText = element?.children?.join(' ');
+
+  return ownText || undefined;
+}

src/helpers/matchers/accessibilityName.ts

@@ -0,0 +1,18 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { getAccessibleName } from '../accessiblity';
+import { TextMatchOptions, matches, TextMatch } from '../../matches';
+
+export function matchAccessibleName(
+  node: ReactTestInstance,
+  expectedName?: TextMatch,
+  normalizer?: TextMatchOptions['normalizer'],
+  exact?: TextMatchOptions['exact']
+): boolean {
+  const accessibleName = getAccessibleName(node);
+
+  if (expectedName) {
+    return matches(expectedName, accessibleName, normalizer, exact);
+  }
+
+  return !!accessibleName;
+}

src/matchers/__tests__/to-have-accessible-name.test.tsx

@@ -0,0 +1,111 @@
+import * as React from 'react';
+import { View, Text, TextInput } from 'react-native';
+import { render, screen } from '../..';
+import '../extend-expect';
+
+test('toHaveAccessibleName() on view with accessibilityLabel prop', () => {
+  render(<View testID="accessibility-label" accessibilityLabel="Test Label" />);
+  const element = screen.getByTestId('accessibility-label');
+  expect(element).toHaveAccessibleName('Test Label');
+});
+
+test('toHaveAccessibleName() on view with aria-label prop', () => {
+  render(<View testID="aria-label" aria-label="Aria Test Label" />);
+  const element = screen.getByTestId('aria-label');
+  expect(element).toHaveAccessibleName('Aria Test Label');
+});
+
+test('toHaveAccessibleName() on view with accessibilityLabel prop with no expectedName', () => {
+  render(<View testID="no-expectName-label" accessibilityLabel="Test Label" />);
+  const element = screen.getByTestId('no-expectName-label');
+  expect(element).toHaveAccessibleName();
+});
+
+test('toHaveAccessibleName() on view with no accessibility props', () => {
+  render(<Text testID="accessibility-label">Text</Text>);
+  const element = screen.getByTestId('accessibility-label');
+  expect(element).toHaveAccessibleName('Text');
+});
+
+test('toHaveAccessibleName() on view with that does not have the expected accessible name', () => {
+  render(<View testID="wrong-label" accessibilityLabel="The actual label" />);
+  const element = screen.getByTestId('wrong-label');
+  expect(() => expect(element).toHaveAccessibleName('Not the label'))
+    .toThrowErrorMatchingInlineSnapshot(`
+  "expect(element).toHaveAccessibleName()
+
+  Expected element to have accessible name:
+    Not the label
+  Received:
+    The actual label"
+`);
+});
+
+test('toHaveAccessibleName() on view that doesnt have accessible name defined', () => {
+  render(<View testID="no-accessibile-name" />);
+  const element = screen.getByTestId('no-accessibile-name');
+
+  expect(() => expect(element).toHaveAccessibleName())
+    .toThrowErrorMatchingInlineSnapshot(`
+    "expect(element).toHaveAccessibleName()
+
+    Expected element to have accessible name:
+
+    Received:
+      undefined"
+  `);
+});
+
+it('toHaveAccessibleName() on a non-host element', () => {
+  const nonElement = 'This is not a ReactTestInstance';
+  expect(() => expect(nonElement).toHaveAccessibleName())
+    .toThrowErrorMatchingInlineSnapshot(`
+    "expect(received).toHaveAccessibleName()
+
+    received value must be a host element.
+    Received has type:  string
+    Received has value: "This is not a ReactTestInstance""
+  `);
+});
+
+test('toHaveAccessibleName() on view with accessibilityLabelledBy prop', async () => {
+  render(
+    <View>
+      <Text nativeID="formLabel">Accessibility LabelledBy</Text>
+      <TextInput
+        testID="accessibility-labelledby"
+        accessibilityLabelledBy="formLabel"
+      />
+    </View>
+  );
+
+  const element = screen.getByTestId('accessibility-labelledby');
+  expect(element).toHaveAccessibleName('Accessibility LabelledBy');
+});
+
+test('toHaveAccessibleName() on view with ariaLabelledBy prop', async () => {
+  render(
+    <View>
+      <Text nativeID="formLabel">Aria LabelledBy</Text>
+      <TextInput testID="aria-labelledby" aria-labelledby="formLabel" />
+    </View>
+  );
+
+  const element = screen.getByTestId('aria-labelledby');
+  expect(element).toHaveAccessibleName('Aria LabelledBy');
+});
+
+//TODO: This fails as expected as I am unsure on how to extract the Text from the nested Element
+test('getByLabelText supports nested aria-labelledby', async () => {
+  const screen = render(
+    <>
+      <View nativeID="label">
+        <Text>Nested Aria LabelledBy</Text>
+      </View>
+      <TextInput testID="text-input" aria-labelledby="label" />
+    </>
+  );
+
+  const element = screen.getByTestId('text-input');
+  expect(element).toHaveAccessibleName('Nested Aria LabelledBy');
+});

src/matchers/extend-expect.d.ts

@@ -22,6 +22,7 @@ export interface JestNativeMatchers<R> {
   toHaveProp(name: string, expectedValue?: unknown): R;
   toHaveStyle(style: StyleProp<Style>): R;
   toHaveTextContent(expectedText: TextMatch, options?: TextMatchOptions): R;
+  toHaveAccessibleName(expectedName?: TextMatch, options?: TextMatchOptions): R;
 }
 
 // Implicit Jest global `expect`.

src/matchers/extend-expect.ts

@@ -16,6 +16,7 @@ import { toHaveDisplayValue } from './to-have-display-value';
 import { toHaveProp } from './to-have-prop';
 import { toHaveStyle } from './to-have-style';
 import { toHaveTextContent } from './to-have-text-content';
+import { toHaveAccessibleName } from './to-have-accessible-name';
 
 expect.extend({
   toBeOnTheScreen,
@@ -35,4 +36,5 @@ expect.extend({
   toHaveProp,
   toHaveStyle,
   toHaveTextContent,
+  toHaveAccessibleName,
 });

src/matchers/index.ts

@@ -14,3 +14,4 @@ export { toHaveDisplayValue } from './to-have-display-value';
 export { toHaveProp } from './to-have-prop';
 export { toHaveStyle } from './to-have-style';
 export { toHaveTextContent } from './to-have-text-content';
+export { toHaveAccessibleName } from './to-have-accessible-name';

src/matchers/to-have-accessible-name.tsx

@@ -0,0 +1,43 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { matcherHint } from 'jest-matcher-utils';
+import { matchAccessibleName } from '../helpers/matchers/accessibilityName';
+import { getAccessibleName } from '../helpers/accessiblity';
+import { TextMatch, TextMatchOptions } from '../matches';
+import { checkHostElement, formatMessage } from './utils';
+
+export function toHaveAccessibleName(
+  this: jest.MatcherContext,
+  element: ReactTestInstance,
+  expectedName?: TextMatch,
+  options?: TextMatchOptions
+) {
+  checkHostElement(element, toHaveAccessibleName, this);
+
+  const receivedName = getAccessibleName(element);
+
+  return {
+    pass: matchAccessibleName(
+      element,
+      expectedName,
+      options?.normalizer,
+      options?.exact
+    ),
+    message: () => {
+      return [
+        formatMessage(
+          matcherHint(
+            `${this.isNot ? '.not' : ''}.toHaveAccessibleName`,
+            'element',
+            ''
+          ),
+          `Expected element ${
+            this.isNot ? 'not to' : 'to'
+          } have accessible name`,
+          `${expectedName ? expectedName : ''}`,
+          'Received',
+          receivedName
+        ),
+      ].join('\n');
+    },
+  };
+}