Merge master in pr/async-utils

Author: mpeyper

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,7 +14,6 @@ Please fill out the information below to expedite the review and (hopefully)
 merge of your pull request!
 -->
 
-
 **What**:
 
 <!-- What changes are being made? (What feature/bug is being fixed here?) -->
@@ -38,7 +37,6 @@ Remove any items that are relevant to your changes
 
 - [ ] Documentation updated
 - [ ] Tests
-- [ ] Typescript definitions updated
 - [ ] Ready to be merged
       <!-- In your opinion, is this ready to be merged as soon as it's reviewed? -->
 - [ ] Added myself to contributors table

docs/api-reference.md

@@ -9,6 +9,7 @@ route: '/reference/api'
 
 - [`renderHook`](/reference/api#renderhook)
 - [`act`](/reference/api#act)
+- [`cleanup`](/reference/api#cleanup)
 
 ---
 
@@ -101,6 +102,43 @@ This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act)
 
 ---
 
+## `cleanup`
+
+```js
+function cleanup: Promise<void>
+```
+
+Unmounts any rendered hooks rendered with `renderHook`, ensuring all effects have been flushed.
+
+> Please note that this is done automatically if the testing framework you're using supports the
+> `afterEach` global (like Jest, mocha and Jasmine). If not, you will need to do manual cleanups
+> after each test.
+
+The `cleanup` function should be called after each test to ensure that previously rendered hooks
+will not have any unintended side-effects on the following tests.
+
+### Skipping Auto-Cleanup
+
+Importing `@testing-library/react-hooks/dont-cleanup-after-each.js` in test setup files will disable
+the auto-cleanup feature.
+
+For example, in [Jest](https://jestjs.io/) this can be added to your
+[Jest config](https://jestjs.io/docs/configuration):
+
+```js
+module.exports = {
+  setupFilesAfterEnv: [
+    '@testing-library/react-hooks/dont-cleanup-after-each.js'
+    // other setup files
+  ]
+}
+```
+
+Alternatively, setting the `RHTL_SKIP_AUTO_CLEANUP` environment variable to `true` before importing
+`@testing-library/react-hooks` will also disable this feature.
+
+---
+
 ## Async Utilities
 
 ### `waitForNextUpdate`

dont-cleanup-after-each.js

@@ -0,0 +1 @@
+process.env.RHTL_SKIP_AUTO_CLEANUP = true

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@testing-library/react-hooks",
-  "version": "2.0.3",
+  "version": "3.1.0",
   "description": "Simple and complete React hooks testing utilities that encourage good testing practices.",
   "main": "lib/index.js",
   "keywords": [

package.json

@@ -0,0 +1,26 @@
+import { act } from 'react-test-renderer'
+
+let cleanupCallbacks = []
+
+async function cleanup() {
+  await act(async () => {})
+  cleanupCallbacks.forEach((cb) => cb())
+  cleanupCallbacks = []
+}
+
+function addCleanup(callback) {
+  cleanupCallbacks.push(callback)
+}
+
+function removeCleanup(callback) {
+  cleanupCallbacks = cleanupCallbacks.filter((cb) => cb !== callback)
+}
+
+// Automatically registers cleanup in supported testing frameworks
+if (typeof afterEach === 'function' && !process.env.RHTL_SKIP_AUTO_CLEANUP) {
+  afterEach(async () => {
+    await cleanup()
+  })
+}
+
+export { cleanup, addCleanup, removeCleanup }

src/cleanup.js

@@ -1,6 +1,7 @@
 import React, { Suspense } from 'react'
 import { act, create } from 'react-test-renderer'
 import asyncUtils from './asyncUtils'
+import { cleanup, addCleanup, removeCleanup } from './cleanup'
 
 function TestHook({ callback, hookProps, onError, children }) {
   try {
@@ -74,6 +75,15 @@ function renderHook(callback, { initialProps, wrapper } = {}) {
   })
   const { unmount, update } = testRenderer
 
+  function unmountHook() {
+    act(() => {
+      removeCleanup(unmountHook)
+      unmount()
+    })
+  }
+
+  addCleanup(unmountHook)
+
   return {
     result,
     rerender: (newProps = hookProps.current) => {
@@ -82,13 +92,9 @@ function renderHook(callback, { initialProps, wrapper } = {}) {
         update(toRender())
       })
     },
-    unmount: () => {
-      act(() => {
-        unmount()
-      })
-    },
+    unmount: unmountHook,
     ...asyncUtils(addResolver)
   }
 }
 
-export { renderHook, act }
+export { renderHook, cleanup, act }

src/index.js

@@ -0,0 +1,28 @@
+import { useEffect } from 'react'
+
+// This verifies that if RHTL_SKIP_AUTO_CLEANUP is set
+// then we DON'T auto-wire up the afterEach for folks
+describe('skip auto cleanup (disabled) tests', () => {
+  let cleanupCalled = false
+  let renderHook
+
+  beforeAll(() => {
+    process.env.RHTL_SKIP_AUTO_CLEANUP = 'true'
+    renderHook = require('src').renderHook
+  })
+
+  test('first', () => {
+    const hookWithCleanup = () => {
+      useEffect(() => {
+        return () => {
+          cleanupCalled = true
+        }
+      })
+    }
+    renderHook(() => hookWithCleanup())
+  })
+
+  test('second', () => {
+    expect(cleanupCalled).toBe(false)
+  })
+})

test/autoCleanup.disabled.test.js

@@ -0,0 +1,28 @@
+import { useEffect } from 'react'
+
+// This verifies that if RHTL_SKIP_AUTO_CLEANUP is set
+// then we DON'T auto-wire up the afterEach for folks
+describe('skip auto cleanup (no afterEach) tests', () => {
+  let cleanupCalled = false
+  let renderHook
+
+  beforeAll(() => {
+    afterEach = false
+    renderHook = require('src').renderHook
+  })
+
+  test('first', () => {
+    const hookWithCleanup = () => {
+      useEffect(() => {
+        return () => {
+          cleanupCalled = true
+        }
+      })
+    }
+    renderHook(() => hookWithCleanup())
+  })
+
+  test('second', () => {
+    expect(cleanupCalled).toBe(false)
+  })
+})

test/autoCleanup.noAfterEach.test.js

@@ -0,0 +1,24 @@
+import { useEffect } from 'react'
+import { renderHook } from 'src'
+
+// This verifies that by importing RHTL in an
+// environment which supports afterEach (like jest)
+// we'll get automatic cleanup between tests.
+describe('auto cleanup tests', () => {
+  let cleanupCalled = false
+
+  test('first', () => {
+    const hookWithCleanup = () => {
+      useEffect(() => {
+        return () => {
+          cleanupCalled = true
+        }
+      })
+    }
+    renderHook(() => hookWithCleanup())
+  })
+
+  test('second', () => {
+    expect(cleanupCalled).toBe(true)
+  })
+})

test/autoCleanup.test.js

@@ -0,0 +1,41 @@
+import { useEffect } from 'react'
+import { renderHook, cleanup } from 'src'
+
+describe('cleanup tests', () => {
+  test('should flush effects on cleanup', async () => {
+    let cleanupCalled = false
+
+    const hookWithCleanup = () => {
+      useEffect(() => {
+        return () => {
+          cleanupCalled = true
+        }
+      })
+    }
+
+    renderHook(() => hookWithCleanup())
+
+    await cleanup()
+
+    expect(cleanupCalled).toBe(true)
+  })
+
+  test('should cleanup all rendered hooks', async () => {
+    let cleanupCalled = []
+    const hookWithCleanup = (id) => {
+      useEffect(() => {
+        return () => {
+          cleanupCalled[id] = true
+        }
+      })
+    }
+
+    renderHook(() => hookWithCleanup(1))
+    renderHook(() => hookWithCleanup(2))
+
+    await cleanup()
+
+    expect(cleanupCalled[1]).toBe(true)
+    expect(cleanupCalled[2]).toBe(true)
+  })
+})