feat: add a11y queries

docs/Queries.md

@@ -83,6 +83,63 @@ const { getByTestId } = render(<MyComponent />);
 const element = getByTestId('unique-id');
 ```
 
+### `ByA11yLabel`, `ByAccessibilityLabel`
+
+> getByA11yLabel, getAllByA11yLabel, queryByA11yLabel, queryAllByA11yLabel
+> getByAccessibilityLabel, getAllByAccessibilityLabel, queryByAccessibilityLabel, queryAllByAccessibilityLabel
+
+Returns a `ReactTestInstance` with matching `accessibilityLabel` prop.
+
+```jsx
+import { render } from 'react-native-testing-library';
+
+const { getByA11yLabel } = render(<MyComponent />);
+const element = getByA11yLabel('my-label');
+```
+
+### `ByA11yHint`, `ByAccessibilityHint`
+
+> getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint
+> getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint
+
+Returns a `ReactTestInstance` with matching `accessibilityHint` prop.
+
+```jsx
+import { render } from 'react-native-testing-library';
+
+const { getByA11yHint } = render(<MyComponent />);
+const element = getByA11yHint('my-hint');
+```
+
+### `ByA11yStates`, `ByAccessibilityStates`
+
+> getByA11yStates, getAllByA11yStates, queryByA11yStates, queryAllByA11yStates
+> getByAccessibilityStates, getAllByAccessibilityStates, queryByAccessibilityStates, queryAllByAccessibilityStates
+
+Returns a `ReactTestInstance` with matching `accessibilityStates` prop.
+
+```jsx
+import { render } from 'react-native-testing-library';
+
+const { getByA11yStates } = render(<MyComponent />);
+const element = getByA11yStates(['checked']);
+const element2 = getByA11yStates('checked');
+```
+
+### `ByA11yRole`, `ByAccessibilityRole`
+
+> getByA11yRole, getAllByA11yRole, queryByA11yRole, queryAllByA11yRole
+> getByAccessibilityRole, getAllByAccessibilityRole, queryByAccessibilityRole, queryAllByAccessibilityRole
+
+Returns a `ReactTestInstance` with matching `accessibilityRole` prop.
+
+```jsx
+import { render } from 'react-native-testing-library';
+
+const { getByA11yRole } = render(<MyComponent />);
+const element = getByA11yRole('button');
+```
+
 ## Unit testing helpers
 
 > Use sparingly and responsibly, escape hatches here

package.json

@@ -20,6 +20,7 @@
     "@callstack/eslint-config": "^6.0.0",
     "@types/react": "^16.7.11",
     "@types/react-test-renderer": "^16.0.3",
+    "@typescript-eslint/eslint-plugin": "^1.9.0",
     "babel-jest": "^24.7.1",
     "chalk": "^2.4.1",
     "conventional-changelog-cli": "^2.0.11",

src/__tests__/a11yAPI.test.js

@@ -0,0 +1,162 @@
+// @flow
+import React from 'react';
+import { TouchableOpacity, Text } from 'react-native';
+import { render } from '..';
+
+const BUTTON_LABEL = 'cool button';
+const BUTTON_HINT = 'click this button';
+const BUTTON_ROLE = 'button';
+const TEXT_LABEL = 'cool text';
+const TEXT_HINT = 'static text';
+const TEXT_ROLE = 'link';
+const NO_MATCHES_TEXT = 'not-existent-element';
+
+const NO_INSTANCES_FOUND = 'No instances found';
+const FOUND_TWO_INSTANCES = 'Expected 1 but found 2 instances';
+
+const Typography = ({ children, ...rest }) => {
+  return <Text {...rest}>{children}</Text>;
+};
+
+class Button extends React.Component<*> {
+  render() {
+    return (
+      <TouchableOpacity
+        accessibilityHint={BUTTON_HINT}
+        accessibilityLabel={BUTTON_LABEL}
+        accessibilityRole={BUTTON_ROLE}
+        accessibilityStates={['selected']}
+      >
+        <Typography
+          accessibilityHint={TEXT_HINT}
+          accessibilityLabel={TEXT_LABEL}
+          accessibilityRole={TEXT_ROLE}
+          accessibilityStates={['selected']}
+        >
+          {this.props.children}
+        </Typography>
+      </TouchableOpacity>
+    );
+  }
+}
+
+function Section() {
+  return (
+    <>
+      <Typography
+        accessibilityHint={TEXT_HINT}
+        accessibilityLabel={TEXT_LABEL}
+        accessibilityRole={TEXT_ROLE}
+        accessibilityStates={['selected', 'disabled']}
+      >
+        Title
+      </Typography>
+      <Button>{TEXT_LABEL}</Button>
+    </>
+  );
+}
+
+test('getByA11yLabel, queryByA11yLabel', () => {
+  const { getByA11yLabel, queryByA11yLabel } = render(<Section />);
+
+  expect(getByA11yLabel(BUTTON_LABEL).props.accessibilityLabel).toEqual(
+    BUTTON_LABEL
+  );
+  const button = queryByA11yLabel(/button/g);
+  expect(button && button.props.accessibilityLabel).toEqual(BUTTON_LABEL);
+  expect(() => getByA11yLabel(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryByA11yLabel(NO_MATCHES_TEXT)).toBeNull();
+
+  expect(() => getByA11yLabel(TEXT_LABEL)).toThrow(FOUND_TWO_INSTANCES);
+  expect(() => queryByA11yLabel(TEXT_LABEL)).toThrow(FOUND_TWO_INSTANCES);
+});
+
+test('getAllByA11yLabel, queryAllByA11yLabel', () => {
+  const { getAllByA11yLabel, queryAllByA11yLabel } = render(<Section />);
+
+  expect(getAllByA11yLabel(TEXT_LABEL)).toHaveLength(2);
+  expect(queryAllByA11yLabel(/cool/g)).toHaveLength(3);
+  expect(() => getAllByA11yLabel(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryAllByA11yLabel(NO_MATCHES_TEXT)).toEqual([]);
+});
+
+test('getByA11yHint, queryByA11yHint', () => {
+  const { getByA11yHint, queryByA11yHint } = render(<Section />);
+
+  expect(getByA11yHint(BUTTON_HINT).props.accessibilityHint).toEqual(
+    BUTTON_HINT
+  );
+  const button = queryByA11yHint(/button/g);
+  expect(button && button.props.accessibilityHint).toEqual(BUTTON_HINT);
+  expect(() => getByA11yHint(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryByA11yHint(NO_MATCHES_TEXT)).toBeNull();
+
+  expect(() => getByA11yHint(TEXT_HINT)).toThrow(FOUND_TWO_INSTANCES);
+  expect(() => queryByA11yHint(TEXT_HINT)).toThrow(FOUND_TWO_INSTANCES);
+});
+
+test('getAllByA11yHint, queryAllByA11yHint', () => {
+  const { getAllByA11yHint, queryAllByA11yHint } = render(<Section />);
+
+  expect(getAllByA11yHint(TEXT_HINT)).toHaveLength(2);
+  expect(queryAllByA11yHint(/static/g)).toHaveLength(2);
+  expect(() => getAllByA11yHint(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryAllByA11yHint(NO_MATCHES_TEXT)).toEqual([]);
+});
+
+test('getByA11yRole, queryByA11yRole', () => {
+  const { getByA11yRole, queryByA11yRole } = render(<Section />);
+
+  expect(getByA11yRole('button').props.accessibilityRole).toEqual('button');
+  const button = queryByA11yRole(/button/g);
+  expect(button && button.props.accessibilityRole).toEqual('button');
+  expect(() => getByA11yRole(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryByA11yRole(NO_MATCHES_TEXT)).toBeNull();
+
+  expect(() => getByA11yRole('link')).toThrow(FOUND_TWO_INSTANCES);
+  expect(() => queryByA11yRole('link')).toThrow(FOUND_TWO_INSTANCES);
+});
+
+test('getAllByA11yRole, queryAllByA11yRole', () => {
+  const { getAllByA11yRole, queryAllByA11yRole } = render(<Section />);
+
+  expect(getAllByA11yRole('link')).toHaveLength(2);
+  expect(queryAllByA11yRole(/ink/g)).toHaveLength(2);
+  expect(() => getAllByA11yRole(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryAllByA11yRole(NO_MATCHES_TEXT)).toEqual([]);
+});
+
+test('getByA11yStates, queryByA11yStates', () => {
+  const { getByA11yStates, queryByA11yStates } = render(<Section />);
+
+  expect(getByA11yStates('disabled').props.accessibilityStates).toEqual([
+    'selected',
+    'disabled',
+  ]);
+  const disabled = queryByA11yStates(['disabled']);
+  expect(disabled && disabled.props.accessibilityStates).toMatchObject([
+    'selected',
+    'disabled',
+  ]);
+  const disabledSelected = queryByA11yStates(['selected', 'disabled']);
+  expect(
+    disabledSelected && disabledSelected.props.accessibilityStates
+  ).toEqual(['selected', 'disabled']);
+
+  expect(() => getByA11yStates(NO_MATCHES_TEXT)).toThrow(NO_INSTANCES_FOUND);
+  expect(queryByA11yStates(NO_MATCHES_TEXT)).toBeNull();
+  expect(queryByA11yStates([])).toBeNull();
+
+  expect(() => getByA11yStates('selected')).toThrow(FOUND_TWO_INSTANCES);
+  expect(() => queryByA11yStates('selected')).toThrow(FOUND_TWO_INSTANCES);
+});
+
+test('getAllByA11yStates, queryAllByA11yStates', () => {
+  const { getAllByA11yStates, queryAllByA11yStates } = render(<Section />);
+
+  expect(getAllByA11yStates('selected')).toHaveLength(3);
+  expect(queryAllByA11yStates(['selected'])).toHaveLength(3);
+
+  expect(() => getAllByA11yStates([])).toThrow(NO_INSTANCES_FOUND);
+  expect(queryAllByA11yStates(NO_MATCHES_TEXT)).toEqual([]);
+});

src/helpers/a11yAPI.js

@@ -0,0 +1,102 @@
+// @flow
+import makeQuery from './makeQuery';
+
+type QueryFn = (string | RegExp) => ReactTestInstance | null;
+type GetFn = (string | RegExp) => ReactTestInstance;
+type GetAllFn = (string | RegExp) => Array<ReactTestInstance> | [];
+type ArrayQueryFn = (string | Array<string>) => ReactTestInstance | null;
+type ArrayGetFn = (string | Array<string>) => ReactTestInstance;
+type ArrayGetAllFn = (string | Array<string>) => Array<ReactTestInstance> | [];
+
+type A11yAPI = {
+  getByA11yLabel: GetFn,
+  getAllByA11yLabel: GetAllFn,
+  queryByA11yLabel: QueryFn,
+  queryAllByA11yLabel: GetAllFn,
+  getByA11yHint: GetFn,
+  getAllByA11yHint: GetAllFn,
+  queryByA11yHint: QueryFn,
+  queryAllByA11yHint: GetAllFn,
+  getByA11yRole: GetFn,
+  getAllByA11yRole: GetAllFn,
+  queryByA11yRole: QueryFn,
+  queryAllByA11yRole: GetAllFn,
+  getByA11yStates: ArrayGetFn,
+  getAllByA11yStates: ArrayGetAllFn,
+  queryByA11yStates: ArrayQueryFn,
+  queryAllByA11yStates: ArrayGetAllFn,
+};
+
+export function matchStringValue(prop?: string, matcher: string | RegExp) {
+  if (!prop) {
+    return false;
+  }
+
+  if (typeof matcher === 'string') {
+    return prop === matcher;
+  }
+
+  return Boolean(prop.match(matcher));
+}
+
+export function matchArrayValue(
+  prop?: Array<string>,
+  matcher: string | Array<string>
+) {
+  if (!prop || matcher.length === 0) {
+    return false;
+  }
+
+  if (typeof matcher === 'string') {
+    return prop.includes(matcher);
+  }
+
+  // $FlowFixMe - callback is sync hence prop exists
+  return !matcher.some(e => !prop.includes(e));
+}
+
+const a11yAPI = (instance: ReactTestInstance): A11yAPI =>
+  ({
+    ...makeQuery(
+      'accessibilityLabel',
+      {
+        getBy: ['getByA11yLabel', 'getByAccessibilityLabel'],
+        getAllBy: ['getAllByA11yLabel', 'getAllByAccessibilityLabel'],
+        queryBy: ['queryByA11yLabel', 'queryByAccessibilityLabel'],
+        queryAllBy: ['queryAllByA11yLabel', 'queryAllByAccessibilityLabel'],
+      },
+      matchStringValue
+    )(instance),
+    ...makeQuery(
+      'accessibilityHint',
+      {
+        getBy: ['getByA11yHint', 'getByAccessibilityHint'],
+        getAllBy: ['getAllByA11yHint', 'getAllByAccessibilityHint'],
+        queryBy: ['queryByA11yHint', 'queryByAccessibilityHint'],
+        queryAllBy: ['queryAllByA11yHint', 'queryAllByAccessibilityHint'],
+      },
+      matchStringValue
+    )(instance),
+    ...makeQuery(
+      'accessibilityRole',
+      {
+        getBy: ['getByA11yRole', 'getByAccessibilityRole'],
+        getAllBy: ['getAllByA11yRole', 'getAllByAccessibilityRole'],
+        queryBy: ['queryByA11yRole', 'queryByAccessibilityRole'],
+        queryAllBy: ['queryAllByA11yRole', 'queryAllByAccessibilityRole'],
+      },
+      matchStringValue
+    )(instance),
+    ...makeQuery(
+      'accessibilityStates',
+      {
+        getBy: ['getByA11yStates', 'getByAccessibilityStates'],
+        getAllBy: ['getAllByA11yStates', 'getAllByAccessibilityStates'],
+        queryBy: ['queryByA11yStates', 'queryByAccessibilityStates'],
+        queryAllBy: ['queryAllByA11yStates', 'queryAllByAccessibilityStates'],
+      },
+      matchArrayValue
+    )(instance),
+  }: any);
+
+export default a11yAPI;

src/helpers/errors.js

@@ -38,3 +38,14 @@ export const logDeprecationWarning = (
 
   warned[deprecatedFnName] = true;
 };
+
+export const prepareErrorMessage = (error: Error) =>
+  // Strip info about custom predicate
+  error.message.replace(/ matching custom predicate[^]*/gm, '');
+
+export const createQueryByError = (error: Error, callsite: Function) => {
+  if (error.message.includes('No instances found')) {
+    return null;
+  }
+  throw new ErrorWithStack(error.message, callsite);
+};

src/helpers/getByAPI.js

@@ -5,6 +5,7 @@ import {
   ErrorWithStack,
   createLibraryNotSupportedError,
   logDeprecationWarning,
+  prepareErrorMessage,
 } from './errors';
 
 const filterNodeByType = (node, type) => node.type === type;
@@ -53,10 +54,6 @@ const getTextInputNodeByPlaceholder = (node, placeholder) => {
   }
 };
 
-const prepareErrorMessage = error =>
-  // Strip info about custom predicate
-  error.message.replace(/ matching custom predicate[^]*/gm, '');
-
 export const getByName = (instance: ReactTestInstance) =>
   function getByNameFn(name: string | React.ComponentType<*>) {
     logDeprecationWarning('getByName', 'getByType');