chore: bring back waitForOptions compatibility

Author: mdjastrzebski

src/queries/__tests__/labelText.test.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { TouchableOpacity, Text } from 'react-native';
+import { View, Text, TouchableOpacity } from 'react-native';
 import { render } from '../..';
 
 const BUTTON_LABEL = 'cool button';
@@ -114,3 +114,32 @@ test('getAllByLabelText, queryAllByLabelText, findAllByLabelText with exact as f
     findAllByLabelText(NO_MATCHES_TEXT, { exact: false })
   ).rejects.toThrow(getNoInstancesFoundMessage(NO_MATCHES_TEXT));
 });
+
+describe('findBy options deprecations', () => {
+  let warnSpy: jest.SpyInstance;
+  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 view = render(<View />);
+    await expect(
+      view.findByLabelText('Some Text', options)
+    ).rejects.toBeTruthy();
+
+    setTimeout(
+      () => view.rerender(<View accessibilityLabel="Some Text" />),
+      20
+    );
+    await expect(view.findByLabelText('Some Text')).resolves.toBeTruthy();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Use of option "timeout"')
+    );
+  }, 20000);
+});

src/queries/makeQueries.ts

@@ -25,13 +25,15 @@ export type QueryAllByQuery<Predicate, Options = void> = (
 
 export type FindByQuery<Predicate, Options = void> = (
   predicate: Predicate,
-  options?: Options,
+  // Remove `& WaitForOptions` when all queries have been migrated to support 2nd arg query options.
+  options?: Options & WaitForOptions,
   waitForOptions?: WaitForOptions
 ) => Promise<ReactTestInstance>;
 
 export type FindAllByQuery<Predicate, Options = void> = (
   predicate: Predicate,
-  options?: Options,
+  // Remove `& WaitForOptions` when all queries have been migrated to support 2nd arg query options.
+  options?: Options & WaitForOptions,
   waitForOptions?: WaitForOptions
 ) => Promise<ReactTestInstance[]>;
 
@@ -46,6 +48,41 @@ export type UnboundQueries<Predicate, Options> = {
   findAllBy: UnboundQuery<FindAllByQuery<Predicate, Options>>;
 };
 
+const deprecatedKeys: (keyof WaitForOptions)[] = [
+  'timeout',
+  'interval',
+  'stackTraceError',
+];
+
+// The WaitForOptions has been moved to the second option param of findBy* methods with the adding of TextMatchOptions
+// To make the migration easier and avoid a breaking change, keep reading this options from the first param but warn
+function extractDeprecatedWaitForOptions(options?: WaitForOptions) {
+  if (!options) {
+    return undefined;
+  }
+
+  const waitForOptions: WaitForOptions = {
+    timeout: options.timeout,
+    interval: options.interval,
+    stackTraceError: options.stackTraceError,
+  };
+
+  deprecatedKeys.forEach((key) => {
+    const option = options[key];
+    if (option) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `Use of option "${key}" in a findBy* query options (2nd parameter) is deprecated. Please pass this option in the waitForOptions (3rd parameter). 
+Example: 
+
+  findByText(text, {}, { ${key}: ${option.toString()} })`
+      );
+    }
+  });
+
+  return waitForOptions;
+}
+
 export function makeQueries<Predicate, Options>(
   queryAllByQuery: UnboundQuery<QueryAllByQuery<Predicate, Options>>,
   getMissingError: (predicate: Predicate, options?: Options) => string,
@@ -101,26 +138,30 @@ export function makeQueries<Predicate, Options>(
   function findAllByQuery(instance: ReactTestInstance) {
     return function findAllFn(
       predicate: Predicate,
-      queryOptions?: Options,
-      waitForOptions?: WaitForOptions
+      queryOptions?: Options & WaitForOptions,
+      waitForOptions: WaitForOptions = {}
     ) {
-      return waitFor(
-        () => getAllByQuery(instance)(predicate, queryOptions),
-        waitForOptions
-      );
+      const deprecatedWaitForOptions =
+        extractDeprecatedWaitForOptions(queryOptions);
+      return waitFor(() => getAllByQuery(instance)(predicate, queryOptions), {
+        ...deprecatedWaitForOptions,
+        ...waitForOptions,
+      });
     };
   }
 
   function findByQuery(instance: ReactTestInstance) {
     return function findFn(
       predicate: Predicate,
-      queryOptions?: Options,
-      waitForOptions?: WaitForOptions
+      queryOptions?: Options & WaitForOptions,
+      waitForOptions: WaitForOptions = {}
     ) {
-      return waitFor(
-        () => getByQuery(instance)(predicate, queryOptions),
-        waitForOptions
-      );
+      const deprecatedWaitForOptions =
+        extractDeprecatedWaitForOptions(queryOptions);
+      return waitFor(() => getByQuery(instance)(predicate, queryOptions), {
+        ...deprecatedWaitForOptions,
+        ...waitForOptions,
+      });
     };
   }