feat(breaking): rename ByPlaceholder to ByPlaceholderText (#455)

src/__tests__/findByApi.test.js

@@ -11,8 +11,8 @@ test('findBy queries work asynchronously', async () => {
     findAllByTestId,
     findByText,
     findAllByText,
-    findByPlaceholder,
-    findAllByPlaceholder,
+    findByPlaceholderText,
+    findAllByPlaceholderText,
     findByDisplayValue,
     findAllByDisplayValue,
   } = render(<View />);
@@ -21,10 +21,10 @@ test('findBy queries work asynchronously', async () => {
   await expect(findByText('Some Text', options)).rejects.toBeTruthy();
   await expect(findAllByText('Some Text', options)).rejects.toBeTruthy();
   await expect(
-    findByPlaceholder('Placeholder Text', options)
+    findByPlaceholderText('Placeholder Text', options)
   ).rejects.toBeTruthy();
   await expect(
-    findAllByPlaceholder('Placeholder Text', options)
+    findAllByPlaceholderText('Placeholder Text', options)
   ).rejects.toBeTruthy();
   await expect(
     findByDisplayValue('Display Value', options)
@@ -49,10 +49,10 @@ test('findBy queries work asynchronously', async () => {
   await expect(findAllByTestId('aTestId')).resolves.toHaveLength(1);
   await expect(findByText('Some Text')).resolves.toBeTruthy();
   await expect(findAllByText('Some Text')).resolves.toHaveLength(1);
-  await expect(findByPlaceholder('Placeholder Text')).resolves.toBeTruthy();
-  await expect(findAllByPlaceholder('Placeholder Text')).resolves.toHaveLength(
-    1
-  );
+  await expect(findByPlaceholderText('Placeholder Text')).resolves.toBeTruthy();
+  await expect(
+    findAllByPlaceholderText('Placeholder Text')
+  ).resolves.toHaveLength(1);
   await expect(findByDisplayValue('Display Value')).resolves.toBeTruthy();
   await expect(findAllByDisplayValue('Display Value')).resolves.toHaveLength(1);
 }, 20000);

src/__tests__/fireEvent.test.js

@@ -123,7 +123,7 @@ test('fireEvent.changeText', () => {
   const onChangeTextMock = jest.fn();
   const CHANGE_TEXT = 'content';
 
-  const { getByPlaceholder } = render(
+  const { getByPlaceholderText } = render(
     <View>
       <TextInput
         placeholder="Customer placeholder"
@@ -132,7 +132,10 @@ test('fireEvent.changeText', () => {
     </View>
   );
 
-  fireEvent.changeText(getByPlaceholder('Customer placeholder'), CHANGE_TEXT);
+  fireEvent.changeText(
+    getByPlaceholderText('Customer placeholder'),
+    CHANGE_TEXT
+  );
 
   expect(onChangeTextMock).toHaveBeenCalledWith(CHANGE_TEXT);
 });

src/__tests__/render.test.js

@@ -176,35 +176,39 @@ test('getAllByText, queryAllByText', () => {
   expect(queryAllByText('InExistent')).toHaveLength(0);
 });
 
-test('getByPlaceholder, queryByPlaceholder', () => {
-  const { getByPlaceholder, queryByPlaceholder } = render(<Banana />);
-  const input = getByPlaceholder(/custom/i);
+test('getByPlaceholderText, queryByPlaceholderText', () => {
+  const { getByPlaceholderText, queryByPlaceholderText } = render(<Banana />);
+  const input = getByPlaceholderText(/custom/i);
 
   expect(input.props.placeholder).toBe(PLACEHOLDER_FRESHNESS);
 
-  const sameInput = getByPlaceholder(PLACEHOLDER_FRESHNESS);
+  const sameInput = getByPlaceholderText(PLACEHOLDER_FRESHNESS);
 
   expect(sameInput.props.placeholder).toBe(PLACEHOLDER_FRESHNESS);
-  expect(() => getByPlaceholder('no placeholder')).toThrow(
+  expect(() => getByPlaceholderText('no placeholder')).toThrow(
     'No instances found'
   );
 
-  expect(queryByPlaceholder(/add/i)).toBe(input);
-  expect(queryByPlaceholder('no placeholder')).toBeNull();
-  expect(() => queryByPlaceholder(/fresh/)).toThrow('Expected 1 but found 2');
+  expect(queryByPlaceholderText(/add/i)).toBe(input);
+  expect(queryByPlaceholderText('no placeholder')).toBeNull();
+  expect(() => queryByPlaceholderText(/fresh/)).toThrow(
+    'Expected 1 but found 2'
+  );
 });
 
-test('getAllByPlaceholder, queryAllByPlaceholder', () => {
-  const { getAllByPlaceholder, queryAllByPlaceholder } = render(<Banana />);
-  const inputs = getAllByPlaceholder(/fresh/i);
+test('getAllByPlaceholderText, queryAllByPlaceholderText', () => {
+  const { getAllByPlaceholderText, queryAllByPlaceholderText } = render(
+    <Banana />
+  );
+  const inputs = getAllByPlaceholderText(/fresh/i);
 
   expect(inputs).toHaveLength(2);
-  expect(() => getAllByPlaceholder('no placeholder')).toThrow(
+  expect(() => getAllByPlaceholderText('no placeholder')).toThrow(
     'No instances found'
   );
 
-  expect(queryAllByPlaceholder(/fresh/i)).toEqual(inputs);
-  expect(queryAllByPlaceholder('no placeholder')).toHaveLength(0);
+  expect(queryAllByPlaceholderText(/fresh/i)).toEqual(inputs);
+  expect(queryAllByPlaceholderText('no placeholder')).toHaveLength(0);
 });
 
 test('getByDisplayValue, queryByDisplayValue', () => {

src/__tests__/within.test.js

@@ -19,7 +19,9 @@ test('within() exposes basic queries', async () => {
 
   expect(rootQueries.getAllByText('Same Text')).toHaveLength(2);
   expect(rootQueries.getAllByDisplayValue('Same Value')).toHaveLength(2);
-  expect(rootQueries.getAllByPlaceholder('Same Placeholder')).toHaveLength(2);
+  expect(rootQueries.getAllByPlaceholderText('Same Placeholder')).toHaveLength(
+    2
+  );
 
   const firstQueries = within(rootQueries.getByA11yHint('first'));
   expect(firstQueries.getAllByText('Same Text')).toHaveLength(1);
@@ -27,12 +29,12 @@ test('within() exposes basic queries', async () => {
   expect(firstQueries.queryAllByText('Same Text')).toHaveLength(1);
   expect(firstQueries.queryByText('Same Text')).toBeTruthy();
   expect(firstQueries.getByDisplayValue('Same Value')).toBeTruthy();
-  expect(firstQueries.getByPlaceholder('Same Placeholder')).toBeTruthy();
+  expect(firstQueries.getByPlaceholderText('Same Placeholder')).toBeTruthy();
   await expect(
     firstQueries.findByDisplayValue('Same Value')
   ).resolves.toBeTruthy();
   await expect(
-    firstQueries.findAllByPlaceholder('Same Placeholder')
+    firstQueries.findAllByPlaceholderText('Same Placeholder')
   ).resolves.toHaveLength(1);
 
   const secondQueries = within(rootQueries.getByA11yHint('second'));
@@ -41,7 +43,7 @@ test('within() exposes basic queries', async () => {
   expect(secondQueries.queryAllByText('Same Text')).toHaveLength(1);
   expect(secondQueries.queryByText('Same Text')).toBeTruthy();
   expect(secondQueries.getByDisplayValue('Same Value')).toBeTruthy();
-  expect(secondQueries.getByPlaceholder('Same Placeholder')).toBeTruthy();
+  expect(secondQueries.getByPlaceholderText('Same Placeholder')).toBeTruthy();
 });
 
 test('within() exposes a11y queries', async () => {

src/helpers/errors.js

@@ -44,6 +44,16 @@ export function throwRemovedFunctionError(
   docsRef: string
 ) {
   throw new Error(
-    `${functionName} has been removed in version 2.0.\n\nPlease consult: https://callstack.github.io/react-native-testing-library/docs/${docsRef}`
+    `"${functionName}" has been removed.\n\nPlease consult: https://callstack.github.io/react-native-testing-library/docs/${docsRef}`
+  );
+}
+
+export function throwRenamedFunctionError(
+  functionName: string,
+  newFunctionName: string
+) {
+  throw new ErrorWithStack(
+    `The "${functionName}" function has been renamed to "${newFunctionName}". Please replace all occurrences.`,
+    throwRenamedFunctionError
   );
 }

src/helpers/findByAPI.js

@@ -6,11 +6,12 @@ import {
   getAllByTestId,
   getByText,
   getAllByText,
-  getByPlaceholder,
-  getAllByPlaceholder,
+  getByPlaceholderText,
+  getAllByPlaceholderText,
   getByDisplayValue,
   getAllByDisplayValue,
 } from './getByAPI';
+import { throwRenamedFunctionError } from './errors';
 
 const makeFindQuery = <Text, Result>(
   instance: ReactTestInstance,
@@ -39,15 +40,16 @@ export const findAllByText = (instance: ReactTestInstance) => (
   waitForOptions: WaitForOptions = {}
 ) => makeFindQuery(instance, getAllByText, text, waitForOptions);
 
-export const findByPlaceholder = (instance: ReactTestInstance) => (
+export const findByPlaceholderText = (instance: ReactTestInstance) => (
   placeholder: string | RegExp,
   waitForOptions: WaitForOptions = {}
-) => makeFindQuery(instance, getByPlaceholder, placeholder, waitForOptions);
+) => makeFindQuery(instance, getByPlaceholderText, placeholder, waitForOptions);
 
-export const findAllByPlaceholder = (instance: ReactTestInstance) => (
+export const findAllByPlaceholderText = (instance: ReactTestInstance) => (
   placeholder: string | RegExp,
   waitForOptions: WaitForOptions = {}
-) => makeFindQuery(instance, getAllByPlaceholder, placeholder, waitForOptions);
+) =>
+  makeFindQuery(instance, getAllByPlaceholderText, placeholder, waitForOptions);
 
 export const findByDisplayValue = (instance: ReactTestInstance) => (
   value: string | RegExp,
@@ -62,10 +64,19 @@ export const findAllByDisplayValue = (instance: ReactTestInstance) => (
 export const findByAPI = (instance: ReactTestInstance) => ({
   findByTestId: findByTestId(instance),
   findByText: findByText(instance),
-  findByPlaceholder: findByPlaceholder(instance),
+  findByPlaceholderText: findByPlaceholderText(instance),
   findByDisplayValue: findByDisplayValue(instance),
   findAllByTestId: findAllByTestId(instance),
   findAllByText: findAllByText(instance),
-  findAllByPlaceholder: findAllByPlaceholder(instance),
+  findAllByPlaceholderText: findAllByPlaceholderText(instance),
   findAllByDisplayValue: findAllByDisplayValue(instance),
+
+  // Renamed
+  findByPlaceholder: () =>
+    throwRenamedFunctionError('findByPlaceholder', 'findByPlaceholderText'),
+  findAllByPlaceholder: () =>
+    throwRenamedFunctionError(
+      'findAllByPlaceholder',
+      'findAllByPlaceholderText'
+    ),
 });

src/helpers/getByAPI.js

@@ -6,6 +6,7 @@ import {
   createLibraryNotSupportedError,
   prepareErrorMessage,
   throwRemovedFunctionError,
+  throwRenamedFunctionError,
 } from './errors';
 
 const filterNodeByType = (node, type) => node.type === type;
@@ -50,7 +51,7 @@ const getChildrenAsText = (children, TextComponent, textContent = []) => {
   return textContent;
 };
 
-const getTextInputNodeByPlaceholder = (node, placeholder) => {
+const getTextInputNodeByPlaceholderText = (node, placeholder) => {
   try {
     // eslint-disable-next-line
     const { TextInput } = require('react-native');
@@ -89,14 +90,17 @@ export const getByText = (instance: ReactTestInstance) =>
     }
   };
 
-export const getByPlaceholder = (instance: ReactTestInstance) =>
-  function getByPlaceholderFn(placeholder: string | RegExp) {
+export const getByPlaceholderText = (instance: ReactTestInstance) =>
+  function getByPlaceholderTextFn(placeholder: string | RegExp) {
     try {
       return instance.find((node) =>
-        getTextInputNodeByPlaceholder(node, placeholder)
+        getTextInputNodeByPlaceholderText(node, placeholder)
       );
     } catch (error) {
-      throw new ErrorWithStack(prepareErrorMessage(error), getByPlaceholderFn);
+      throw new ErrorWithStack(
+        prepareErrorMessage(error),
+        getByPlaceholderTextFn
+      );
     }
   };
 
@@ -142,15 +146,15 @@ export const getAllByText = (instance: ReactTestInstance) =>
     return results;
   };
 
-export const getAllByPlaceholder = (instance: ReactTestInstance) =>
-  function getAllByPlaceholderFn(placeholder: string | RegExp) {
+export const getAllByPlaceholderText = (instance: ReactTestInstance) =>
+  function getAllByPlaceholderTextFn(placeholder: string | RegExp) {
     const results = instance.findAll((node) =>
-      getTextInputNodeByPlaceholder(node, placeholder)
+      getTextInputNodeByPlaceholderText(node, placeholder)
     );
     if (results.length === 0) {
       throw new ErrorWithStack(
         `No instances found with placeholder: ${String(placeholder)}`,
-        getAllByPlaceholderFn
+        getAllByPlaceholderTextFn
       );
     }
     return results;
@@ -226,11 +230,11 @@ export const UNSAFE_getAllByProps = (instance: ReactTestInstance) =>
 
 export const getByAPI = (instance: ReactTestInstance) => ({
   getByText: getByText(instance),
-  getByPlaceholder: getByPlaceholder(instance),
+  getByPlaceholderText: getByPlaceholderText(instance),
   getByDisplayValue: getByDisplayValue(instance),
   getByTestId: getByTestId(instance),
   getAllByText: getAllByText(instance),
-  getAllByPlaceholder: getAllByPlaceholder(instance),
+  getAllByPlaceholderText: getAllByPlaceholderText(instance),
   getAllByDisplayValue: getAllByDisplayValue(instance),
   getAllByTestId: getAllByTestId(instance),
 
@@ -256,4 +260,10 @@ export const getByAPI = (instance: ReactTestInstance) => ({
       'getAllByProps',
       'migration-v2#removed-functions'
     ),
+
+  // Renamed
+  getByPlaceholder: () =>
+    throwRenamedFunctionError('getByPlaceholder', 'getByPlaceholderText'),
+  getAllByPlaceholder: () =>
+    throwRenamedFunctionError('getAllByPlaceholder', 'getByPlaceholderText'),
 });

src/helpers/queryByAPI.js

@@ -3,18 +3,22 @@ import * as React from 'react';
 import {
   getByTestId,
   getByText,
-  getByPlaceholder,
+  getByPlaceholderText,
   getByDisplayValue,
   getAllByTestId,
   getAllByText,
-  getAllByPlaceholder,
+  getAllByPlaceholderText,
   getAllByDisplayValue,
   UNSAFE_getByType,
   UNSAFE_getByProps,
   UNSAFE_getAllByType,
   UNSAFE_getAllByProps,
 } from './getByAPI';
-import { createQueryByError, throwRemovedFunctionError } from './errors';
+import {
+  createQueryByError,
+  throwRemovedFunctionError,
+  throwRenamedFunctionError,
+} from './errors';
 
 export const queryByText = (instance: ReactTestInstance) =>
   function queryByTextFn(text: string | RegExp) {
@@ -25,12 +29,12 @@ export const queryByText = (instance: ReactTestInstance) =>
     }
   };
 
-export const queryByPlaceholder = (instance: ReactTestInstance) =>
-  function queryByPlaceholderFn(placeholder: string | RegExp) {
+export const queryByPlaceholderText = (instance: ReactTestInstance) =>
+  function queryByPlaceholderTextFn(placeholder: string | RegExp) {
     try {
-      return getByPlaceholder(instance)(placeholder);
+      return getByPlaceholderText(instance)(placeholder);
     } catch (error) {
-      return createQueryByError(error, queryByPlaceholderFn);
+      return createQueryByError(error, queryByPlaceholderTextFn);
     }
   };
 
@@ -62,11 +66,11 @@ export const queryAllByText = (instance: ReactTestInstance) => (
   }
 };
 
-export const queryAllByPlaceholder = (instance: ReactTestInstance) => (
+export const queryAllByPlaceholderText = (instance: ReactTestInstance) => (
   placeholder: string | RegExp
 ) => {
   try {
-    return getAllByPlaceholder(instance)(placeholder);
+    return getAllByPlaceholderText(instance)(placeholder);
   } catch (error) {
     return [];
   }
@@ -133,11 +137,11 @@ export const UNSAFE_queryAllByProps = (instance: ReactTestInstance) => (props: {
 export const queryByAPI = (instance: ReactTestInstance) => ({
   queryByTestId: queryByTestId(instance),
   queryByText: queryByText(instance),
-  queryByPlaceholder: queryByPlaceholder(instance),
+  queryByPlaceholderText: queryByPlaceholderText(instance),
   queryByDisplayValue: queryByDisplayValue(instance),
   queryAllByTestId: queryAllByTestId(instance),
   queryAllByText: queryAllByText(instance),
-  queryAllByPlaceholder: queryAllByPlaceholder(instance),
+  queryAllByPlaceholderText: queryAllByPlaceholderText(instance),
   queryAllByDisplayValue: queryAllByDisplayValue(instance),
 
   // Unsafe
@@ -168,4 +172,13 @@ export const queryByAPI = (instance: ReactTestInstance) => ({
       'queryAllByProps',
       'migration-v2#removed-functions'
     ),
+
+  // Renamed
+  queryByPlaceholder: () =>
+    throwRenamedFunctionError('queryByPlaceholder', 'queryByPlaceholderText'),
+  queryAllByPlaceholder: () =>
+    throwRenamedFunctionError(
+      'queryAllByPlaceholder',
+      'queryAllByPlaceholderText'
+    ),
 });