feat: add getByPlaceholder query functionality (#101)

### Summary
There is a helper that exists in `react-testing-library` to query inputs by their `placeholder`. This PR adds that support.

You **could** achieve this by querying for a `placeholder` prop, or querying for react native `TextInput`s manually and then checking their props, but it felt cleaner to have this contained in the testing library itself. It will also allow you to bypass any other instances that may have a `placeholder` prop that aren't `TextInput`s.

If we don't want to expand the surface of the library further, I completely understand that and am fine with this being closed. Just seems like it may be useful and save some time for several scenarios =)

### Test plan
+ Render a `TextInput` with a `placeholder` prop
+ Query the test instance via `getByPlaceholder` for the input
+ Verify the test instance is found

Author: danahartweg

docs/API.md

@@ -52,6 +52,14 @@ A method returning a `ReactTestInstance` with matching text – may be a string
 
 A method returning an array of `ReactTestInstance`s with matching text – may be a string or regular expression.
 
+### `getByPlaceholder: (placeholder: string | RegExp)`
+
+A method returning a `ReactTestInstance` for a `TextInput` with a matching placeholder – may be a string or regular expression. Throws when no matches.
+
+### `getAllByPlaceholder: (placeholder: string | RegExp)`
+
+A method returning an array of `ReactTestInstance`s for `TextInput`'s with a matching placeholder – may be a string or regular expression.
+
 ### `getByProps: (props: { [propName: string]: any })`
 
 A method returning a `ReactTestInstance` with matching props object. Throws when no matches.

src/__tests__/__snapshots__/render.test.js.snap

@@ -10,6 +10,18 @@ exports[`debug 1`] = `
   >
     not fresh
   </Text>
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Add custom freshness\\"
+    testID=\\"bananaCustomFreshness\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Who inspected freshness?\\"
+    testID=\\"bananaChef\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
   <View
     accessible={true}
     isTVSelectable={true}
@@ -42,6 +54,18 @@ exports[`debug changing component: bananaFresh button message should now be "fre
   >
     fresh
   </Text>
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Add custom freshness\\"
+    testID=\\"bananaCustomFreshness\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Who inspected freshness?\\"
+    testID=\\"bananaChef\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
   <View
     accessible={true}
     isTVSelectable={true}
@@ -74,6 +98,18 @@ exports[`debug: shallow 1`] = `
   >
     not fresh
   </Text>
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Add custom freshness\\"
+    testID=\\"bananaCustomFreshness\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Who inspected freshness?\\"
+    testID=\\"bananaChef\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
   <Button
     onPress={[Function anonymous]}
     type=\\"primary\\"
@@ -95,6 +131,18 @@ exports[`debug: shallow with message 1`] = `
   >
     not fresh
   </Text>
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Add custom freshness\\"
+    testID=\\"bananaCustomFreshness\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Who inspected freshness?\\"
+    testID=\\"bananaChef\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
   <Button
     onPress={[Function anonymous]}
     type=\\"primary\\"
@@ -116,6 +164,18 @@ exports[`debug: with message 1`] = `
   >
     not fresh
   </Text>
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Add custom freshness\\"
+    testID=\\"bananaCustomFreshness\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
+  <TextInput
+    allowFontScaling={true}
+    placeholder=\\"Who inspected freshness?\\"
+    testID=\\"bananaChef\\"
+    underlineColorAndroid=\\"transparent\\"
+  />
   <View
     accessible={true}
     isTVSelectable={true}

src/__tests__/render.test.js

@@ -1,10 +1,13 @@
 // @flow
 /* eslint-disable react/no-multi-comp */
 import React from 'react';
-import { View, Text, TouchableOpacity } from 'react-native';
+import { View, Text, TextInput, TouchableOpacity } from 'react-native';
 import stripAnsi from 'strip-ansi';
 import { render, fireEvent } from '..';
 
+const PLACEHOLDER_FRESHNESS = 'Add custom freshness';
+const PLACEHOLDER_CHEF = 'Who inspected freshness?';
+
 class Button extends React.Component<*> {
   render() {
     return (
@@ -45,6 +48,11 @@ class Banana extends React.Component<*, *> {
         <Text testID="bananaFresh">
           {this.state.fresh ? 'fresh' : 'not fresh'}
         </Text>
+        <TextInput
+          testID="bananaCustomFreshness"
+          placeholder={PLACEHOLDER_FRESHNESS}
+        />
+        <TextInput testID="bananaChef" placeholder={PLACEHOLDER_CHEF} />
         <Button onPress={this.changeFresh} type="primary">
           Change freshness!
         </Button>
@@ -138,6 +146,37 @@ test('getAllByText, queryAllByText', () => {
   expect(queryAllByText('InExistent')).toHaveLength(0);
 });
 
+test('getByPlaceholder, queryByPlaceholder', () => {
+  const { getByPlaceholder, queryByPlaceholder } = render(<Banana />);
+  const input = getByPlaceholder(/custom/i);
+
+  expect(input.props.placeholder).toBe(PLACEHOLDER_FRESHNESS);
+
+  const sameInput = getByPlaceholder(PLACEHOLDER_FRESHNESS);
+
+  expect(sameInput.props.placeholder).toBe(PLACEHOLDER_FRESHNESS);
+  expect(() => getByPlaceholder('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');
+});
+
+test('getAllByPlaceholder, queryAllByPlaceholder', () => {
+  const { getAllByPlaceholder, queryAllByPlaceholder } = render(<Banana />);
+  const inputs = getAllByPlaceholder(/fresh/i);
+
+  expect(inputs).toHaveLength(2);
+  expect(() => getAllByPlaceholder('no placeholder')).toThrow(
+    'No instances found'
+  );
+
+  expect(queryAllByPlaceholder(/fresh/i)).toEqual(inputs);
+  expect(queryAllByPlaceholder('no placeholder')).toHaveLength(0);
+});
+
 test('getByProps, queryByProps', () => {
   const { getByProps, queryByProps } = render(<Banana />);
   const primaryType = getByProps({ type: 'primary' });

src/helpers/getByAPI.js

@@ -28,6 +28,21 @@ const getNodeByText = (node, text) => {
   }
 };
 
+const getTextInputNodeByPlaceholder = (node, placeholder) => {
+  try {
+    // eslint-disable-next-line
+    const { TextInput } = require('react-native');
+    return (
+      filterNodeByType(node, TextInput) &&
+      (typeof placeholder === 'string'
+        ? placeholder === node.props.placeholder
+        : placeholder.test(node.props.placeholder))
+    );
+  } catch (error) {
+    throw createLibraryNotSupportedError(error);
+  }
+};
+
 const prepareErrorMessage = error =>
   // Strip info about custom predicate
   error.message.replace(/ matching custom predicate[^]*/gm, '');
@@ -62,6 +77,17 @@ export const getByText = (instance: ReactTestInstance) =>
     }
   };
 
+export const getByPlaceholder = (instance: ReactTestInstance) =>
+  function getByPlaceholderFn(placeholder: string | RegExp) {
+    try {
+      return instance.find(node =>
+        getTextInputNodeByPlaceholder(node, placeholder)
+      );
+    } catch (error) {
+      throw new ErrorWithStack(prepareErrorMessage(error), getByPlaceholderFn);
+    }
+  };
+
 export const getByProps = (instance: ReactTestInstance) =>
   function getByPropsFn(props: { [propName: string]: any }) {
     try {
@@ -114,6 +140,20 @@ export const getAllByText = (instance: ReactTestInstance) =>
     return results;
   };
 
+export const getAllByPlaceholder = (instance: ReactTestInstance) =>
+  function getAllByPlaceholderFn(placeholder: string | RegExp) {
+    const results = instance.findAll(node =>
+      getTextInputNodeByPlaceholder(node, placeholder)
+    );
+    if (results.length === 0) {
+      throw new ErrorWithStack(
+        `No instances found with placeholder: ${String(placeholder)}`,
+        getAllByPlaceholderFn
+      );
+    }
+    return results;
+  };
+
 export const getAllByProps = (instance: ReactTestInstance) =>
   function getAllByPropsFn(props: { [propName: string]: any }) {
     const results = instance.findAllByProps(props);
@@ -131,9 +171,11 @@ export const getByAPI = (instance: ReactTestInstance) => ({
   getByName: getByName(instance),
   getByType: getByType(instance),
   getByText: getByText(instance),
+  getByPlaceholder: getByPlaceholder(instance),
   getByProps: getByProps(instance),
   getAllByName: getAllByName(instance),
   getAllByType: getAllByType(instance),
   getAllByText: getAllByText(instance),
+  getAllByPlaceholder: getAllByPlaceholder(instance),
   getAllByProps: getAllByProps(instance),
 });

src/helpers/queryByAPI.js

@@ -5,10 +5,12 @@ import {
   getByName,
   getByType,
   getByText,
+  getByPlaceholder,
   getByProps,
   getAllByName,
   getAllByType,
   getAllByText,
+  getAllByPlaceholder,
   getAllByProps,
 } from './getByAPI';
 import { ErrorWithStack, logDeprecationWarning } from './errors';
@@ -48,6 +50,15 @@ export const queryByText = (instance: ReactTestInstance) =>
     }
   };
 
+export const queryByPlaceholder = (instance: ReactTestInstance) =>
+  function queryByPlaceholderFn(placeholder: string | RegExp) {
+    try {
+      return getByPlaceholder(instance)(placeholder);
+    } catch (error) {
+      return createQueryByError(error, queryByPlaceholder);
+    }
+  };
+
 export const queryByProps = (instance: ReactTestInstance) =>
   function queryByPropsFn(props: { [propName: string]: any }) {
     try {
@@ -97,6 +108,16 @@ export const queryAllByText = (instance: ReactTestInstance) => (
   }
 };
 
+export const queryAllByPlaceholder = (instance: ReactTestInstance) => (
+  placeholder: string | RegExp
+) => {
+  try {
+    return getAllByPlaceholder(instance)(placeholder);
+  } catch (error) {
+    return [];
+  }
+};
+
 export const queryAllByProps = (instance: ReactTestInstance) => (props: {
   [propName: string]: any,
 }) => {
@@ -112,9 +133,11 @@ export const queryByAPI = (instance: ReactTestInstance) => ({
   queryByName: queryByName(instance),
   queryByType: queryByType(instance),
   queryByText: queryByText(instance),
+  queryByPlaceholder: queryByPlaceholder(instance),
   queryByProps: queryByProps(instance),
   queryAllByName: queryAllByName(instance),
   queryAllByType: queryAllByType(instance),
   queryAllByText: queryAllByText(instance),
+  queryAllByPlaceholder: queryAllByPlaceholder(instance),
   queryAllByProps: queryAllByProps(instance),
 });

typings/__tests__/index.test.tsx

@@ -15,13 +15,15 @@ interface HasRequiredProp {
 
 const View = props => props.children;
 const Text = props => props.children;
+const TextInput = props => props.children;
 const ElementWithRequiredProps = (props: HasRequiredProp) => (
   <Text>{props.requiredProp}</Text>
 );
 
 const TestComponent = () => (
   <View>
     <Text>Test component</Text>
+    <TextInput placeholder="my placeholder" />
   </View>
 );
 
@@ -36,6 +38,8 @@ const getByTypeWithRequiredProps: ReactTestInstance = tree.getByType(
 );
 const getByTextString: ReactTestInstance = tree.getByText('<View />');
 const getByTextRegExp: ReactTestInstance = tree.getByText(/View/g);
+const getByPlaceholderString: ReactTestInstance = tree.getByPlaceholder('my placeholder');
+const getByPlaceholderRegExp: ReactTestInstance = tree.getByPlaceholder(/placeholder/g);
 const getByProps: ReactTestInstance = tree.getByProps({ value: 2 });
 const getByTestId: ReactTestInstance = tree.getByTestId('test-id');
 const getAllByNameString: Array<ReactTestInstance> = tree.getAllByName('View');
@@ -65,6 +69,10 @@ const queryByTextString: ReactTestInstance | null = tree.queryByText(
   '<View />'
 );
 const queryByTextRegExp: ReactTestInstance | null = tree.queryByText(/View/g);
+const queryByPlaceholderString: ReactTestInstance | null = tree.queryByText(
+  'my placeholder'
+);
+const queryByPlaceholderRegExp: ReactTestInstance | null = tree.queryByText(/placeholder/g);
 const queryByProps: ReactTestInstance | null = tree.queryByProps({ value: 2 });
 const queryByTestId: ReactTestInstance | null = tree.queryByTestId('test-id');
 const queryAllByNameString: Array<ReactTestInstance> = tree.getAllByName(

typings/index.d.ts

@@ -5,25 +5,29 @@ export interface GetByAPI {
   getByName: (name: React.ReactType | string) => ReactTestInstance;
   getByType: <P>(type: React.ComponentType<P>) => ReactTestInstance;
   getByText: (text: string | RegExp) => ReactTestInstance;
+  getByPlaceholder: (placeholder: string | RegExp) => ReactTestInstance;
   getByProps: (props: Record<string, any>) => ReactTestInstance;
   getByTestId: (testID: string) => ReactTestInstance;
   getAllByName: (name: React.ReactType | string) => Array<ReactTestInstance>;
   getAllByType: <P>(type: React.ComponentType<P>) => Array<ReactTestInstance>;
   getAllByText: (text: string | RegExp) => Array<ReactTestInstance>;
+  getAllByPlaceholder: (placeholder: string | RegExp) => Array<ReactTestInstance>;
   getAllByProps: (props: Record<string, any>) => Array<ReactTestInstance>;
 }
 
 export interface QueryByAPI {
   queryByName: (name: React.ReactType | string) => ReactTestInstance | null;
   queryByType: <P>(type: React.ComponentType<P>) => ReactTestInstance | null;
   queryByText: (name: string | RegExp) => ReactTestInstance | null;
+  queryByPlaceholder: (placeholder: string | RegExp) => ReactTestInstance | null;
   queryByProps: (props: Record<string, any>) => ReactTestInstance | null;
   queryByTestId: (testID: string) => ReactTestInstance | null;
   queryAllByName: (name: React.ReactType | string) => Array<ReactTestInstance> | [];
   queryAllByType: <P>(
     type: React.ComponentType<P>
   ) => Array<ReactTestInstance> | [];
   queryAllByText: (text: string | RegExp) => Array<ReactTestInstance> | [];
+  queryAllByPlaceholder: (placeholder: string | RegExp) => Array<ReactTestInstance> | [];
   queryAllByProps: (
     props: Record<string, any>
   ) => Array<ReactTestInstance> | [];