refactor: pre-merge tweaks

Author: mdjastrzebski

src/__tests__/config.test.ts

@@ -23,7 +23,6 @@ test('resetToDefaults() resets config to defaults', () => {
   configure({
     asyncUtilTimeout: 5000,
     defaultIncludeHiddenElements: false,
-    defaultHidden: false,
   });
   expect(getConfig().asyncUtilTimeout).toEqual(5000);
   expect(getConfig().defaultIncludeHiddenElements).toEqual(false);
@@ -35,6 +34,7 @@ test('resetToDefaults() resets config to defaults', () => {
 
 test('configure handles alias option defaultHidden', () => {
   expect(getConfig().defaultIncludeHiddenElements).toEqual(true);
+
   configure({ defaultHidden: false });
   expect(getConfig().defaultIncludeHiddenElements).toEqual(false);
 });

src/config.ts

@@ -4,18 +4,15 @@ export type Config = {
   /** Default timeout, in ms, for `waitFor` and `findBy*` queries. */
   asyncUtilTimeout: number;
 
-  /** Default includeHiddenElements value for all queries */
+  /** Default value for `includeHiddenElements` query option. */
   defaultIncludeHiddenElements: boolean;
 
   /** Default options for `debug` helper. */
   defaultDebugOptions?: Partial<DebugOptions>;
 };
 
 export type ConfigAliasOptions = {
-  /** Default hidden value for all queries, alias to defaultIncludeHiddenElements to respect react-testing-library API
-   * WARNING: if both defaultHidden and defaultIncludeHiddenElements values are defined,
-   * then defaultIncludeHiddenElements will take precedence
-   */
+  /** RTL-compatibility alias to `defaultIncludeHiddenElements` */
   defaultHidden: boolean;
 };
 
@@ -34,14 +31,10 @@ export function configure(options: Partial<Config & ConfigAliasOptions>) {
     defaultHidden ??
     config.defaultIncludeHiddenElements;
 
-  const optionsToSet = {
-    ...restOptions,
-    defaultIncludeHiddenElements,
-  };
-
   config = {
     ...config,
-    ...optionsToSet,
+    ...restOptions,
+    defaultIncludeHiddenElements,
   };
 }
 

src/helpers/__tests__/includeHiddenElements.test.tsx

@@ -1,9 +1,6 @@
-import { View } from 'react-native';
 import React from 'react';
-
-import render from '../../render';
-import { screen } from '../../screen';
-import { configure } from '../../config';
+import { View } from 'react-native';
+import { configure, render, screen } from '../..';
 
 test('includeHiddenElements query option takes priority over hidden option and global config', () => {
   configure({ defaultHidden: true, defaultIncludeHiddenElements: true });

src/helpers/findAll.ts

@@ -15,12 +15,12 @@ export function findAll(
 ) {
   const results = root.findAll(predicate);
 
-  const hidden =
+  const includeHiddenElements =
     options?.includeHiddenElements ??
     options?.hidden ??
     getConfig()?.defaultIncludeHiddenElements;
 
-  if (hidden) {
+  if (includeHiddenElements) {
     return results;
   }
 

src/queries/__tests__/a11yState.test.tsx

@@ -247,5 +247,7 @@ test('byA11yState queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByA11yState({ expanded: false }, { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with expanded state: false"`
+  );
 });

src/queries/__tests__/a11yValue.test.tsx

@@ -110,5 +110,7 @@ test('byA11yValue queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByA11yValue({ max: 10 }, { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with accessibilityValue: {"max":10}"`
+  );
 });

src/queries/__tests__/displayValue.test.tsx

@@ -115,5 +115,7 @@ test('byDisplayValue queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByDisplayValue('hidden', { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with displayValue: hidden"`
+  );
 });

src/queries/__tests__/hintText.test.tsx

@@ -122,5 +122,7 @@ test('byHintText queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByHintText('hidden', { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with accessibilityHint: hidden"`
+  );
 });

src/queries/__tests__/labelText.test.tsx

@@ -161,5 +161,7 @@ test('byLabelText queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByLabelText('hidden', { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with accessibilityLabel: hidden"`
+  );
 });

src/queries/__tests__/placeholderText.test.tsx

@@ -74,5 +74,7 @@ test('byPlaceholderText queries support hidden option', () => {
   ).toBeFalsy();
   expect(() =>
     getByPlaceholderText('hidden', { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with placeholder: hidden"`
+  );
 });

src/queries/__tests__/role.test.tsx

@@ -709,5 +709,9 @@ test('byRole queries support hidden option', () => {
   expect(getByRole('button', { includeHiddenElements: true })).toBeTruthy();
 
   expect(queryByRole('button', { includeHiddenElements: false })).toBeFalsy();
-  expect(() => getByRole('button', { includeHiddenElements: false })).toThrow();
+  expect(() =>
+    getByRole('button', { includeHiddenElements: false })
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with role: "button""`
+  );
 });

src/queries/__tests__/testId.test.tsx

@@ -146,5 +146,7 @@ test('byTestId queries support hidden option', () => {
   expect(queryByTestId('hidden', { includeHiddenElements: false })).toBeFalsy();
   expect(() =>
     getByTestId('hidden', { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with testID: hidden"`
+  );
 });

src/queries/__tests__/text.test.tsx

@@ -478,5 +478,7 @@ test('byText support hidden option', () => {
   expect(queryByText(/hidden/i, { includeHiddenElements: false })).toBeFalsy();
   expect(() =>
     getByText(/hidden/i, { includeHiddenElements: false })
-  ).toThrow();
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Unable to find an element with text: /hidden/i"`
+  );
 });

src/queries/options.ts

@@ -1,12 +1,11 @@
 import { NormalizerFn } from '../matches';
 
-/**
- * hidden is an alias for includeHiddenElements that exists only to match react-testing-library API
- * if both hidden and includeHiddenElements values are defined, then includeHiddenElements will take precedence
- */
 export type CommonQueryOptions = {
-  hidden?: boolean;
+  /** Should query include elements hidden from accessibility. */
   includeHiddenElements?: boolean;
+
+  /** RTL-compatibile alias to `includeHiddenElements`. */
+  hidden?: boolean;
 };
 
 export type TextMatchOptions = {

typings/index.flow.js

@@ -10,7 +10,6 @@ type FindAllReturn = Promise<ReactTestInstance[]>;
 
 type CommonQueryOptions = {
   includeHiddenElements?: boolean,
-  /** Alias to `includeHiddenElements` for RTL compatibility */
   hidden?: boolean,
 };
 type TextMatch = string | RegExp;

website/docs/API.md

@@ -793,9 +793,11 @@ Default timeout, in ms, for async helper functions (`waitFor`, `waitForElementTo
 
 #### `defaultIncludeHiddenElements` option
 
-Default [includeHiddenElements](Queries.md#includehidden-option) query option for all queries. This default option will be overridden by the one you specify directly when using your query.
+Default value for [includeHiddenElements](Queries.md#includehidden-option) query option for all queries. Defaults to `true`, which means that queries will match [elements hidden from accessibility](#ishiddenfromaccessibility) by default.
 
-There is an alias to this option named `defaultHidden` that exists only for compatibility with [react-testing-library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden).
+Currently this option is set to `true` which means that queries will also match hidden elements. This is done to avoid breaking changes. However, we plan to change the default behavior to exclude hidden elements in the next major release.
+
+This option is also available as `defaultHidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden).
 
 #### `defaultDebugOptions` option
 

website/docs/Queries.md

@@ -378,28 +378,26 @@ const element = screen.getByA11yValue({ min: 40 });
 
 ### `includeHiddenElements` option
 
-All queries have the `includeHiddenElements` option which enables them to respect accessibility props on components when it is set to `false`. If you set `includeHiddenElements` to `true`, elements that are normally excluded from the accessibility tree are considered for the query as well. Currently `includeHiddenElements` option is set `true` by default, which means that elements includeHiddenElements from accessibility will be included by default. However, we plan to change the default value to `includeHiddenElements: false` in the next major release.
+All queries have the `includeHiddenElements` option which affects whether [elements hidden from accessibility](./API.md#ishiddenfromaccessibility) are matched by the query.
 
 You can configure the default value with the [`configure` function](API.md#configure).
 
-An element is considered to be hidden from accessibility based on [`isHiddenFromAccessibility()`](./API.md#ishiddenfromaccessibility) function.
-
-There is an alias to this option named `hidden` that exists only for compatibility with [react-testing-library](https://testing-library.com/docs/dom-testing-library/api-configuration/#defaulthidden).
+This option is also available as `hidden` alias for compatibility with [React Testing Library](https://testing-library.com/docs/queries/byrole#hidden).
 
 **Examples**
 
 ```tsx
-render(<Text style={{ display: 'none' }}>I am hidden from accessibility</Text>);
+render(<Text style={{ display: 'none' }}>Hidden from accessibility</Text>);
 
-// Include hidden elements
+// Exclude hidden elements
 expect(
-  screen.queryByText('I am hidden from accessibility', { includeHiddenElements: false })
+  screen.queryByText('Hidden from accessibility', { includeHiddenElements: false })
 ).toBeFalsy();
 
-// Match hidden elements
-expect(screen.getByText('I am hidden from accessibility')).toBeTruthy(); // Defaults to includeHiddenElements: true for now
+// Include hidden elements
+expect(screen.getByText('Hidden from accessibility')).toBeTruthy();
 expect(
-  screen.getByText('I am hidden from accessibility', { includeHiddenElements: true })
+  screen.getByText('Hidden from accessibility', { includeHiddenElements: true })
 ).toBeTruthy();
 ```