chore(breaking): deprecate flushMicrotasksQueue (#340)

* Deprecated flushMicrotasksQueue

* Update website/docs/Migration20.md

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

* Renamed flushMicrotasksQueueInternal to flushMicroTasks

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: mdjastrzebski

README.md

@@ -120,7 +120,6 @@ The [public API](https://callstack.github.io/react-native-testing-library/docs/a
 - [`fireEvent`](https://callstack.github.io/react-native-testing-library/docs/api#fireevent) - invokes named event handler on the element.
 - [`waitFor`](https://callstack.github.io/react-native-testing-library/docs/api#waitfor) - waits for non-deterministic periods of time until your element appears or times out.
 - [`within`](https://callstack.github.io/react-native-testing-library/docs/api#within) - creates a queries object scoped for given element.
-- [`flushMicrotasksQueue`](https://callstack.github.io/react-native-testing-library/docs/api#flushmicrotasksqueue) - waits for microtasks queue to flush.
 
 ## Migration Guides
 

src/flushMicroTasks.js

@@ -0,0 +1,15 @@
+// @flow
+
+import { printDeprecationWarning } from './helpers/errors';
+
+/**
+ * Wait for microtasks queue to flush
+ */
+export default function flushMicrotasksQueue(): Promise<any> {
+  printDeprecationWarning('flushMicrotasksQueue');
+  return flushMicroTasks();
+}
+
+export function flushMicroTasks(): Promise<any> {
+  return new Promise((resolve) => setImmediate(resolve));
+}

src/flushMicrotasksQueue.js

@@ -33,7 +33,7 @@ export function printDeprecationWarning(functionName: string) {
 
   console.warn(`
   Deprecation Warning:
-  ${functionName} is not recommended for use and will be deleted in react-native-testing-library 2.x.
+  Use of ${functionName} is not recommended and will be deleted in future versions of react-native-testing-library.
   `);
 
   warned[functionName] = true;

src/helpers/errors.js

@@ -1,6 +1,6 @@
 // @flow
-import flushMicrotasksQueue from './flushMicrotasksQueue';
 import { cleanup } from './pure';
+import { flushMicroTasks } from './flushMicroTasks';
 
 // If we're running in a test runner that supports afterEach
 // then we'll automatically run cleanup afterEach test
@@ -10,7 +10,7 @@ import { cleanup } from './pure';
 if (typeof afterEach === 'function' && !process.env.RNTL_SKIP_AUTO_CLEANUP) {
   // eslint-disable-next-line no-undef
   afterEach(async () => {
-    await flushMicrotasksQueue();
+    await flushMicroTasks();
     cleanup();
   });
 }

src/index.js

@@ -2,7 +2,7 @@
 import act from './act';
 import cleanup from './cleanup';
 import fireEvent from './fireEvent';
-import flushMicrotasksQueue from './flushMicrotasksQueue';
+import flushMicrotasksQueue from './flushMicroTasks';
 import render from './render';
 import shallow from './shallow';
 import waitFor, { waitForElement } from './waitFor';

src/pure.js

@@ -295,7 +295,6 @@ export declare const render: (
   options?: RenderOptions
 ) => RenderAPI;
 
-export declare const flushMicrotasksQueue: () => Promise<any>;
 export declare const cleanup: () => void;
 export declare const fireEvent: FireEventAPI;
 export declare const waitFor: WaitForFunction;
@@ -307,6 +306,11 @@ export declare const within: (instance: ReactTestInstance) => Queries;
  */
 export declare const waitForElement: WaitForFunction;
 
+/**
+ * @deprecated This function has been deprecated and will be removed in the next release.
+ */
+export declare const flushMicrotasksQueue: () => Promise<any>;
+
 /**
  * @deprecated This function has been removed.
  */

typings/index.d.ts

@@ -377,21 +377,6 @@ Use cases for scoped queries include:
 - queries scoped to a single item inside a FlatList containing many items
 - queries scoped to a single screen in tests involving screen transitions (e.g. with react-navigation)
 
-## `flushMicrotasksQueue`
-
-Waits for microtasks queue to flush. Useful if you want to wait for some promises with `async/await`.
-
-```jsx
-import { flushMicrotasksQueue, render } from 'react-native-testing-library';
-
-test('fetch data', async () => {
-  const { getByText } = render(<FetchData />);
-  getByText('fetch');
-  await flushMicrotasksQueue();
-  expect(getByText('fetch').props.title).toBe('loaded');
-});
-```
-
 ## `query` APIs
 
 Each of the get APIs listed in the render section above have a complimentary query API. The get APIs will throw errors if a proper node cannot be found. This is normally the desired effect. However, if you want to make an assertion that an element is not present in the hierarchy, then you can use the query API instead:

website/docs/API.md

@@ -113,3 +113,15 @@ If you relied on setting `testID` for your custom components, you should probabl
 :::caution
 In general, you should avoid `byTestId` queries when possible and rather use queries that check things that can been seen by the user (e.g. `byText`, `byPlaceholder`, etc) or accessability queries (e.g. `byA11yHint`, `byA11yLabel`, etc).
 :::
+
+## Deprecated `flushMicrotasksQueue`
+
+We have deprecated `flushMicrotasksQueue` and plan to remove it in the next major version, as currently there are better alternatives available for helping you write async tests: `findBy` async queries and `waitFor` helper.
+
+If you can't or don't want to migrate your tests, you can get rid of the deprecation warning by copy-pasting function's implementation into your project:
+
+```js
+function flushMicrotasksQueue() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+```