feat(breaking): add text match options a.k.a string precision API (#554)

* Add TextMatch options to getByAPI

* Add TextMatch options to queryByAPI

* Add TextMatch options to findByAPI

* Add tests covering new TextMatch options

* Add documentation and examples for TextMatch options

* Implement text match normalization customization

* Implement tests for normalization options

* Add text normalization docs

* Refactor typings

* Add export for getDefaultNormalizer function

* Remove undocumented config for normalizer function

* Update website/docs/Queries.md

Co-authored-by: Maciej Jastrzebski <mdjastrzebski@gmail.com>

* BREAKING: make findBy* queries arguments order compatible with RTL

* Fix tests for findBy queries after changing their API

* Fix matching nested Text components with queryOptions exact set to true

* Remove recursion matching for *byText APIs

* Reuse getAllByText in getByText

* Add Textmatch options to *byTestId

* fix: types for getDefaultNormalizer

* refactor: remove makeNormalizer and use getDefaultNormalizer() instead

* refactor: change params position and description for matches

* refactor: move & remove duplicated tests after merge

* Make waitForOptions param change non breaking change

* chore: cleanup and type fixups

* tests: update snapshots

* chore: use default arg value for normalizer

* Restore mock after use

* fix: wrong snapshot update with outdated deps

Co-authored-by: Rafał Zakrzewski <zakrzewski.rafal@gmail.com>
Co-authored-by: Michał Pierzchała <thymikee@gmail.com>
Co-authored-by: Maciej Jastrzebski <mdjastrzebski@gmail.com>
Co-authored-by: Damian Sznajder <damsznajder@gmail.com>

Author: 5 people

src/__tests__/byDisplayValue.test.js

@@ -81,10 +81,10 @@ test('findBy queries work asynchronously', async () => {
   );
 
   await expect(
-    findByDisplayValue('Display Value', options)
+    findByDisplayValue('Display Value', {}, options)
   ).rejects.toBeTruthy();
   await expect(
-    findAllByDisplayValue('Display Value', options)
+    findAllByDisplayValue('Display Value', {}, options)
   ).rejects.toBeTruthy();
 
   setTimeout(

src/__tests__/byTestId.test.js

@@ -115,8 +115,8 @@ test('getAllByTestId, queryAllByTestId', () => {
 test('findByTestId and findAllByTestId work asynchronously', async () => {
   const options = { timeout: 10 }; // Short timeout so that this test runs quickly
   const { rerender, findByTestId, findAllByTestId } = render(<View />);
-  await expect(findByTestId('aTestId', options)).rejects.toBeTruthy();
-  await expect(findAllByTestId('aTestId', options)).rejects.toBeTruthy();
+  await expect(findByTestId('aTestId', {}, options)).rejects.toBeTruthy();
+  await expect(findAllByTestId('aTestId', {}, options)).rejects.toBeTruthy();
 
   setTimeout(
     () =>

src/__tests__/byText.test.js

@@ -1,7 +1,14 @@
 // @flow
 import * as React from 'react';
-import { View, Text, TouchableOpacity, Image } from 'react-native';
-import { render } from '..';
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  Image,
+  Button,
+  TextInput,
+} from 'react-native';
+import { render, getDefaultNormalizer } from '..';
 
 const MyButton = ({ children, onPress }) => (
   <TouchableOpacity onPress={onPress}>
@@ -88,8 +95,8 @@ test('getAllByText, queryAllByText', () => {
 test('findByText queries work asynchronously', async () => {
   const options = { timeout: 10 }; // Short timeout so that this test runs quickly
   const { rerender, findByText, findAllByText } = render(<View />);
-  await expect(findByText('Some Text', options)).rejects.toBeTruthy();
-  await expect(findAllByText('Some Text', options)).rejects.toBeTruthy();
+  await expect(findByText('Some Text', {}, options)).rejects.toBeTruthy();
+  await expect(findAllByText('Some Text', {}, options)).rejects.toBeTruthy();
 
   setTimeout(
     () =>
@@ -105,6 +112,39 @@ test('findByText queries work asynchronously', async () => {
   await expect(findAllByText('Some Text')).resolves.toHaveLength(1);
 }, 20000);
 
+describe('findBy options deprecations', () => {
+  let warnSpy;
+  beforeEach(() => {
+    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test('findByText queries warn on deprecated use of WaitForOptions', async () => {
+    const options = { timeout: 10 };
+    // mock implementation to avoid warning in the test suite
+    const { rerender, findByText } = render(<View />);
+    await expect(findByText('Some Text', options)).rejects.toBeTruthy();
+
+    setTimeout(
+      () =>
+        rerender(
+          <View>
+            <Text>Some Text</Text>
+          </View>
+        ),
+      20
+    );
+
+    await expect(findByText('Some Text')).resolves.toBeTruthy();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Use of option "timeout"')
+    );
+  }, 20000);
+});
+
 test.skip('getByText works properly with custom text component', () => {
   function BoldText({ children }) {
     return <Text>{children}</Text>;
@@ -181,7 +221,7 @@ test('queryByText not found', () => {
   ).toBeFalsy();
 });
 
-test('queryByText nested text across multiple <Text> in <Text>', () => {
+test('queryByText does not match nested text across multiple <Text> in <Text>', () => {
   const { queryByText } = render(
     <Text nativeID="1">
       Hello{' '}
@@ -192,7 +232,7 @@ test('queryByText nested text across multiple <Text> in <Text>', () => {
     </Text>
   );
 
-  expect(queryByText('Hello World!')?.props.nativeID).toBe('1');
+  expect(queryByText('Hello World!')).toBe(null);
 });
 
 test('queryByText with nested Text components return the closest Text', () => {
@@ -204,7 +244,7 @@ test('queryByText with nested Text components return the closest Text', () => {
 
   const { queryByText } = render(<NestedTexts />);
 
-  expect(queryByText('My text')?.props.nativeID).toBe('2');
+  expect(queryByText('My text', { exact: false })?.props.nativeID).toBe('2');
 });
 
 test('queryByText with nested Text components each with text return the lowest one', () => {
@@ -217,33 +257,182 @@ test('queryByText with nested Text components each with text return the lowest o
 
   const { queryByText } = render(<NestedTexts />);
 
-  expect(queryByText('My text')?.props.nativeID).toBe('2');
+  expect(queryByText('My text', { exact: false })?.props.nativeID).toBe('2');
 });
 
-test('queryByText nested <CustomText> in <Text>', () => {
+test('queryByText nested deep <CustomText> in <Text>', () => {
   const CustomText = ({ children }) => {
     return <Text>{children}</Text>;
   };
 
   expect(
     render(
       <Text>
-        Hello <CustomText>World!</CustomText>
+        <CustomText>Hello</CustomText> <CustomText>World!</CustomText>
       </Text>
     ).queryByText('Hello World!')
-  ).toBeTruthy();
+  ).toBe(null);
 });
 
-test('queryByText nested deep <CustomText> in <Text>', () => {
-  const CustomText = ({ children }) => {
-    return <Text>{children}</Text>;
-  };
+test('queryByText with nested Text components: not-exact text match returns the most deeply nested common component', () => {
+  const { queryByText: queryByTextFirstCase } = render(
+    <Text nativeID="1">
+      bob
+      <Text nativeID="2">My </Text>
+      <Text nativeID="3">text</Text>
+    </Text>
+  );
+
+  const { queryByText: queryByTextSecondCase } = render(
+    <Text nativeID="1">
+      bob
+      <Text nativeID="2">My text for test</Text>
+    </Text>
+  );
 
+  expect(queryByTextFirstCase('My text')).toBe(null);
   expect(
-    render(
-      <Text>
-        <CustomText>Hello</CustomText> <CustomText>World!</CustomText>
-      </Text>
-    ).queryByText('Hello World!')
-  ).toBeTruthy();
+    queryByTextSecondCase('My text', { exact: false })?.props.nativeID
+  ).toBe('2');
+});
+
+test('queryAllByText does not match several times the same text', () => {
+  const allMatched = render(
+    <Text nativeID="1">
+      Start
+      <Text nativeID="2">This is a long text</Text>
+    </Text>
+  ).queryAllByText('long text', { exact: false });
+  expect(allMatched.length).toBe(1);
+  expect(allMatched[0].props.nativeID).toBe('2');
+});
+
+test('queryAllByText matches all the matching nodes', () => {
+  const allMatched = render(
+    <Text nativeID="1">
+      Start
+      <Text nativeID="2">This is a long text</Text>
+      <Text nativeID="3">This is another long text</Text>
+    </Text>
+  ).queryAllByText('long text', { exact: false });
+  expect(allMatched.length).toBe(2);
+  expect(allMatched.map((node) => node.props.nativeID)).toEqual(['2', '3']);
+});
+
+describe('supports TextMatch options', () => {
+  test('getByText, getAllByText', () => {
+    const { getByText, getAllByText } = render(
+      <View>
+        <Text testID="text">Text and details</Text>
+        <Button
+          testID="button"
+          title="Button and a detail"
+          onPress={jest.fn()}
+        />
+      </View>
+    );
+
+    expect(getByText('details', { exact: false })).toBeTruthy();
+    expect(getAllByText('detail', { exact: false })).toHaveLength(2);
+  });
+
+  test('getByPlaceholderText, getAllByPlaceholderText', () => {
+    const { getByPlaceholderText, getAllByPlaceholderText } = render(
+      <View>
+        <TextInput placeholder={'Placeholder with details'} />
+        <TextInput placeholder={'Placeholder with a DETAIL'} />
+      </View>
+    );
+
+    expect(getByPlaceholderText('details', { exact: false })).toBeTruthy();
+    expect(getAllByPlaceholderText('detail', { exact: false })).toHaveLength(2);
+  });
+
+  test('getByDisplayValue, getAllByDisplayValue', () => {
+    const { getByDisplayValue, getAllByDisplayValue } = render(
+      <View>
+        <TextInput value={'Value with details'} />
+        <TextInput value={'Value with a detail'} />
+      </View>
+    );
+
+    expect(getByDisplayValue('details', { exact: false })).toBeTruthy();
+    expect(getAllByDisplayValue('detail', { exact: false })).toHaveLength(2);
+  });
+
+  test('getByTestId, getAllByTestId', () => {
+    const { getByTestId, getAllByTestId } = render(
+      <View>
+        <View testID="test" />
+        <View testID="tests id" />
+      </View>
+    );
+    expect(getByTestId('id', { exact: false })).toBeTruthy();
+    expect(getAllByTestId('test', { exact: false })).toHaveLength(2);
+  });
+
+  test('with TextMatch option exact === false text search is NOT case sensitive', () => {
+    const { getByText, getAllByText } = render(
+      <View>
+        <Text testID="text">Text and details</Text>
+        <Button
+          testID="button"
+          title="Button and a DeTAil"
+          onPress={jest.fn()}
+        />
+      </View>
+    );
+
+    expect(getByText('DeTaIlS', { exact: false })).toBeTruthy();
+    expect(getAllByText('detail', { exact: false })).toHaveLength(2);
+  });
+});
+
+describe('Supports normalization', () => {
+  test('trims and collapses whitespace by default', () => {
+    const { getByText } = render(
+      <View>
+        <Text>{`  Text     and
+
+
+        whitespace`}</Text>
+      </View>
+    );
+
+    expect(getByText('Text and whitespace')).toBeTruthy();
+  });
+
+  test('trim and collapseWhitespace is customizable by getDefaultNormalizer param', () => {
+    const testTextWithWhitespace = `  Text     and
+
+
+        whitespace`;
+    const { getByText } = render(
+      <View>
+        <Text>{testTextWithWhitespace}</Text>
+      </View>
+    );
+
+    expect(
+      getByText(testTextWithWhitespace, {
+        normalizer: getDefaultNormalizer({
+          trim: false,
+          collapseWhitespace: false,
+        }),
+      })
+    ).toBeTruthy();
+  });
+
+  test('normalizer function is customisable', () => {
+    const testText = 'A TO REMOVE text';
+    const normalizerFn = (textToNormalize) =>
+      textToNormalize.replace('TO REMOVE ', '');
+    const { getByText } = render(
+      <View>
+        <Text>{testText}</Text>
+      </View>
+    );
+
+    expect(getByText('A text', { normalizer: normalizerFn })).toBeTruthy();
+  });
 });

src/helpers/byDisplayValue.js

@@ -1,19 +1,26 @@
 // @flow
+import { matches } from '../matches';
 import { makeQueries } from './makeQueries';
 import type { Queries } from './makeQueries';
 import { filterNodeByType } from './filterNodeByType';
 import { createLibraryNotSupportedError } from './errors';
+import type { TextMatchOptions } from './byText';
 
-const getTextInputNodeByDisplayValue = (node, value) => {
+const getTextInputNodeByDisplayValue = (
+  node,
+  value,
+  options?: TextMatchOptions = {}
+) => {
   try {
     const { TextInput } = require('react-native');
+    const { exact, normalizer } = options;
     const nodeValue =
       node.props.value !== undefined
         ? node.props.value
         : node.props.defaultValue;
     return (
       filterNodeByType(node, TextInput) &&
-      (typeof value === 'string' ? value === nodeValue : value.test(nodeValue))
+      matches(value, nodeValue, normalizer, exact)
     );
   } catch (error) {
     throw createLibraryNotSupportedError(error);
@@ -22,10 +29,13 @@ const getTextInputNodeByDisplayValue = (node, value) => {
 
 const queryAllByDisplayValue = (
   instance: ReactTestInstance
-): ((displayValue: string | RegExp) => Array<ReactTestInstance>) =>
-  function queryAllByDisplayValueFn(displayValue) {
+): ((
+  displayValue: string | RegExp,
+  queryOptions?: TextMatchOptions
+) => Array<ReactTestInstance>) =>
+  function queryAllByDisplayValueFn(displayValue, queryOptions) {
     return instance.findAll((node) =>
-      getTextInputNodeByDisplayValue(node, displayValue)
+      getTextInputNodeByDisplayValue(node, displayValue, queryOptions)
     );
   };