feat: option for queries to respect accessibility

README.md

@@ -117,8 +117,8 @@ test('form submits two answers', () => {
   fireEvent.press(screen.getByText('Submit'));
 
   expect(mockFn).toBeCalledWith({
-    '1': { q: 'q1', a: 'a1' },
-    '2': { q: 'q2', a: 'a2' },
+    1: { q: 'q1', a: 'a1' },
+    2: { q: 'q2', a: 'a2' },
   });
 });
 ```
@@ -173,4 +173,4 @@ Supported and used by [Rally Health](https://www.rallyhealth.com/careers-home).
 [callstack-badge]: https://callstack.com/images/callstack-badge.svg
 [callstack]: https://callstack.com/open-source/?utm_source=github.com&utm_medium=referral&utm_campaign=react-native-testing-library&utm_term=readme
 [codecov-badge]: https://codecov.io/gh/callstack/react-native-testing-library/branch/main/graph/badge.svg?token=tYVSWro1IP
-[codecov]: https://codecov.io/gh/callstack/react-native-testing-library
+[codecov]: https://codecov.io/gh/callstack/react-native-testing-library

src/__tests__/config.test.ts

@@ -14,6 +14,7 @@ test('configure() overrides existing config values', () => {
   expect(getConfig()).toEqual({
     asyncUtilTimeout: 5000,
     defaultDebugOptions: { message: 'debug message' },
+    defaultHidden: true,
   });
 });
 

src/config.ts

@@ -4,17 +4,19 @@ export type Config = {
   /** Default timeout, in ms, for `waitFor` and `findBy*` queries. */
   asyncUtilTimeout: number;
 
+  /** Default hidden value for all queries */
+  defaultHidden: boolean;
+
   /** Default options for `debug` helper. */
   defaultDebugOptions?: Partial<DebugOptions>;
 };
 
 const defaultConfig: Config = {
   asyncUtilTimeout: 1000,
+  defaultHidden: true,
 };
 
-let config = {
-  ...defaultConfig,
-};
+let config = { ...defaultConfig };
 
 export function configure(options: Partial<Config>) {
   config = {
@@ -24,7 +26,7 @@ export function configure(options: Partial<Config>) {
 }
 
 export function resetToDefaults() {
-  config = defaultConfig;
+  config = { ...defaultConfig };
 }
 
 export function getConfig() {

src/helpers/accessiblity.ts

@@ -2,6 +2,10 @@ import { AccessibilityState, 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[] = [
@@ -12,14 +16,24 @@ export const accessibilityStateKeys: AccessibilityStateKey[] = [
   'expanded',
 ];
 
-export function isInaccessible(element: ReactTestInstance | null): boolean {
+export function isInaccessible(
+  element: ReactTestInstance | null,
+  { cache }: IsInaccessibleOptions = {}
+): boolean {
   if (element == null) {
     return true;
   }
 
   let current: ReactTestInstance | null = element;
   while (current) {
-    if (isSubtreeInaccessible(current)) {
+    let isCurrentSubtreeInaccessible = cache?.get(current);
+
+    if (isCurrentSubtreeInaccessible === undefined) {
+      isCurrentSubtreeInaccessible = isSubtreeInaccessible(current);
+      cache?.set(current, isCurrentSubtreeInaccessible);
+    }
+
+    if (isCurrentSubtreeInaccessible) {
       return true;
     }
 
@@ -29,7 +43,9 @@ export function isInaccessible(element: ReactTestInstance | null): boolean {
   return false;
 }
 
-function isSubtreeInaccessible(element: ReactTestInstance | null): boolean {
+export function isSubtreeInaccessible(
+  element: ReactTestInstance | null
+): boolean {
   if (element == null) {
     return true;
   }
@@ -46,7 +62,7 @@ function isSubtreeInaccessible(element: ReactTestInstance | null): boolean {
     return true;
   }
 
-  // Note that `opacity: 0` is not threated as inassessible on iOS
+  // Note that `opacity: 0` is not treated as inaccessible on iOS
   const flatStyle = StyleSheet.flatten(element.props.style) ?? {};
   if (flatStyle.display === 'none') return true;
 

src/helpers/findAll.ts

@@ -0,0 +1,23 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { getConfig } from '../config';
+import { isInaccessible } from './accessiblity';
+
+interface FindAllOptions {
+  hidden?: boolean;
+}
+
+export function findAll(
+  root: ReactTestInstance,
+  predicate: (node: ReactTestInstance) => boolean,
+  options?: FindAllOptions
+) {
+  const results = root.findAll(predicate);
+
+  const hidden = options?.hidden ?? getConfig().defaultHidden;
+  if (hidden) {
+    return results;
+  }
+
+  const cache = new WeakMap<ReactTestInstance>();
+  return results.filter((element) => !isInaccessible(element, { cache }));
+}

src/queries/__tests__/a11yState.test.tsx

@@ -226,3 +226,22 @@ test('*ByA11yState on TouchableOpacity with "disabled" prop', () => {
   expect(view.getByA11yState({ disabled: true })).toBeTruthy();
   expect(view.queryByA11yState({ disabled: false })).toBeFalsy();
 });
+
+test('byA11yState queries support hidden option', () => {
+  const { getByA11yState, queryByA11yState } = render(
+    <Pressable
+      accessibilityState={{ expanded: false }}
+      style={{ display: 'none' }}
+    >
+      <Text>Hidden from accessibility</Text>
+    </Pressable>
+  );
+
+  expect(getByA11yState({ expanded: false })).toBeTruthy();
+  expect(getByA11yState({ expanded: false }, { hidden: true })).toBeTruthy();
+
+  expect(queryByA11yState({ expanded: false }, { hidden: false })).toBeFalsy();
+  expect(() =>
+    getByA11yState({ expanded: false }, { hidden: false })
+  ).toThrow();
+});

src/queries/__tests__/a11yValue.test.tsx

@@ -92,3 +92,17 @@ test('getAllByA11yValue, queryAllByA11yValue, findAllByA11yValue', async () => {
   );
   await expect(findAllByA11yValue({ max: 60 })).resolves.toHaveLength(2);
 });
+
+test('byA11yValue queries support hidden option', () => {
+  const { getByA11yValue, queryByA11yValue } = render(
+    <Text accessibilityValue={{ max: 10 }} style={{ display: 'none' }}>
+      Hidden from accessibility
+    </Text>
+  );
+
+  expect(getByA11yValue({ max: 10 })).toBeTruthy();
+  expect(getByA11yValue({ max: 10 }, { hidden: true })).toBeTruthy();
+
+  expect(queryByA11yValue({ max: 10 }, { hidden: false })).toBeFalsy();
+  expect(() => getByA11yValue({ max: 10 }, { hidden: false })).toThrow();
+});

src/queries/__tests__/displayValue.test.tsx

@@ -99,3 +99,15 @@ test('findBy queries work asynchronously', async () => {
   await expect(findByDisplayValue('Display Value')).resolves.toBeTruthy();
   await expect(findAllByDisplayValue('Display Value')).resolves.toHaveLength(1);
 }, 20000);
+
+test('byDisplayValue queries support hidden option', () => {
+  const { getByDisplayValue, queryByDisplayValue } = render(
+    <TextInput value="hidden" style={{ display: 'none' }} />
+  );
+
+  expect(getByDisplayValue('hidden')).toBeTruthy();
+  expect(getByDisplayValue('hidden', { hidden: true })).toBeTruthy();
+
+  expect(queryByDisplayValue('hidden', { hidden: false })).toBeFalsy();
+  expect(() => getByDisplayValue('hidden', { hidden: false })).toThrow();
+});

src/queries/__tests__/hintText.test.tsx

@@ -106,3 +106,17 @@ test('getByHintText, getByHintText and exact = true', () => {
   expect(queryByHintText('id', { exact: true })).toBeNull();
   expect(getAllByHintText('test', { exact: true })).toHaveLength(1);
 });
+
+test('byHintText queries support hidden option', () => {
+  const { getByHintText, queryByHintText } = render(
+    <Text accessibilityHint="hidden" style={{ display: 'none' }}>
+      Hidden from accessiblity
+    </Text>
+  );
+
+  expect(getByHintText('hidden')).toBeTruthy();
+  expect(getByHintText('hidden', { hidden: true })).toBeTruthy();
+
+  expect(queryByHintText('hidden', { hidden: false })).toBeFalsy();
+  expect(() => getByHintText('hidden', { hidden: false })).toThrow();
+});

src/queries/__tests__/labelText.test.tsx

@@ -143,3 +143,17 @@ describe('findBy options deprecations', () => {
     );
   }, 20000);
 });
+
+test('byLabelText queries support hidden option', () => {
+  const { getByLabelText, queryByLabelText } = render(
+    <Text accessibilityLabel="hidden" style={{ display: 'none' }}>
+      Hidden from accessibility
+    </Text>
+  );
+
+  expect(getByLabelText('hidden')).toBeTruthy();
+  expect(getByLabelText('hidden', { hidden: true })).toBeTruthy();
+
+  expect(queryByLabelText('hidden', { hidden: false })).toBeFalsy();
+  expect(() => getByLabelText('hidden', { hidden: false })).toThrow();
+});

src/queries/__tests__/placeholderText.test.tsx

@@ -58,3 +58,15 @@ test('getAllByPlaceholderText, queryAllByPlaceholderText', () => {
   expect(queryAllByPlaceholderText(/fresh/i)).toEqual(inputs);
   expect(queryAllByPlaceholderText('no placeholder')).toHaveLength(0);
 });
+
+test('byPlaceholderText queries support hidden option', () => {
+  const { getByPlaceholderText, queryByPlaceholderText } = render(
+    <TextInput placeholder="hidden" style={{ display: 'none' }} />
+  );
+
+  expect(getByPlaceholderText('hidden')).toBeTruthy();
+  expect(getByPlaceholderText('hidden', { hidden: true })).toBeTruthy();
+
+  expect(queryByPlaceholderText('hidden', { hidden: false })).toBeFalsy();
+  expect(() => getByPlaceholderText('hidden', { hidden: false })).toThrow();
+});

src/queries/__tests__/role.test.tsx

@@ -697,3 +697,17 @@ describe('error messages', () => {
     );
   });
 });
+
+test('byRole queries support hidden option', () => {
+  const { getByRole, queryByRole } = render(
+    <Pressable accessibilityRole="button" style={{ display: 'none' }}>
+      <Text>Hidden from accessibility</Text>
+    </Pressable>
+  );
+
+  expect(getByRole('button')).toBeTruthy();
+  expect(getByRole('button', { hidden: true })).toBeTruthy();
+
+  expect(queryByRole('button', { hidden: false })).toBeFalsy();
+  expect(() => getByRole('button', { hidden: false })).toThrow();
+});

src/queries/__tests__/testId.test.tsx

@@ -132,3 +132,17 @@ test('findByTestId and findAllByTestId work asynchronously', async () => {
   await expect(findByTestId('aTestId')).resolves.toBeTruthy();
   await expect(findAllByTestId('aTestId')).resolves.toHaveLength(1);
 }, 20000);
+
+test('byTestId queries support hidden option', () => {
+  const { getByTestId, queryByTestId } = render(
+    <Text style={{ display: 'none' }} testID="hidden">
+      Hidden from accessibility
+    </Text>
+  );
+
+  expect(getByTestId('hidden')).toBeTruthy();
+  expect(getByTestId('hidden', { hidden: true })).toBeTruthy();
+
+  expect(queryByTestId('hidden', { hidden: false })).toBeFalsy();
+  expect(() => getByTestId('hidden', { hidden: false })).toThrow();
+});

src/queries/__tests__/text.test.tsx

@@ -466,3 +466,15 @@ test('getByText searches for text within self host element', () => {
   const textNode = within(getByTestId('subject'));
   expect(textNode.getByText('Hello')).toBeTruthy();
 });
+
+test('byText support hidden option', () => {
+  const { getByText, queryByText } = render(
+    <Text style={{ display: 'none' }}>Hidden from accessibility</Text>
+  );
+
+  expect(getByText(/hidden/i)).toBeTruthy();
+  expect(getByText(/hidden/i, { hidden: true })).toBeTruthy();
+
+  expect(queryByText(/hidden/i, { hidden: false })).toBeFalsy();
+  expect(() => getByText(/hidden/i, { hidden: false })).toThrow();
+});

src/queries/a11yState.ts

@@ -1,6 +1,7 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import type { AccessibilityState } from 'react-native';
+import { AccessibilityState } from 'react-native';
 import { accessibilityStateKeys } from '../helpers/accessiblity';
+import { findAll } from '../helpers/findAll';
 import { matchAccessibilityState } from '../helpers/matchers/accessibilityState';
 import { makeQueries } from './makeQueries';
 import type {
@@ -11,14 +12,20 @@ import type {
   QueryAllByQuery,
   QueryByQuery,
 } from './makeQueries';
+import { CommonQueryOptions } from './options';
 
 const queryAllByA11yState = (
   instance: ReactTestInstance
-): ((matcher: AccessibilityState) => Array<ReactTestInstance>) =>
-  function queryAllByA11yStateFn(matcher) {
-    return instance.findAll(
+): ((
+  matcher: AccessibilityState,
+  queryOptions?: CommonQueryOptions
+) => Array<ReactTestInstance>) =>
+  function queryAllByA11yStateFn(matcher, queryOptions) {
+    return findAll(
+      instance,
       (node) =>
-        typeof node.type === 'string' && matchAccessibilityState(node, matcher)
+        typeof node.type === 'string' && matchAccessibilityState(node, matcher),
+      queryOptions
     );
   };
 
@@ -47,19 +54,31 @@ const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
 );
 
 export type ByA11yStateQueries = {
-  getByA11yState: GetByQuery<AccessibilityState>;
-  getAllByA11yState: GetAllByQuery<AccessibilityState>;
-  queryByA11yState: QueryByQuery<AccessibilityState>;
-  queryAllByA11yState: QueryAllByQuery<AccessibilityState>;
-  findByA11yState: FindByQuery<AccessibilityState>;
-  findAllByA11yState: FindAllByQuery<AccessibilityState>;
+  getByA11yState: GetByQuery<AccessibilityState, CommonQueryOptions>;
+  getAllByA11yState: GetAllByQuery<AccessibilityState, CommonQueryOptions>;
+  queryByA11yState: QueryByQuery<AccessibilityState, CommonQueryOptions>;
+  queryAllByA11yState: QueryAllByQuery<AccessibilityState, CommonQueryOptions>;
+  findByA11yState: FindByQuery<AccessibilityState, CommonQueryOptions>;
+  findAllByA11yState: FindAllByQuery<AccessibilityState, CommonQueryOptions>;
 
-  getByAccessibilityState: GetByQuery<AccessibilityState>;
-  getAllByAccessibilityState: GetAllByQuery<AccessibilityState>;
-  queryByAccessibilityState: QueryByQuery<AccessibilityState>;
-  queryAllByAccessibilityState: QueryAllByQuery<AccessibilityState>;
-  findByAccessibilityState: FindByQuery<AccessibilityState>;
-  findAllByAccessibilityState: FindAllByQuery<AccessibilityState>;
+  getByAccessibilityState: GetByQuery<AccessibilityState, CommonQueryOptions>;
+  getAllByAccessibilityState: GetAllByQuery<
+    AccessibilityState,
+    CommonQueryOptions
+  >;
+  queryByAccessibilityState: QueryByQuery<
+    AccessibilityState,
+    CommonQueryOptions
+  >;
+  queryAllByAccessibilityState: QueryAllByQuery<
+    AccessibilityState,
+    CommonQueryOptions
+  >;
+  findByAccessibilityState: FindByQuery<AccessibilityState, CommonQueryOptions>;
+  findAllByAccessibilityState: FindAllByQuery<
+    AccessibilityState,
+    CommonQueryOptions
+  >;
 };
 
 export const bindByA11yStateQueries = (