feat: deprecate getByName helpers (#66)

README.md

@@ -105,22 +105,6 @@ type ReactTestInstance = {
 };
 ```
 
-### `getByName: (name: React.ComponentType<*>)`
-
-A method returning a `ReactTestInstance` with matching a React component type. Throws when no matches.
-
-### `getAllByName: (name: React.ComponentType<*>)`
-
-A method returning an array of `ReactTestInstance`s with matching a React component type.
-
-### `getByType: (type: React.ComponentType<*>)`
-
-A method returning a `ReactTestInstance` with matching a React component type. Throws when no matches.
-
-### `getAllByType: (type: React.ComponentType<*>)`
-
-A method returning an array of `ReactTestInstance`s with matching a React component type.
-
 ### `getByText: (text: string | RegExp)`
 
 A method returning a `ReactTestInstance` with matching text – may be a string or regular expression. Throws when no matches.
@@ -137,6 +121,26 @@ A method returning a `ReactTestInstance` with matching props object. Throws when
 
 A method returning an array of `ReactTestInstance`s with matching props object.
 
+### `getByType: (type: React.ComponentType<*>)`
+
+A method returning a `ReactTestInstance` with matching a React component type. Throws when no matches.
+
+### `getAllByType: (type: React.ComponentType<*>)`
+
+A method returning an array of `ReactTestInstance`s with matching a React component type.
+
+### `[DEPRECATED] getByName: (name: React.ComponentType<*>)`
+
+A method returning a `ReactTestInstance` with matching a React component type. Throws when no matches.
+
+> This method has been **deprecated** because using it results in fragile tests that may break between minor React Native versions. It will be removed in next major release (v2.0). Use [`getByType`](#getbytype-type-reactcomponenttype) instead.
+
+### `[DEPRECATED] getAllByName: (name: React.ComponentType<*>)`
+
+A method returning an array of `ReactTestInstance`s with matching a React component type.
+
+> This method has been **deprecated** because using it results in fragile tests that may break between minor React Native versions. It will be removed in next major release (v2.0). Use [`getAllByType`](#getallbytype-type-reactcomponenttype) instead.
+
 ### `update: (element: React.Element<*>) => void`
 
 Re-render the in-memory tree with a new root element. This simulates a React update at the root. If the new element has the same type and key as the previous element, the tree will be updated; otherwise, it will re-mount a new tree.

src/helpers/errors.js

@@ -14,3 +14,27 @@ export const createLibraryNotSupportedError = (error: Error) =>
       error.message
     }`
   );
+
+const warned = {
+  getByName: false,
+  getAllByName: false,
+  queryByName: false,
+  queryAllByName: false,
+};
+
+export const logDeprecationWarning = (
+  deprecatedFnName: string,
+  alternativeFnName: string
+) => {
+  if (warned[deprecatedFnName]) {
+    return;
+  }
+  console.warn(`Deprecation Warning:
+
+  "${deprecatedFnName}" is deprecated and will be removed in next major release. Please use "${alternativeFnName}" instead.
+
+  Docs: https://github.com/callstack/react-native-testing-library#${alternativeFnName.toLowerCase()}-type-reactcomponenttype
+    `);
+
+  warned[deprecatedFnName] = true;
+};

src/helpers/getByAPI.js

@@ -1,7 +1,11 @@
 // @flow
 import * as React from 'react';
 import prettyFormat from 'pretty-format';
-import { ErrorWithStack, createLibraryNotSupportedError } from './errors';
+import {
+  ErrorWithStack,
+  createLibraryNotSupportedError,
+  logDeprecationWarning,
+} from './errors';
 
 const filterNodeByType = (node, type) => node.type === type;
 
@@ -28,9 +32,9 @@ const prepareErrorMessage = error =>
   // Strip info about custom predicate
   error.message.replace(/ matching custom predicate[^]*/gm, '');
 
-// TODO: deprecate getByName(string | type) in favor of getByType(type)
 export const getByName = (instance: ReactTestInstance) =>
   function getByNameFn(name: string | React.ComponentType<*>) {
+    logDeprecationWarning('getByName', 'getByType');
     try {
       return typeof name === 'string'
         ? instance.find(node => filterNodeByName(node, name))
@@ -76,9 +80,9 @@ export const getByTestId = (instance: ReactTestInstance) =>
     }
   };
 
-// TODO: deprecate getAllByName(string | type) in favor of getAllByType(type)
 export const getAllByName = (instance: ReactTestInstance) =>
   function getAllByNameFn(name: string | React.ComponentType<*>) {
+    logDeprecationWarning('getAllByName', 'getAllByType');
     const results =
       typeof name === 'string'
         ? instance.findAll(node => filterNodeByName(node, name))

src/helpers/queryByAPI.js

@@ -11,10 +11,12 @@ import {
   getAllByText,
   getAllByProps,
 } from './getByAPI';
+import { logDeprecationWarning } from './errors';
 
 export const queryByName = (instance: ReactTestInstance) => (
   name: string | React.ComponentType<*>
 ) => {
+  logDeprecationWarning('queryByName', 'getByName');
   try {
     return getByName(instance)(name);
   } catch (error) {
@@ -65,6 +67,7 @@ export const queryByTestId = (instance: ReactTestInstance) => (
 export const queryAllByName = (instance: ReactTestInstance) => (
   name: string | React.ComponentType<*>
 ) => {
+  logDeprecationWarning('queryAllByName', 'getAllByName');
   try {
     return getAllByName(instance)(name);
   } catch (error) {