fix: *ByA11yState default value false value for busy, disabled & selected state

src/queries/__tests__/a11yState.test.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { TouchableOpacity, Text } from 'react-native';
+import { View, Text, Pressable, TouchableOpacity } from 'react-native';
 import { render } from '../..';
 
 const TEXT_LABEL = 'cool text';
@@ -96,3 +96,141 @@ test('getAllByA11yState, queryAllByA11yState, findAllByA11yState', async () => {
     2
   );
 });
+
+describe('checked state matching', () => {
+  it('handles true', () => {
+    const view = render(<View accessibilityState={{ checked: true }} />);
+
+    expect(view.getByA11yState({ checked: true })).toBeTruthy();
+    expect(view.queryByA11yState({ checked: 'mixed' })).toBeFalsy();
+    expect(view.queryByA11yState({ checked: false })).toBeFalsy();
+  });
+
+  it('handles mixed', () => {
+    const view = render(<View accessibilityState={{ checked: 'mixed' }} />);
+
+    expect(view.getByA11yState({ checked: 'mixed' })).toBeTruthy();
+    expect(view.queryByA11yState({ checked: true })).toBeFalsy();
+    expect(view.queryByA11yState({ checked: false })).toBeFalsy();
+  });
+
+  it('handles false', () => {
+    const view = render(<View accessibilityState={{ checked: false }} />);
+
+    expect(view.getByA11yState({ checked: false })).toBeTruthy();
+    expect(view.queryByA11yState({ checked: true })).toBeFalsy();
+    expect(view.queryByA11yState({ checked: 'mixed' })).toBeFalsy();
+  });
+
+  it('handles  default', () => {
+    const view = render(<View accessibilityState={{}} />);
+
+    expect(view.queryByA11yState({ checked: false })).toBeFalsy();
+    expect(view.queryByA11yState({ checked: true })).toBeFalsy();
+    expect(view.queryByA11yState({ checked: 'mixed' })).toBeFalsy();
+  });
+});
+
+describe('expanded state matching', () => {
+  it('handles true', () => {
+    const view = render(<View accessibilityState={{ expanded: true }} />);
+
+    expect(view.getByA11yState({ expanded: true })).toBeTruthy();
+    expect(view.queryByA11yState({ expanded: false })).toBeFalsy();
+  });
+
+  it('handles false', () => {
+    const view = render(<View accessibilityState={{ expanded: false }} />);
+
+    expect(view.getByA11yState({ expanded: false })).toBeTruthy();
+    expect(view.queryByA11yState({ expanded: true })).toBeFalsy();
+  });
+
+  it('handles  default', () => {
+    const view = render(<View accessibilityState={{}} />);
+
+    expect(view.queryByA11yState({ expanded: false })).toBeFalsy();
+    expect(view.queryByA11yState({ expanded: true })).toBeFalsy();
+  });
+});
+
+describe('disabled state matching', () => {
+  it('handles true', () => {
+    const view = render(<View accessibilityState={{ disabled: true }} />);
+
+    expect(view.getByA11yState({ disabled: true })).toBeTruthy();
+    expect(view.queryByA11yState({ disabled: false })).toBeFalsy();
+  });
+
+  it('handles false', () => {
+    const view = render(<View accessibilityState={{ disabled: false }} />);
+
+    expect(view.getByA11yState({ disabled: false })).toBeTruthy();
+    expect(view.queryByA11yState({ disabled: true })).toBeFalsy();
+  });
+
+  it('handles  default', () => {
+    const view = render(<View accessibilityState={{}} />);
+
+    expect(view.getByA11yState({ disabled: false })).toBeTruthy();
+    expect(view.queryByA11yState({ disabled: true })).toBeFalsy();
+  });
+});
+
+describe('busy state matching', () => {
+  it('handles true', () => {
+    const view = render(<View accessibilityState={{ busy: true }} />);
+
+    expect(view.getByA11yState({ busy: true })).toBeTruthy();
+    expect(view.queryByA11yState({ busy: false })).toBeFalsy();
+  });
+
+  it('handles false', () => {
+    const view = render(<View accessibilityState={{ busy: false }} />);
+
+    expect(view.getByA11yState({ busy: false })).toBeTruthy();
+    expect(view.queryByA11yState({ busy: true })).toBeFalsy();
+  });
+
+  it('handles  default', () => {
+    const view = render(<View accessibilityState={{}} />);
+
+    expect(view.getByA11yState({ busy: false })).toBeTruthy();
+    expect(view.queryByA11yState({ busy: true })).toBeFalsy();
+  });
+});
+
+describe('selected state matching', () => {
+  it('handles true', () => {
+    const view = render(<View accessibilityState={{ selected: true }} />);
+
+    expect(view.getByA11yState({ selected: true })).toBeTruthy();
+    expect(view.queryByA11yState({ selected: false })).toBeFalsy();
+  });
+
+  it('handles false', () => {
+    const view = render(<View accessibilityState={{ selected: false }} />);
+
+    expect(view.getByA11yState({ selected: false })).toBeTruthy();
+    expect(view.queryByA11yState({ selected: true })).toBeFalsy();
+  });
+
+  it('handles  default', () => {
+    const view = render(<View accessibilityState={{}} />);
+
+    expect(view.getByA11yState({ selected: false })).toBeTruthy();
+    expect(view.queryByA11yState({ selected: true })).toBeFalsy();
+  });
+});
+
+test('*ByA11yState on Pressable with "disabled" prop', () => {
+  const view = render(<Pressable disabled />);
+  expect(view.getByA11yState({ disabled: true })).toBeTruthy();
+  expect(view.queryByA11yState({ disabled: false })).toBeFalsy();
+});
+
+test('*ByA11yState on TouchableOpacity with "disabled" prop', () => {
+  const view = render(<TouchableOpacity disabled />);
+  expect(view.getByA11yState({ disabled: true })).toBeTruthy();
+  expect(view.queryByA11yState({ disabled: false })).toBeFalsy();
+});

src/queries/a11yState.ts

@@ -1,6 +1,5 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 import type { AccessibilityState } from 'react-native';
-import { matchObjectProp } from '../helpers/matchers/matchObjectProp';
 import { makeQueries } from './makeQueries';
 import type {
   FindAllByQuery,
@@ -11,15 +10,52 @@ import type {
   QueryByQuery,
 } from './makeQueries';
 
+/**
+ * Default accessibility state values based on experiments using accessibility
+ * inspector/screen reader on iOS and Android.
+ *
+ * @see https://github.com/callstack/react-native-testing-library/wiki/Accessibility:-State
+ */
+const defaultState: AccessibilityState = {
+  disabled: false,
+  selected: false,
+  checked: undefined,
+  busy: false,
+  expanded: undefined,
+};
+
+export function matchAccessibilityState(
+  node: ReactTestInstance,
+  matcher: AccessibilityState
+) {
+  const state = node.props.accessibilityState;
+  return (
+    matchState(state, matcher, 'disabled') &&
+    matchState(state, matcher, 'selected') &&
+    matchState(state, matcher, 'checked') &&
+    matchState(state, matcher, 'busy') &&
+    matchState(state, matcher, 'expanded')
+  );
+}
+
+function matchState(
+  value: AccessibilityState,
+  matcher: AccessibilityState,
+  key: keyof AccessibilityState
+) {
+  const valueWithDefault = value?.[key] ?? defaultState[key];
+  return matcher[key] === undefined || matcher[key] === valueWithDefault;
+}
+
 const queryAllByA11yState = (
   instance: ReactTestInstance
-): ((state: AccessibilityState) => Array<ReactTestInstance>) =>
-  function queryAllByA11yStateFn(state) {
-    return instance.findAll(
-      (node) =>
-        typeof node.type === 'string' &&
-        matchObjectProp(node.props.accessibilityState, state)
-    );
+): ((matcher: AccessibilityState) => Array<ReactTestInstance>) =>
+  function queryAllByA11yStateFn(matcher) {
+    return instance.findAll((node) => {
+      return (
+        typeof node.type === 'string' && matchAccessibilityState(node, matcher)
+      );
+    });
   };
 
 const getMultipleError = (state: AccessibilityState) =>

src/queries/role.ts

@@ -12,13 +12,22 @@ import type {
   QueryAllByQuery,
   QueryByQuery,
 } from './makeQueries';
+import { matchAccessibilityState } from './a11yState';
 
 type ByRoleOptions = {
   name?: TextMatch;
 } & AccessibilityState;
 
 type AccessibilityStateKey = keyof AccessibilityState;
 
+const accessibilityStateKeys: AccessibilityStateKey[] = [
+  'disabled',
+  'selected',
+  'checked',
+  'busy',
+  'expanded',
+];
+
 const matchAccessibleNameIfNeeded = (
   node: ReactTestInstance,
   name?: TextMatch
@@ -31,42 +40,16 @@ const matchAccessibleNameIfNeeded = (
   );
 };
 
-// disabled:undefined is equivalent to disabled:false, same for selected. busy not, but it makes
-// sense from a testing/voice-over perspective. checked and expanded do behave differently
-const implicityFalseState: AccessibilityStateKey[] = [
-  'disabled',
-  'selected',
-  'busy',
-];
-
 const matchAccessibleStateIfNeeded = (
   node: ReactTestInstance,
   options?: ByRoleOptions
-) =>
-  accessibilityStates.every((accessibilityState) => {
-    const queriedState = options?.[accessibilityState];
-
-    if (typeof queriedState !== 'undefined') {
-      // Some accessibilityState properties have implicit value (when not set)
-      const defaultState = implicityFalseState.includes(accessibilityState)
-        ? false
-        : undefined;
-      return (
-        queriedState ===
-        (node.props.accessibilityState?.[accessibilityState] ?? defaultState)
-      );
-    } else {
-      return true;
-    }
-  });
+) => {
+  if (!options) {
+    return true;
+  }
 
-const accessibilityStates: AccessibilityStateKey[] = [
-  'disabled',
-  'selected',
-  'checked',
-  'busy',
-  'expanded',
-];
+  return matchAccessibilityState(node, options);
+};
 
 const queryAllByRole = (
   instance: ReactTestInstance
@@ -90,22 +73,15 @@ const buildErrorMessage = (role: TextMatch, options: ByRoleOptions = {}) => {
     errors.push(`name: "${String(options.name)}"`);
   }
 
-  if (
-    accessibilityStates.some(
-      (accessibilityState) => typeof options[accessibilityState] !== 'undefined'
-    )
-  ) {
-    accessibilityStates.forEach((accessibilityState) => {
-      if (options[accessibilityState]) {
-        errors.push(
-          `${accessibilityState} state: ${options[accessibilityState]}`
-        );
-      }
-    });
-  }
+  accessibilityStateKeys.forEach((stateKey) => {
+    if (options[stateKey]) {
+      errors.push(`${stateKey} state: ${options[stateKey]}`);
+    }
+  });
 
   return errors.join(', ');
 };
+
 const getMultipleError = (role: TextMatch, options?: ByRoleOptions) =>
   `Found multiple elements with ${buildErrorMessage(role, options)}`;
 const getMissingError = (role: TextMatch, options?: ByRoleOptions) =>

website/docs/Queries.md

@@ -23,6 +23,8 @@ title: Queries
   - [`ByRole`](#byrole)
     - [Options](#options-1)
   - [`ByA11yState`, `ByAccessibilityState`](#bya11ystate-byaccessibilitystate)
+    - [Default state for: `disabled`, `selected`, and `busy` keys](#default-state-for-disabled-selected-and-busy-keys)
+    - [Default state for: `checked` and `expanded` keys](#default-state-for-checked-and-expanded-keys)
   - [`ByA11Value`, `ByAccessibilityValue`](#bya11value-byaccessibilityvalue)
 - [TextMatch](#textmatch)
   - [Examples](#examples)
@@ -296,6 +298,30 @@ render(<Component />);
 const element = screen.getByA11yState({ disabled: true });
 ```
 
+:::note
+
+#### Default state for: `disabled`, `selected`, and `busy` keys
+
+Passing `false` matcher value will match both elements with explicit `false` state value and without explicit state value. 
+
+For instance, `getByA11yState({ disabled: false })` will match elements with following props:
+* `accessibilityState={{ disabled: false, ... }}`
+* no `disabled` key under `accessibilityState` prop, e.g. `accessibilityState={{}}`
+* no `accessibilityState` prop at all
+
+#### Default state for: `checked` and `expanded` keys
+Passing `false` matcher value will only match elements with explicit `false` state value.
+
+For instance, `getByA11yState({ checked: false })` will only match elements with:
+* `accessibilityState={{ checked: false, ... }}`
+
+but will not match elements with following props:
+* no `checked` key under `accessibilityState` prop, e.g. `accessibilityState={{}}`
+* no `accessibilityState` prop at all
+
+The difference in handling default values is made to reflect observed accessibility behaviour on iOS and Android platforms.
+:::
+
 ### `ByA11Value`, `ByAccessibilityValue`
 
 > getByA11yValue, getAllByA11yValue, queryByA11yValue, queryAllByA11yValue, findByA11yValue, findAllByA11yValue