feat: add "cleanup" function (#237)

* feat: add "cleanup" function

* docs: add "cleanup" section

* test: "cleanup" function

* don't expose cleanup queue


Co-authored-by: Alec Larson <alec.stanford.larson@gmail.com>
Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

Author: 2 people

docs/API.md

@@ -115,6 +115,45 @@ toJSON(): ReactTestRendererJSON | null
 
 Get the rendered component JSON representation, e.g. for snapshot testing.
 
+## `cleanup`
+
+```ts
+const cleanup: () => void
+```
+
+Unmounts React trees that were mounted with `render`.
+
+For example, if you're using the `jest` testing framework, then you would need to use the `afterEach` hook like so:
+
+```jsx
+import { cleanup, render } from 'react-native-testing-library'
+import { View } from 'react-native'
+
+afterEach(cleanup)
+
+it('renders a view', () => {
+  render(<View />)
+  // ...
+})
+```
+
+The `afterEach(cleanup)` call also works in `describe` blocks:
+
+```jsx
+describe('when logged in', () => {
+  afterEach(cleanup)
+
+  it('renders the user', () => {
+    render(<SiteHeader />)
+    // ...
+  });
+})
+```
+
+Failing to call `cleanup` when you've called `render` could result in a memory leak and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).
+
+The alternative to `cleanup` is balancing every `render` with an `unmount` method call.
+
 ## `fireEvent`
 
 ```ts

src/__tests__/cleanup.test.js

@@ -0,0 +1,27 @@
+// @flow
+/* eslint-disable react/no-multi-comp */
+import React from 'react';
+import { View } from 'react-native';
+import { cleanup, render } from '..';
+
+class Test extends React.Component<*> {
+  componentWillUnmount() {
+    if (this.props.onUnmount) {
+      this.props.onUnmount();
+    }
+  }
+  render() {
+    return <View />;
+  }
+}
+
+test('cleanup', () => {
+  const fn = jest.fn();
+
+  render(<Test onUnmount={fn} />);
+  render(<Test onUnmount={fn} />);
+  expect(fn).not.toHaveBeenCalled();
+
+  cleanup();
+  expect(fn).toHaveBeenCalledTimes(2);
+});

src/cleanup.js

@@ -0,0 +1,13 @@
+// @flow
+let cleanupQueue = new Set();
+
+export default function cleanup() {
+  cleanupQueue.forEach(fn => fn());
+  cleanupQueue.clear();
+}
+
+export function addToCleanupQueue(
+  fn: (nextElement?: React$Element<any>) => void
+) {
+  cleanupQueue.add(fn);
+}

src/index.js

@@ -1,16 +1,18 @@
 // @flow
 import act from './act';
-import render from './render';
-import shallow from './shallow';
-import flushMicrotasksQueue from './flushMicrotasksQueue';
+import cleanup from './cleanup';
 import debug from './debug';
 import fireEvent from './fireEvent';
+import flushMicrotasksQueue from './flushMicrotasksQueue';
+import render from './render';
+import shallow from './shallow';
 import waitForElement from './waitForElement';
 
-export { render };
-export { shallow };
-export { flushMicrotasksQueue };
+export { act };
+export { cleanup };
 export { debug };
 export { fireEvent };
+export { flushMicrotasksQueue };
+export { render };
+export { shallow };
 export { waitForElement };
-export { act };

src/render.js

@@ -2,6 +2,7 @@
 import * as React from 'react';
 import TestRenderer, { type ReactTestRenderer } from 'react-test-renderer'; // eslint-disable-line import/no-extraneous-dependencies
 import act from './act';
+import { addToCleanupQueue } from './cleanup';
 import { getByAPI } from './helpers/getByAPI';
 import { queryByAPI } from './helpers/queryByAPI';
 import a11yAPI from './helpers/a11yAPI';
@@ -34,6 +35,8 @@ export default function render<T>(
   const update = updateWithAct(renderer, wrap);
   const instance = renderer.root;
 
+  addToCleanupQueue(renderer.unmount);
+
   return {
     ...getByAPI(instance),
     ...queryByAPI(instance),

typings/index.d.ts

@@ -135,6 +135,7 @@ export declare const shallow: <P = {}>(
   instance: ReactTestInstance | React.ReactElement<P>
 ) => { output: React.ReactElement<P> };
 export declare const flushMicrotasksQueue: () => Promise<any>;
+export declare const cleanup: () => void;
 export declare const debug: DebugAPI;
 export declare const fireEvent: FireEventAPI;
 export declare const waitForElement: WaitForElementFunction;