@testing-library/react-native 12.1.2 → 12.1.3

package/src/helpers/deprecation.ts

@@ -0,0 +1,53 @@
+import { getQueryPrefix } from './query-name';
+
+export function deprecateQueries<Queries extends Record<string, any>>(
+  queriesObject: Queries,
+  recommendation: string
+): Queries {
+  const result = {} as Queries;
+  Object.keys(queriesObject).forEach((queryName) => {
+    const queryFn = queriesObject[queryName];
+    // @ts-expect-error: generic typing is hard
+    result[queryName] = deprecateQuery(queryFn, queryName, recommendation);
+  });
+
+  return result;
+}
+
+function deprecateQuery<QueryFn extends (...args: any) => any>(
+  queryFn: QueryFn,
+  queryName: string,
+  recommendation: string
+): QueryFn {
+  const formattedRecommendation = recommendation.replace(
+    /{queryPrefix}/g,
+    getQueryPrefix(queryName)
+  );
+
+  // @ts-expect-error: generic typing is hard
+  const wrapper: QueryFn = (...args: any) => {
+    const errorMessage = `${queryName}(...) is deprecated and will be removed in the future.\n\n${formattedRecommendation}`;
+    // eslint-disable-next-line no-console
+    console.warn(errorMessage);
+    return queryFn(...args);
+  };
+
+  return wrapper;
+}
+
+const warned: { [functionName: string]: boolean } = {};
+
+// istambul ignore next: Occasionally used
+export function printDeprecationWarning(functionName: string) {
+  if (warned[functionName]) {
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.warn(`
+  Deprecation Warning:
+  Use of ${functionName} is not recommended and will be deleted in future versions of @testing-library/react-native.
+  `);
+
+  warned[functionName] = true;
+}

package/src/helpers/errors.ts

@@ -0,0 +1,66 @@
+import prettyFormat from 'pretty-format';
+
+export class ErrorWithStack extends Error {
+  constructor(message: string | undefined, callsite: Function) {
+    super(message);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, callsite);
+    }
+  }
+}
+
+export const prepareErrorMessage = (
+  // TS states that error caught in a catch close are of type `unknown`
+  // most real cases will be `Error`, but better safe than sorry
+  error: unknown,
+  name?: string,
+  value?: unknown
+): string => {
+  let errorMessage: string;
+  if (error instanceof Error) {
+    // Strip info about custom predicate
+    errorMessage = error.message.replace(
+      / matching custom predicate[^]*/gm,
+      ''
+    );
+  } else if (error && typeof error === 'object') {
+    errorMessage = error.toString();
+  } else {
+    errorMessage = 'Caught unknown error';
+  }
+
+  if (name && value) {
+    errorMessage += ` with ${name} ${prettyFormat(value, { min: true })}`;
+  }
+  return errorMessage;
+};
+
+export const createQueryByError = (
+  error: unknown,
+  callsite: Function
+): null => {
+  if (error instanceof Error) {
+    if (error.message.includes('No instances found')) {
+      return null;
+    }
+    throw new ErrorWithStack(error.message, callsite);
+  }
+
+  throw new ErrorWithStack(
+    // generic refining of `unknown` is very hard, you cannot do `'toString' in error` or anything like that
+    // Converting as any with extra safe optional chaining will do the job just as well
+    `Query: caught unknown error type: ${typeof error}, value: ${(
+      error as any
+    )?.toString?.()}`,
+    callsite
+  );
+};
+
+export function copyStackTrace(target: unknown, stackTraceSource: Error) {
+  if (target instanceof Error && stackTraceSource.stack) {
+    target.stack = stackTraceSource.stack.replace(
+      stackTraceSource.message,
+      target.message
+    );
+  }
+}

package/src/helpers/filterNodeByType.ts

@@ -0,0 +1,7 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+import * as React from 'react';
+
+export const filterNodeByType = (
+  node: ReactTestInstance | React.ReactElement,
+  type: React.ElementType | string
+) => node.type === type;

package/src/helpers/findAll.ts

@@ -0,0 +1,68 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { getConfig } from '../config';
+import { isHiddenFromAccessibility } from './accessiblity';
+
+interface FindAllOptions {
+  /** Match elements hidden from accessibility */
+  includeHiddenElements?: boolean;
+
+  /** RTL-compatible alias to `includeHiddenElements` */
+  hidden?: boolean;
+
+  /* Exclude any ancestors of deepest matched elements even if they match the predicate */
+  matchDeepestOnly?: boolean;
+}
+
+export function findAll(
+  root: ReactTestInstance,
+  predicate: (element: ReactTestInstance) => boolean,
+  options?: FindAllOptions
+) {
+  const results = findAllInternal(root, predicate, options);
+
+  const includeHiddenElements =
+    options?.includeHiddenElements ??
+    options?.hidden ??
+    getConfig()?.defaultIncludeHiddenElements;
+
+  if (includeHiddenElements) {
+    return results;
+  }
+
+  const cache = new WeakMap<ReactTestInstance>();
+  return results.filter(
+    (element) => !isHiddenFromAccessibility(element, { cache })
+  );
+}
+
+// Extracted from React Test Renderer
+// src: https://github.com/facebook/react/blob/8e2bde6f2751aa6335f3cef488c05c3ea08e074a/packages/react-test-renderer/src/ReactTestRenderer.js#L402
+function findAllInternal(
+  root: ReactTestInstance,
+  predicate: (element: ReactTestInstance) => boolean,
+  options?: FindAllOptions
+): Array<ReactTestInstance> {
+  const results: ReactTestInstance[] = [];
+
+  // Match descendants first but do not add them to results yet.
+  const matchingDescendants: ReactTestInstance[] = [];
+  root.children.forEach((child) => {
+    if (typeof child === 'string') {
+      return;
+    }
+    matchingDescendants.push(...findAllInternal(child, predicate, options));
+  });
+
+  if (
+    // When matchDeepestOnly = true: add current element only if no descendants match
+    (!options?.matchDeepestOnly || matchingDescendants.length === 0) &&
+    predicate(root)
+  ) {
+    results.push(root);
+  }
+
+  // Add matching descendants after element to preserve original tree walk order.
+  results.push(...matchingDescendants);
+
+  return results;
+}

package/src/helpers/format-default.ts

@@ -0,0 +1,72 @@
+import { StyleSheet, ViewStyle } from 'react-native';
+import { MapPropsFunction } from './format';
+
+const propsToDisplay = [
+  'testID',
+  'nativeID',
+  'accessibilityElementsHidden',
+  'accessibilityViewIsModal',
+  'importantForAccessibility',
+  'accessibilityRole',
+  'accessibilityLabel',
+  'accessibilityLabelledBy',
+  'accessibilityHint',
+  'placeholder',
+  'value',
+  'defaultValue',
+  'title',
+];
+
+/**
+ * Preserve props that are helpful in diagnosing test failures, while stripping rest
+ */
+export const defaultMapProps: MapPropsFunction = (props) => {
+  const result: Record<string, unknown> = {};
+
+  const styles = StyleSheet.flatten(props.style as ViewStyle);
+  if (styles?.display === 'none') {
+    result.style = { display: 'none' };
+  }
+
+  const accessibilityState = removeUndefinedKeys(props.accessibilityState);
+  if (accessibilityState !== undefined) {
+    result.accessibilityState = accessibilityState;
+  }
+
+  const accessibilityValue = removeUndefinedKeys(props.accessibilityValue);
+  if (accessibilityValue !== undefined) {
+    result.accessibilityValue = accessibilityValue;
+  }
+
+  propsToDisplay.forEach((propName) => {
+    if (propName in props) {
+      result[propName] = props[propName];
+    }
+  });
+
+  return result;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function removeUndefinedKeys(prop: unknown) {
+  if (!isObject(prop)) {
+    return prop;
+  }
+
+  const result: Record<string, unknown> = {};
+  Object.entries(prop).forEach(([key, value]) => {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  });
+
+  // If object does not have any props we will ignore it.
+  if (Object.keys(result).length === 0) {
+    return undefined;
+  }
+
+  return result;
+}

package/src/helpers/format.ts

@@ -0,0 +1,47 @@
+import type { ReactTestRendererJSON } from 'react-test-renderer';
+import prettyFormat, { NewPlugin, plugins } from 'pretty-format';
+
+export type MapPropsFunction = (
+  props: Record<string, unknown>,
+  node: ReactTestRendererJSON
+) => Record<string, unknown>;
+
+export type FormatOptions = {
+  mapProps?: MapPropsFunction;
+};
+
+const format = (
+  input: ReactTestRendererJSON | ReactTestRendererJSON[],
+  options: FormatOptions = {}
+) =>
+  prettyFormat(input, {
+    plugins: [getCustomPlugin(options.mapProps), plugins.ReactElement],
+    highlight: shouldHighlight(),
+    printBasicPrototype: false,
+  });
+
+const getCustomPlugin = (mapProps?: MapPropsFunction): NewPlugin => {
+  return {
+    test: (val) => plugins.ReactTestComponent.test(val),
+    serialize: (val, config, indentation, depth, refs, printer) => {
+      let newVal = val;
+      if (mapProps && val.props) {
+        newVal = { ...val, props: mapProps(val.props, val) };
+      }
+      return plugins.ReactTestComponent.serialize(
+        newVal,
+        config,
+        indentation,
+        depth,
+        refs,
+        printer
+      );
+    },
+  };
+};
+
+function shouldHighlight() {
+  return process?.env?.COLORS !== 'false';
+}
+
+export default format;

package/src/helpers/getTextContent.ts

@@ -0,0 +1,20 @@
+import type { ReactTestInstance } from 'react-test-renderer';
+
+export function getTextContent(
+  element: ReactTestInstance | string | null
+): string {
+  if (!element) {
+    return '';
+  }
+
+  if (typeof element === 'string') {
+    return element;
+  }
+
+  const result: string[] = [];
+  element.children?.forEach((child) => {
+    result.push(getTextContent(child));
+  });
+
+  return result.join('');
+}

package/src/helpers/host-component-names.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { ReactTestInstance } from 'react-test-renderer';
+import { Switch, Text, TextInput, View } from 'react-native';
+import { configureInternal, getConfig, HostComponentNames } from '../config';
+import { renderWithAct } from '../render-act';
+
+const userConfigErrorMessage = `There seems to be an issue with your configuration that prevents React Native Testing Library from working correctly.
+Please check if you are using compatible versions of React Native and React Native Testing Library.`;
+
+export function getHostComponentNames(): HostComponentNames {
+  let hostComponentNames = getConfig().hostComponentNames;
+  if (!hostComponentNames) {
+    hostComponentNames = detectHostComponentNames();
+    configureInternal({ hostComponentNames });
+  }
+
+  return hostComponentNames;
+}
+
+export function configureHostComponentNamesIfNeeded() {
+  const configHostComponentNames = getConfig().hostComponentNames;
+  if (configHostComponentNames) {
+    return;
+  }
+
+  const hostComponentNames = detectHostComponentNames();
+  configureInternal({ hostComponentNames });
+}
+
+function detectHostComponentNames(): HostComponentNames {
+  try {
+    const renderer = renderWithAct(
+      <View>
+        <Text testID="text">Hello</Text>
+        <TextInput testID="textInput" />
+        <Switch testID="switch" />
+      </View>
+    );
+
+    return {
+      text: getByTestId(renderer.root, 'text').type as string,
+      textInput: getByTestId(renderer.root, 'textInput').type as string,
+      switch: getByTestId(renderer.root, 'switch').type as string,
+    };
+  } catch (error) {
+    const errorMessage =
+      error && typeof error === 'object' && 'message' in error
+        ? error.message
+        : null;
+
+    throw new Error(
+      `Trying to detect host component names triggered the following error:\n\n${errorMessage}\n\n${userConfigErrorMessage}`
+    );
+  }
+}
+
+function getByTestId(instance: ReactTestInstance, testID: string) {
+  const nodes = instance.findAll(
+    (node) => typeof node.type === 'string' && node.props.testID === testID
+  );
+
+  if (nodes.length === 0) {
+    throw new Error(`Unable to find an element with testID: ${testID}`);
+  }
+
+  return nodes[0];
+}

package/src/helpers/matchers/__tests__/matchArrayValue.test.ts

@@ -0,0 +1,34 @@
+import { matchArrayProp } from '../matchArrayProp';
+
+test('returns true given 2 identical prop and matcher', () => {
+  expect(matchArrayProp(['banana'], ['banana'])).toEqual(true);
+  expect(matchArrayProp(['banana', 'apple'], ['banana', 'apple'])).toEqual(
+    true
+  );
+});
+
+test('returns true when the prop contains all the values of the matcher', () => {
+  expect(
+    matchArrayProp(['banana', 'apple', 'orange'], ['banana', 'orange'])
+  ).toEqual(true);
+});
+
+test('returns false when the prop does not contain all the values of the matcher', () => {
+  expect(
+    matchArrayProp(['banana', 'apple', 'orange'], ['banana', 'pear'])
+  ).toEqual(false);
+});
+
+test('returns false when prop is undefined', () => {
+  expect(matchArrayProp(undefined, ['banana'])).toEqual(false);
+});
+
+test('returns false when the matcher is an empty list', () => {
+  expect(matchArrayProp(['banana'], [])).toEqual(false);
+});
+
+test('returns false given 2 different prop and matchers', () => {
+  expect(matchArrayProp(['banana', 'apple'], ['banana', 'orange'])).toEqual(
+    false
+  );
+});

package/src/helpers/matchers/__tests__/matchObject.test.ts

@@ -0,0 +1,37 @@
+import { matchObjectProp } from '../matchObjectProp';
+
+test('returns true given 2 identical objects', () => {
+  expect(matchObjectProp({ fruit: 'banana' }, { fruit: 'banana' })).toEqual(
+    true
+  );
+  expect(
+    matchObjectProp(
+      { fruit: 'banana', isRipe: true },
+      { fruit: 'banana', isRipe: true }
+    )
+  ).toEqual(true);
+});
+
+test('returns false when one of the param is an empty object', () => {
+  expect(matchObjectProp({}, { fruit: 'banana' })).toEqual(false);
+  expect(matchObjectProp({ fruit: 'banana' }, {})).toEqual(false);
+});
+
+test('returns false given an undefined prop', () => {
+  expect(matchObjectProp(undefined, { fruit: 'banana' })).toEqual(false);
+});
+
+test('returns false given 2 different non empty objects', () => {
+  expect(matchObjectProp({ fruit: 'banana' }, { fruits: 'banana' })).toEqual(
+    false
+  );
+  expect(matchObjectProp({ fruit: 'banana' }, { fruit: 'orange' })).toEqual(
+    false
+  );
+  expect(
+    matchObjectProp(
+      { fruit: 'banana', isRipe: true },
+      { fruit: 'banana', ripe: true }
+    )
+  ).toEqual(false);
+});

package/src/helpers/matchers/__tests__/matchStringValue.test.ts

@@ -0,0 +1,15 @@
+import { matchStringProp } from '../matchStringProp';
+
+test.each`
+  prop         | matcher     | expectedResult
+  ${'hey'}     | ${'hey'}    | ${true}
+  ${'hey'}     | ${/hey/}    | ${true}
+  ${'hey'}     | ${'heyyyy'} | ${false}
+  ${'hey'}     | ${/heyyy/}  | ${false}
+  ${undefined} | ${'hey'}    | ${false}
+`(
+  'returns $expectedResult given prop $prop and matcher $matcher',
+  ({ prop, matcher, expectedResult }) => {
+    expect(matchStringProp(prop, matcher)).toEqual(expectedResult);
+  }
+);

package/src/helpers/matchers/accessibilityState.ts

@@ -0,0 +1,48 @@
+import { AccessibilityState } from 'react-native';
+import { ReactTestInstance } from 'react-test-renderer';
+import { accessibilityStateKeys } from '../accessiblity';
+
+// This type is the same as AccessibilityState from `react-native` package
+// It is re-declared here due to issues with migration from `@types/react-native` to
+// built in `react-native` types.
+// See: https://github.com/callstack/react-native-testing-library/issues/1351
+export interface AccessibilityStateMatcher {
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: boolean | 'mixed';
+  busy?: boolean;
+  expanded?: boolean;
+}
+
+/**
+ * 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: AccessibilityStateMatcher
+) {
+  const state = node.props.accessibilityState;
+  return accessibilityStateKeys.every((key) => matchState(state, matcher, key));
+}
+
+function matchState(
+  state: AccessibilityState,
+  matcher: AccessibilityStateMatcher,
+  key: keyof AccessibilityState
+) {
+  return (
+    matcher[key] === undefined ||
+    matcher[key] === (state?.[key] ?? defaultState[key])
+  );
+}

package/src/helpers/matchers/accessibilityValue.ts

@@ -0,0 +1,24 @@
+import { AccessibilityValue } from 'react-native';
+import { ReactTestInstance } from 'react-test-renderer';
+import { TextMatch } from '../../matches';
+import { matchStringProp } from './matchStringProp';
+
+export interface AccessibilityValueMatcher {
+  min?: number;
+  max?: number;
+  now?: number;
+  text?: TextMatch;
+}
+
+export function matchAccessibilityValue(
+  node: ReactTestInstance,
+  matcher: AccessibilityValueMatcher
+): boolean {
+  const value: AccessibilityValue = node.props.accessibilityValue ?? {};
+  return (
+    (matcher.min === undefined || matcher.min === value.min) &&
+    (matcher.max === undefined || matcher.max === value.max) &&
+    (matcher.now === undefined || matcher.now === value.now) &&
+    (matcher.text === undefined || matchStringProp(value.text, matcher.text))
+  );
+}

package/src/helpers/matchers/matchArrayProp.ts

@@ -0,0 +1,21 @@
+/**
+ * Matches whether given array prop contains the given value, or all given values.
+ *
+ * @param prop - The array prop to match.
+ * @param matcher - The value or values to be included in the array.
+ * @returns Whether the array prop contains the given value, or all given values.
+ */
+export function matchArrayProp(
+  prop: Array<string> | undefined,
+  matcher: string | Array<string>
+): boolean {
+  if (!prop || matcher.length === 0) {
+    return false;
+  }
+
+  if (typeof matcher === 'string') {
+    return prop.includes(matcher);
+  }
+
+  return matcher.every((e) => prop.includes(e));
+}

package/src/helpers/matchers/matchLabelText.ts

@@ -0,0 +1,51 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { matches, TextMatch, TextMatchOptions } from '../../matches';
+import { findAll } from '../findAll';
+import { matchTextContent } from './matchTextContent';
+
+export function matchLabelText(
+  root: ReactTestInstance,
+  element: ReactTestInstance,
+  text: TextMatch,
+  options: TextMatchOptions = {}
+) {
+  return (
+    matchAccessibilityLabel(element, text, options) ||
+    matchAccessibilityLabelledBy(
+      root,
+      element.props.accessibilityLabelledBy,
+      text,
+      options
+    )
+  );
+}
+
+function matchAccessibilityLabel(
+  element: ReactTestInstance,
+  text: TextMatch,
+  options: TextMatchOptions
+) {
+  const { exact, normalizer } = options;
+  return matches(text, element.props.accessibilityLabel, normalizer, exact);
+}
+
+function matchAccessibilityLabelledBy(
+  root: ReactTestInstance,
+  nativeId: string | undefined,
+  text: TextMatch,
+  options: TextMatchOptions
+) {
+  if (!nativeId) {
+    return false;
+  }
+
+  return (
+    findAll(
+      root,
+      (node) =>
+        typeof node.type === 'string' &&
+        node.props.nativeID === nativeId &&
+        matchTextContent(node, text, options)
+    ).length > 0
+  );
+}

package/src/helpers/matchers/matchObjectProp.ts

@@ -0,0 +1,25 @@
+/**
+ * check that each key value pair of the objects match
+ * BE CAREFUL it works only for 1 level deep key value pairs
+ * won't work for nested objects
+ */
+
+/**
+ * Matches whether given object prop contains all key/value pairs.
+ * @param prop - The object prop to match.
+ * @param matcher - The key/value pairs to be included in the object.
+ * @returns Whether the object prop contains all key/value pairs.
+ */
+export function matchObjectProp<T extends Record<string, unknown>>(
+  prop: T | undefined,
+  matcher: T
+): boolean {
+  if (!prop || Object.keys(matcher).length === 0) {
+    return false;
+  }
+
+  return (
+    Object.keys(prop).length !== 0 &&
+    Object.keys(matcher).every((key) => prop[key] === matcher[key])
+  );
+}