feature: a11y value option for *ByRole queries

mdjastrzebski · mdjastrzebski · commit 68d9b29753c3 · 2022-11-15T15:50:54.000+01:00
diff --git a/src/helpers/__tests__/accessiblity.test.tsx b/src/helpers/__tests__/accessiblity.test.tsx
@@ -22,7 +22,7 @@ test('returns false for accessible elements', () => {
   ).toBe(false);
 });
 
-test('returns true for hidden elements', () => {
+test('returns true for null elements', () => {
   expect(isHiddenFromAccessibility(null)).toBe(true);
 });
 
diff --git a/src/helpers/accessiblity.ts b/src/helpers/accessiblity.ts
@@ -1,21 +1,30 @@
-import { AccessibilityState, StyleSheet } from 'react-native';
+import {
+  AccessibilityState,
+  AccessibilityValue,
+  StyleSheet,
+} from 'react-native';
 import { ReactTestInstance } from 'react-test-renderer';
 import { getHostSiblings } from './component-tree';
 
 type IsInaccessibleOptions = {
   cache?: WeakMap<ReactTestInstance, boolean>;
 };
 
-export type AccessibilityStateKey = keyof AccessibilityState;
-
-export const accessibilityStateKeys: AccessibilityStateKey[] = [
+export const accessibilityStateKeys: (keyof AccessibilityState)[] = [
   'disabled',
   'selected',
   'checked',
   'busy',
   'expanded',
 ];
 
+export const accessiblityValueKeys: (keyof AccessibilityValue)[] = [
+  'min',
+  'max',
+  'now',
+  'text',
+];
+
 export function isHiddenFromAccessibility(
   element: ReactTestInstance | null,
   { cache }: IsInaccessibleOptions = {}
diff --git a/src/helpers/matchers/accessibilityValue.ts b/src/helpers/matchers/accessibilityValue.ts
@@ -0,0 +1,24 @@
+import { AccessibilityValue } from 'react-native';
+import { ReactTestInstance } from 'react-test-renderer';
+import { TextMatch } from '../../matches';
+import { matchStringProp } from './matchStringProp';
+
+export interface AccessibilityValueMatcher {
+  min?: number;
+  max?: number;
+  now?: number;
+  text?: TextMatch;
+}
+
+export function matchAccessibilityValue(
+  node: ReactTestInstance,
+  matcher: AccessibilityValueMatcher
+): boolean {
+  const value = (node.props.accessibilityValue ?? {}) as AccessibilityValue;
+  return (
+    (matcher.min === undefined || matcher.min === value.min) &&
+    (matcher.max === undefined || matcher.max === value.max) &&
+    (matcher.now === undefined || matcher.now === value.now) &&
+    (matcher.text === undefined || matchStringProp(value.text, matcher.text))
+  );
+}
diff --git a/src/queries/__tests__/a11yValue.test.tsx b/src/queries/__tests__/a11yValue.test.tsx
@@ -4,14 +4,6 @@ import { render } from '../..';
 
 const TEXT_LABEL = 'cool text';
 
-const getMultipleInstancesFoundMessage = (value: string) => {
-  return `Found multiple elements with accessibilityValue: ${value}`;
-};
-
-const getNoInstancesFoundMessage = (value: string) => {
-  return `Unable to find an element with accessibilityValue: ${value}`;
-};
-
 const Typography = ({ children, ...rest }: any) => {
   return <Text {...rest}>{children}</Text>;
 };
@@ -46,15 +38,15 @@ test('getByA11yValue, queryByA11yValue, findByA11yValue', async () => {
   });
 
   expect(() => getByA11yValue({ min: 50 })).toThrow(
-    getNoInstancesFoundMessage('{"min":50}')
+    'Unable to find an element with min value: 50'
   );
   expect(queryByA11yValue({ min: 50 })).toEqual(null);
 
   expect(() => getByA11yValue({ max: 60 })).toThrow(
-    getMultipleInstancesFoundMessage('{"max":60}')
+    'Found multiple elements with max value: 60'
   );
   expect(() => queryByA11yValue({ max: 60 })).toThrow(
-    getMultipleInstancesFoundMessage('{"max":60}')
+    'Found multiple elements with max value: 60'
   );
 
   const asyncElement = await findByA11yValue({ min: 40 });
@@ -63,10 +55,10 @@ test('getByA11yValue, queryByA11yValue, findByA11yValue', async () => {
     max: 60,
   });
   await expect(findByA11yValue({ min: 50 })).rejects.toThrow(
-    getNoInstancesFoundMessage('{"min":50}')
+    'Unable to find an element with min value: 50'
   );
   await expect(findByA11yValue({ max: 60 })).rejects.toThrow(
-    getMultipleInstancesFoundMessage('{"max":60}')
+    'Found multiple elements with max value: 60'
   );
 });
 
@@ -79,7 +71,7 @@ test('getAllByA11yValue, queryAllByA11yValue, findAllByA11yValue', async () => {
   expect(queryAllByA11yValue({ min: 40 })).toHaveLength(1);
 
   expect(() => getAllByA11yValue({ min: 50 })).toThrow(
-    getNoInstancesFoundMessage('{"min":50}')
+    'Unable to find an element with min value: 50'
   );
   expect(queryAllByA11yValue({ min: 50 })).toEqual([]);
 
@@ -88,7 +80,7 @@ test('getAllByA11yValue, queryAllByA11yValue, findAllByA11yValue', async () => {
 
   await expect(findAllByA11yValue({ min: 40 })).resolves.toHaveLength(1);
   await expect(findAllByA11yValue({ min: 50 })).rejects.toThrow(
-    getNoInstancesFoundMessage('{"min":50}')
+    'Unable to find an element with min value: 50'
   );
   await expect(findAllByA11yValue({ max: 60 })).resolves.toHaveLength(2);
 });
diff --git a/src/queries/__tests__/role-value.test.tsx b/src/queries/__tests__/role-value.test.tsx
@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { View } from 'react-native';
+import { render } from '../..';
+
+describe('accessibility value', () => {
+  test('matches using all value props', () => {
+    const { getByRole, queryByRole } = render(
+      <View
+        accessibilityRole="adjustable"
+        accessibilityValue={{ min: 0, max: 100, now: 50, text: '50%' }}
+      />
+    );
+
+    expect(
+      getByRole('adjustable', {
+        value: { min: 0, max: 100, now: 50, text: '50%' },
+      })
+    ).toBeTruthy();
+    expect(
+      queryByRole('adjustable', {
+        value: { min: 1, max: 100, now: 50, text: '50%' },
+      })
+    ).toBeFalsy();
+    expect(
+      queryByRole('adjustable', {
+        value: { min: 0, max: 99, now: 50, text: '50%' },
+      })
+    ).toBeFalsy();
+    expect(
+      queryByRole('adjustable', {
+        value: { min: 0, max: 100, now: 45, text: '50%' },
+      })
+    ).toBeFalsy();
+    expect(
+      queryByRole('adjustable', {
+        value: { min: 0, max: 100, now: 50, text: '55%' },
+      })
+    ).toBeFalsy();
+  });
+
+  test('matches using single value', () => {
+    const { getByRole, queryByRole } = render(
+      <View
+        accessibilityRole="adjustable"
+        accessibilityValue={{ min: 10, max: 20, now: 12, text: 'Hello' }}
+      />
+    );
+
+    expect(getByRole('adjustable', { value: { min: 10 } })).toBeTruthy();
+    expect(getByRole('adjustable', { value: { max: 20 } })).toBeTruthy();
+    expect(getByRole('adjustable', { value: { now: 12 } })).toBeTruthy();
+    expect(getByRole('adjustable', { value: { text: 'Hello' } })).toBeTruthy();
+    expect(getByRole('adjustable', { value: { text: /hello/i } })).toBeTruthy();
+
+    expect(queryByRole('adjustable', { value: { min: 11 } })).toBeFalsy();
+    expect(queryByRole('adjustable', { value: { max: 19 } })).toBeFalsy();
+    expect(queryByRole('adjustable', { value: { now: 15 } })).toBeFalsy();
+    expect(queryByRole('adjustable', { value: { text: 'No' } })).toBeFalsy();
+    expect(queryByRole('adjustable', { value: { text: /no/ } })).toBeFalsy();
+  });
+});
diff --git a/src/queries/__tests__/role.test.tsx b/src/queries/__tests__/role.test.tsx
@@ -696,6 +696,24 @@ describe('error messages', () => {
       `"Unable to find an element with role: "button", disabled state: true"`
     );
   });
+
+  test('gives a descriptive error message when querying with a role and an accessibility value', () => {
+    const { getByRole } = render(<View />);
+
+    expect(() =>
+      getByRole('adjustable', { value: { min: 1 } })
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"Unable to find an element with role: "adjustable", min value: 1"`
+    );
+
+    expect(() =>
+      getByRole('adjustable', {
+        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/"`
+    );
+  });
 });
 
 test('byRole queries support hidden option', () => {
diff --git a/src/queries/a11yValue.ts b/src/queries/a11yValue.ts
@@ -1,6 +1,10 @@
 import type { ReactTestInstance } from 'react-test-renderer';
+import { accessiblityValueKeys } from '../helpers/accessiblity';
 import { findAll } from '../helpers/findAll';
-import { matchObjectProp } from '../helpers/matchers/matchObjectProp';
+import {
+  AccessibilityValueMatcher,
+  matchAccessibilityValue,
+} from '../helpers/matchers/accessibilityValue';
 import { makeQueries } from './makeQueries';
 import type {
   FindAllByQuery,
@@ -12,33 +16,38 @@ import type {
 } from './makeQueries';
 import { CommonQueryOptions } from './options';
 
-type A11yValue = {
-  min?: number;
-  max?: number;
-  now?: number;
-  text?: string;
-};
-
 const queryAllByA11yValue = (
   instance: ReactTestInstance
 ): ((
-  value: A11yValue,
+  value: AccessibilityValueMatcher,
   queryOptions?: CommonQueryOptions
 ) => Array<ReactTestInstance>) =>
   function queryAllByA11yValueFn(value, queryOptions) {
     return findAll(
       instance,
       (node) =>
-        typeof node.type === 'string' &&
-        matchObjectProp(node.props.accessibilityValue, value),
+        typeof node.type === 'string' && matchAccessibilityValue(node, value),
       queryOptions
     );
   };
 
-const getMultipleError = (value: A11yValue) =>
-  `Found multiple elements with accessibilityValue: ${JSON.stringify(value)} `;
-const getMissingError = (value: A11yValue) =>
-  `Unable to find an element with accessibilityValue: ${JSON.stringify(value)}`;
+const buildErrorMessage = (value: AccessibilityValueMatcher) => {
+  const errors: string[] = [];
+
+  accessiblityValueKeys.forEach((valueKey) => {
+    if (value[valueKey] !== undefined) {
+      errors.push(`${valueKey} value: ${value[valueKey]}`);
+    }
+  });
+
+  return errors.join(', ');
+};
+
+const getMultipleError = (value: AccessibilityValueMatcher) =>
+  `Found multiple elements with ${buildErrorMessage(value)}`;
+
+const getMissingError = (value: AccessibilityValueMatcher) =>
+  `Unable to find an element with ${buildErrorMessage(value)}`;
 
 const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
   queryAllByA11yValue,
@@ -47,19 +56,46 @@ const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
 );
 
 export type ByA11yValueQueries = {
-  getByA11yValue: GetByQuery<A11yValue, CommonQueryOptions>;
-  getAllByA11yValue: GetAllByQuery<A11yValue, CommonQueryOptions>;
-  queryByA11yValue: QueryByQuery<A11yValue, CommonQueryOptions>;
-  queryAllByA11yValue: QueryAllByQuery<A11yValue, CommonQueryOptions>;
-  findByA11yValue: FindByQuery<A11yValue, CommonQueryOptions>;
-  findAllByA11yValue: FindAllByQuery<A11yValue, CommonQueryOptions>;
+  getByA11yValue: GetByQuery<AccessibilityValueMatcher, CommonQueryOptions>;
+  getAllByA11yValue: GetAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  queryByA11yValue: QueryByQuery<AccessibilityValueMatcher, CommonQueryOptions>;
+  queryAllByA11yValue: QueryAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  findByA11yValue: FindByQuery<AccessibilityValueMatcher, CommonQueryOptions>;
+  findAllByA11yValue: FindAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
 
-  getByAccessibilityValue: GetByQuery<A11yValue, CommonQueryOptions>;
-  getAllByAccessibilityValue: GetAllByQuery<A11yValue, CommonQueryOptions>;
-  queryByAccessibilityValue: QueryByQuery<A11yValue, CommonQueryOptions>;
-  queryAllByAccessibilityValue: QueryAllByQuery<A11yValue, CommonQueryOptions>;
-  findByAccessibilityValue: FindByQuery<A11yValue, CommonQueryOptions>;
-  findAllByAccessibilityValue: FindAllByQuery<A11yValue, CommonQueryOptions>;
+  getByAccessibilityValue: GetByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  getAllByAccessibilityValue: GetAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  queryByAccessibilityValue: QueryByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  queryAllByAccessibilityValue: QueryAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  findByAccessibilityValue: FindByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
+  findAllByAccessibilityValue: FindAllByQuery<
+    AccessibilityValueMatcher,
+    CommonQueryOptions
+  >;
 };
 
 export const bindByA11yValueQueries = (
diff --git a/src/queries/role.ts b/src/queries/role.ts
diff --git a/typings/index.flow.js b/typings/index.flow.js
diff --git a/website/docs/Queries.md b/website/docs/Queries.md
