@testing-library/react-native 12.1.2 → 12.2.0

package/src/queries/a11yValue.ts

@@ -0,0 +1,131 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { accessiblityValueKeys } from '../helpers/accessiblity';
+import { deprecateQueries } from '../helpers/deprecation';
+import { findAll } from '../helpers/findAll';
+import {
+  AccessibilityValueMatcher,
+  matchAccessibilityValue,
+} from '../helpers/matchers/accessibilityValue';
+import { makeQueries } from './makeQueries';
+import type {
+  FindAllByQuery,
+  FindByQuery,
+  GetAllByQuery,
+  GetByQuery,
+  QueryAllByQuery,
+  QueryByQuery,
+} from './makeQueries';
+import { CommonQueryOptions } from './options';
+
+const queryAllByA11yValue = (
+  instance: ReactTestInstance
+): ((
+  value: AccessibilityValueMatcher,
+  queryOptions?: CommonQueryOptions
+) => Array<ReactTestInstance>) =>
+  function queryAllByA11yValueFn(value, queryOptions) {
+    return findAll(
+      instance,
+      (node) =>
+        typeof node.type === 'string' && matchAccessibilityValue(node, value),
+      queryOptions
+    );
+  };
+
+const formatQueryParams = (matcher: AccessibilityValueMatcher) => {
+  const params: string[] = [];
+
+  accessiblityValueKeys.forEach((valueKey) => {
+    if (matcher[valueKey] !== undefined) {
+      params.push(`${valueKey} value: ${matcher[valueKey]}`);
+    }
+  });
+
+  return params.join(', ');
+};
+
+const getMultipleError = (matcher: AccessibilityValueMatcher) =>
+  `Found multiple elements with ${formatQueryParams(matcher)}`;
+
+const getMissingError = (matcher: AccessibilityValueMatcher) =>
+  `Unable to find an element with ${formatQueryParams(matcher)}`;
+
+const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
+  queryAllByA11yValue,
+  getMissingError,
+  getMultipleError
+);
+
+export type ByA11yValueQueries = {
+  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<
+    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 = (
+  instance: ReactTestInstance
+): ByA11yValueQueries => {
+  const getByA11yValue = getBy(instance);
+  const getAllByA11yValue = getAllBy(instance);
+  const queryByA11yValue = queryBy(instance);
+  const queryAllByA11yValue = queryAllBy(instance);
+  const findByA11yValue = findBy(instance);
+  const findAllByA11yValue = findAllBy(instance);
+
+  return {
+    ...deprecateQueries(
+      {
+        getByA11yValue,
+        getAllByA11yValue,
+        queryByA11yValue,
+        queryAllByA11yValue,
+        findByA11yValue,
+        findAllByA11yValue,
+        getByAccessibilityValue: getByA11yValue,
+        getAllByAccessibilityValue: getAllByA11yValue,
+        queryByAccessibilityValue: queryByA11yValue,
+        queryAllByAccessibilityValue: queryAllByA11yValue,
+        findByAccessibilityValue: findByA11yValue,
+        findAllByAccessibilityValue: findAllByA11yValue,
+      },
+      'Use expect(...).toHaveAccessibilityValue(...) matcher from "@testing-library/jest-native" package or {queryPrefix}ByRole(role, { value: ... }) query instead.'
+    ),
+  };
+};

package/src/queries/displayValue.ts

@@ -0,0 +1,78 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { filterNodeByType } from '../helpers/filterNodeByType';
+import { findAll } from '../helpers/findAll';
+import { matches, TextMatch, TextMatchOptions } from '../matches';
+import { getHostComponentNames } from '../helpers/host-component-names';
+import { makeQueries } from './makeQueries';
+import type {
+  FindAllByQuery,
+  FindByQuery,
+  GetAllByQuery,
+  GetByQuery,
+  QueryAllByQuery,
+  QueryByQuery,
+} from './makeQueries';
+import type { CommonQueryOptions } from './options';
+
+type ByDisplayValueOptions = CommonQueryOptions & TextMatchOptions;
+
+const getTextInputNodeByDisplayValue = (
+  node: ReactTestInstance,
+  value: TextMatch,
+  options: TextMatchOptions = {}
+) => {
+  const { exact, normalizer } = options;
+  const nodeValue =
+    node.props.value !== undefined ? node.props.value : node.props.defaultValue;
+
+  return (
+    filterNodeByType(node, getHostComponentNames().textInput) &&
+    matches(value, nodeValue, normalizer, exact)
+  );
+};
+
+const queryAllByDisplayValue = (
+  instance: ReactTestInstance
+): ((
+  displayValue: TextMatch,
+  queryOptions?: ByDisplayValueOptions
+) => Array<ReactTestInstance>) =>
+  function queryAllByDisplayValueFn(displayValue, queryOptions) {
+    return findAll(
+      instance,
+      (node) =>
+        getTextInputNodeByDisplayValue(node, displayValue, queryOptions),
+      queryOptions
+    );
+  };
+
+const getMultipleError = (displayValue: TextMatch) =>
+  `Found multiple elements with display value: ${String(displayValue)} `;
+const getMissingError = (displayValue: TextMatch) =>
+  `Unable to find an element with displayValue: ${String(displayValue)}`;
+
+const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
+  queryAllByDisplayValue,
+  getMissingError,
+  getMultipleError
+);
+
+export type ByDisplayValueQueries = {
+  getByDisplayValue: GetByQuery<TextMatch, ByDisplayValueOptions>;
+  getAllByDisplayValue: GetAllByQuery<TextMatch, ByDisplayValueOptions>;
+  queryByDisplayValue: QueryByQuery<TextMatch, ByDisplayValueOptions>;
+  queryAllByDisplayValue: QueryAllByQuery<TextMatch, ByDisplayValueOptions>;
+  findByDisplayValue: FindByQuery<TextMatch, ByDisplayValueOptions>;
+  findAllByDisplayValue: FindAllByQuery<TextMatch, ByDisplayValueOptions>;
+};
+
+export const bindByDisplayValueQueries = (
+  instance: ReactTestInstance
+): ByDisplayValueQueries => ({
+  getByDisplayValue: getBy(instance),
+  getAllByDisplayValue: getAllBy(instance),
+  queryByDisplayValue: queryBy(instance),
+  queryAllByDisplayValue: queryAllBy(instance),
+  findByDisplayValue: findBy(instance),
+  findAllByDisplayValue: findAllBy(instance),
+});

package/src/queries/hintText.ts

@@ -0,0 +1,112 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { findAll } from '../helpers/findAll';
+import { matches, TextMatch, TextMatchOptions } from '../matches';
+import { makeQueries } from './makeQueries';
+import type {
+  FindAllByQuery,
+  FindByQuery,
+  GetAllByQuery,
+  GetByQuery,
+  QueryAllByQuery,
+  QueryByQuery,
+} from './makeQueries';
+import { CommonQueryOptions } from './options';
+
+type ByHintTextOptions = CommonQueryOptions & TextMatchOptions;
+
+const getNodeByHintText = (
+  node: ReactTestInstance,
+  text: TextMatch,
+  options: TextMatchOptions = {}
+) => {
+  const { exact, normalizer } = options;
+  return matches(text, node.props.accessibilityHint, normalizer, exact);
+};
+
+const queryAllByHintText = (
+  instance: ReactTestInstance
+): ((
+  hint: TextMatch,
+  queryOptions?: ByHintTextOptions
+) => Array<ReactTestInstance>) =>
+  function queryAllByA11yHintFn(hint, queryOptions) {
+    return findAll(
+      instance,
+      (node) =>
+        typeof node.type === 'string' &&
+        getNodeByHintText(node, hint, queryOptions),
+      queryOptions
+    );
+  };
+
+const getMultipleError = (hint: TextMatch) =>
+  `Found multiple elements with accessibilityHint: ${String(hint)} `;
+const getMissingError = (hint: TextMatch) =>
+  `Unable to find an element with accessibilityHint: ${String(hint)}`;
+
+const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
+  queryAllByHintText,
+  getMissingError,
+  getMultipleError
+);
+
+export type ByHintTextQueries = {
+  getByHintText: GetByQuery<TextMatch, ByHintTextOptions>;
+  getAllByHintText: GetAllByQuery<TextMatch, ByHintTextOptions>;
+  queryByHintText: QueryByQuery<TextMatch, ByHintTextOptions>;
+  queryAllByHintText: QueryAllByQuery<TextMatch, ByHintTextOptions>;
+  findByHintText: FindByQuery<TextMatch, ByHintTextOptions>;
+  findAllByHintText: FindAllByQuery<TextMatch, ByHintTextOptions>;
+
+  // a11yHint aliases
+  getByA11yHint: GetByQuery<TextMatch, ByHintTextOptions>;
+  getAllByA11yHint: GetAllByQuery<TextMatch, ByHintTextOptions>;
+  queryByA11yHint: QueryByQuery<TextMatch, ByHintTextOptions>;
+  queryAllByA11yHint: QueryAllByQuery<TextMatch, ByHintTextOptions>;
+  findByA11yHint: FindByQuery<TextMatch, ByHintTextOptions>;
+  findAllByA11yHint: FindAllByQuery<TextMatch, ByHintTextOptions>;
+
+  // accessibilityHint aliases
+  getByAccessibilityHint: GetByQuery<TextMatch, ByHintTextOptions>;
+  getAllByAccessibilityHint: GetAllByQuery<TextMatch, ByHintTextOptions>;
+  queryByAccessibilityHint: QueryByQuery<TextMatch, ByHintTextOptions>;
+  queryAllByAccessibilityHint: QueryAllByQuery<TextMatch, ByHintTextOptions>;
+  findByAccessibilityHint: FindByQuery<TextMatch, ByHintTextOptions>;
+  findAllByAccessibilityHint: FindAllByQuery<TextMatch, ByHintTextOptions>;
+};
+
+export const bindByHintTextQueries = (
+  instance: ReactTestInstance
+): ByHintTextQueries => {
+  const getByHintText = getBy(instance);
+  const getAllByHintText = getAllBy(instance);
+  const queryByHintText = queryBy(instance);
+  const queryAllByHintText = queryAllBy(instance);
+  const findByHintText = findBy(instance);
+  const findAllByHintText = findAllBy(instance);
+
+  return {
+    getByHintText,
+    getAllByHintText,
+    queryByHintText,
+    queryAllByHintText,
+    findByHintText,
+    findAllByHintText,
+
+    // a11yHint aliases
+    getByA11yHint: getByHintText,
+    getAllByA11yHint: getAllByHintText,
+    queryByA11yHint: queryByHintText,
+    queryAllByA11yHint: queryAllByHintText,
+    findByA11yHint: findByHintText,
+    findAllByA11yHint: findAllByHintText,
+
+    // accessibilityHint aliases
+    getByAccessibilityHint: getByHintText,
+    getAllByAccessibilityHint: getAllByHintText,
+    queryByAccessibilityHint: queryByHintText,
+    queryAllByAccessibilityHint: queryAllByHintText,
+    findByAccessibilityHint: findByHintText,
+    findAllByAccessibilityHint: findAllByHintText,
+  };
+};

package/src/queries/labelText.ts

@@ -0,0 +1,59 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { findAll } from '../helpers/findAll';
+import { TextMatch, TextMatchOptions } from '../matches';
+import { matchLabelText } from '../helpers/matchers/matchLabelText';
+import { makeQueries } from './makeQueries';
+import type {
+  FindAllByQuery,
+  FindByQuery,
+  GetAllByQuery,
+  GetByQuery,
+  QueryAllByQuery,
+  QueryByQuery,
+} from './makeQueries';
+import { CommonQueryOptions } from './options';
+
+type ByLabelTextOptions = CommonQueryOptions & TextMatchOptions;
+
+function queryAllByLabelText(instance: ReactTestInstance) {
+  return (text: TextMatch, queryOptions?: ByLabelTextOptions) => {
+    return findAll(
+      instance,
+      (node) =>
+        typeof node.type === 'string' &&
+        matchLabelText(instance, node, text, queryOptions),
+      queryOptions
+    );
+  };
+}
+
+const getMultipleError = (labelText: TextMatch) =>
+  `Found multiple elements with accessibilityLabel: ${String(labelText)} `;
+const getMissingError = (labelText: TextMatch) =>
+  `Unable to find an element with accessibilityLabel: ${String(labelText)}`;
+
+const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
+  queryAllByLabelText,
+  getMissingError,
+  getMultipleError
+);
+
+export type ByLabelTextQueries = {
+  getByLabelText: GetByQuery<TextMatch, ByLabelTextOptions>;
+  getAllByLabelText: GetAllByQuery<TextMatch, ByLabelTextOptions>;
+  queryByLabelText: QueryByQuery<TextMatch, ByLabelTextOptions>;
+  queryAllByLabelText: QueryAllByQuery<TextMatch, ByLabelTextOptions>;
+  findByLabelText: FindByQuery<TextMatch, ByLabelTextOptions>;
+  findAllByLabelText: FindAllByQuery<TextMatch, ByLabelTextOptions>;
+};
+
+export const bindByLabelTextQueries = (
+  instance: ReactTestInstance
+): ByLabelTextQueries => ({
+  getByLabelText: getBy(instance),
+  getAllByLabelText: getAllBy(instance),
+  queryByLabelText: queryBy(instance),
+  queryAllByLabelText: queryAllBy(instance),
+  findByLabelText: findBy(instance),
+  findAllByLabelText: findAllBy(instance),
+});

package/src/queries/makeQueries.ts

@@ -0,0 +1,255 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import { ErrorWithStack } from '../helpers/errors';
+import waitFor from '../waitFor';
+import type { WaitForOptions } from '../waitFor';
+import format from '../helpers/format';
+import { screen } from '../screen';
+import { defaultMapProps } from '../helpers/format-default';
+
+export type GetByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  options?: Options
+) => ReactTestInstance;
+
+export type GetAllByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  options?: Options
+) => ReactTestInstance[];
+
+export type QueryByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  options?: Options
+) => ReactTestInstance | null;
+
+export type QueryAllByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  options?: Options
+) => ReactTestInstance[];
+
+export type FindByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  // Remove `& WaitForOptions` when all queries have been migrated to support 2nd arg query options.
+  options?: Options & WaitForOptions,
+  waitForOptions?: WaitForOptions
+) => Promise<ReactTestInstance>;
+
+export type FindAllByQuery<Predicate, Options = void> = (
+  predicate: Predicate,
+  // Remove `& WaitForOptions` when all queries have been migrated to support 2nd arg query options.
+  options?: Options & WaitForOptions,
+  waitForOptions?: WaitForOptions
+) => Promise<ReactTestInstance[]>;
+
+type UnboundQuery<Query> = (instance: ReactTestInstance) => Query;
+
+export type UnboundQueries<Predicate, Options> = {
+  getBy: UnboundQuery<GetByQuery<Predicate, Options>>;
+  getAllBy: UnboundQuery<GetAllByQuery<Predicate, Options>>;
+  queryBy: UnboundQuery<QueryByQuery<Predicate, Options>>;
+  queryAllBy: UnboundQuery<QueryAllByQuery<Predicate, Options>>;
+  findBy: UnboundQuery<FindByQuery<Predicate, Options>>;
+  findAllBy: UnboundQuery<FindAllByQuery<Predicate, Options>>;
+};
+
+const deprecatedKeys: (keyof WaitForOptions)[] = [
+  'timeout',
+  'interval',
+  'stackTraceError',
+];
+
+// The WaitForOptions has been moved to the second option param of findBy* methods with the adding of TextMatchOptions
+// To make the migration easier and avoid a breaking change, keep reading this options from the first param but warn
+function extractDeprecatedWaitForOptions(options?: WaitForOptions) {
+  if (!options) {
+    return undefined;
+  }
+
+  const waitForOptions: WaitForOptions = {
+    timeout: options.timeout,
+    interval: options.interval,
+    stackTraceError: options.stackTraceError,
+  };
+
+  deprecatedKeys.forEach((key) => {
+    const option = options[key];
+    if (option) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `Use of option "${key}" in a findBy* query options (2nd parameter) is deprecated. Please pass this option in the waitForOptions (3rd parameter).
+Example:
+
+  findByText(text, {}, { ${key}: ${option.toString()} })`
+      );
+    }
+  });
+
+  return waitForOptions;
+}
+
+function formatErrorMessage(message: string, printElementTree: boolean) {
+  if (!printElementTree) {
+    return message;
+  }
+
+  const json = screen.toJSON();
+  if (!json) {
+    return message;
+  }
+
+  return `${message}\n\n${format(json, {
+    mapProps: defaultMapProps,
+  })}`;
+}
+
+function appendElementTreeToError(error: Error) {
+  const oldMessage = error.message;
+  error.message = formatErrorMessage(oldMessage, true);
+
+  // Required to make Jest print the element tree on error
+  error.stack = error.stack?.replace(oldMessage, error.message);
+
+  return error;
+}
+
+export function makeQueries<Predicate, Options>(
+  queryAllByQuery: UnboundQuery<QueryAllByQuery<Predicate, Options>>,
+  getMissingError: (predicate: Predicate, options?: Options) => string,
+  getMultipleError: (predicate: Predicate, options?: Options) => string
+): UnboundQueries<Predicate, Options> {
+  function getAllByQuery(
+    instance: ReactTestInstance,
+    { printElementTree = true } = {}
+  ) {
+    return function getAllFn(predicate: Predicate, options?: Options) {
+      const results = queryAllByQuery(instance)(predicate, options);
+
+      if (results.length === 0) {
+        const errorMessage = formatErrorMessage(
+          getMissingError(predicate, options),
+          printElementTree
+        );
+        throw new ErrorWithStack(errorMessage, getAllFn);
+      }
+
+      return results;
+    };
+  }
+
+  function queryByQuery(
+    instance: ReactTestInstance,
+    { printElementTree = true } = {}
+  ) {
+    return function singleQueryFn(predicate: Predicate, options?: Options) {
+      const results = queryAllByQuery(instance)(predicate, options);
+
+      if (results.length > 1) {
+        throw new ErrorWithStack(
+          formatErrorMessage(
+            getMultipleError(predicate, options),
+            printElementTree
+          ),
+          singleQueryFn
+        );
+      }
+
+      if (results.length === 0) {
+        return null;
+      }
+
+      return results[0];
+    };
+  }
+
+  function getByQuery(
+    instance: ReactTestInstance,
+    { printElementTree = true } = {}
+  ) {
+    return function getFn(predicate: Predicate, options?: Options) {
+      const results = queryAllByQuery(instance)(predicate, options);
+
+      if (results.length > 1) {
+        throw new ErrorWithStack(getMultipleError(predicate, options), getFn);
+      }
+
+      if (results.length === 0) {
+        const errorMessage = formatErrorMessage(
+          getMissingError(predicate, options),
+          printElementTree
+        );
+        throw new ErrorWithStack(errorMessage, getFn);
+      }
+
+      return results[0];
+    };
+  }
+
+  function findAllByQuery(instance: ReactTestInstance) {
+    return function findAllFn(
+      predicate: Predicate,
+      queryOptions?: Options & WaitForOptions,
+      {
+        onTimeout = (error) => appendElementTreeToError(error),
+        ...waitForOptions
+      }: WaitForOptions = {}
+    ) {
+      const stackTraceError = new ErrorWithStack(
+        'STACK_TRACE_ERROR',
+        findAllFn
+      );
+      const deprecatedWaitForOptions =
+        extractDeprecatedWaitForOptions(queryOptions);
+
+      return waitFor(
+        () =>
+          getAllByQuery(instance, { printElementTree: false })(
+            predicate,
+            queryOptions
+          ),
+        {
+          ...deprecatedWaitForOptions,
+          ...waitForOptions,
+          stackTraceError,
+          onTimeout,
+        }
+      );
+    };
+  }
+
+  function findByQuery(instance: ReactTestInstance) {
+    return function findFn(
+      predicate: Predicate,
+      queryOptions?: Options & WaitForOptions,
+      {
+        onTimeout = (error) => appendElementTreeToError(error),
+        ...waitForOptions
+      }: WaitForOptions = {}
+    ) {
+      const stackTraceError = new ErrorWithStack('STACK_TRACE_ERROR', findFn);
+      const deprecatedWaitForOptions =
+        extractDeprecatedWaitForOptions(queryOptions);
+
+      return waitFor(
+        () =>
+          getByQuery(instance, { printElementTree: false })(
+            predicate,
+            queryOptions
+          ),
+        {
+          ...deprecatedWaitForOptions,
+          ...waitForOptions,
+          stackTraceError,
+          onTimeout,
+        }
+      );
+    };
+  }
+
+  return {
+    getBy: getByQuery,
+    getAllBy: getAllByQuery,
+    queryBy: queryByQuery,
+    queryAllBy: queryAllByQuery,
+    findBy: findByQuery,
+    findAllBy: findAllByQuery,
+  };
+}

package/src/queries/options.ts

@@ -0,0 +1,14 @@
+import { NormalizerFn } from '../matches';
+
+export type CommonQueryOptions = {
+  /** Should query include elements hidden from accessibility. */
+  includeHiddenElements?: boolean;
+
+  /** RTL-compatibile alias to `includeHiddenElements`. */
+  hidden?: boolean;
+};
+
+export type TextMatchOptions = {
+  exact?: boolean;
+  normalizer?: NormalizerFn;
+};