Refactored waitForValueToChange to use wait under the hook and updated docs

Author: mpeyper

docs/api-reference.md

@@ -103,32 +103,33 @@ This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act)
 
 ## Async Utilities
 
-### `wait`
+### `waitForNextUpdate`
 
 ```js
-function wait(callback: function(): boolean|void, options?: WaitOptions): Promise<void>
+function waitForNextUpdate(options?: WaitOptions): Promise<void>
 ```
 
-Returns a `Promise` that resolves if the provided callback executes without exception and returns a
-truthy or `undefined` value. It is safe to use the [`result` of `renderHook`](/reference/api#result)
-in the callback to perform assertion or to test values.
-
-The callback is tested after each render of the hook.
+Returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as
+the result of an asynchronous update.
 
-See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
-`options` parameter.
+See the [`wait` Options](/reference/api#wait-options) section for more details on the available
+`options`.
 
-### `waitForNextUpdate`
+### `wait`
 
 ```js
-function waitForNextUpdate(options?: WaitOptions): Promise<void>
+function wait(callback: function(): boolean|void, options?: WaitOptions): Promise<void>
 ```
 
-Returns a `Promise` that resolves the next time the hook renders, commonly when state is updated as
-the result of an asynchronous update.
+Returns a `Promise` that resolves if the provided callback executes without exception and returns a
+truthy or `undefined` value. It is safe to use the [`result` of `renderHook`](/reference/api#result)
+in the callback to perform assertion or to test values.
+
+The callback is tested after each render of the hook. By default, errors raised from the callback
+will be suppressed (`suppressErrors = true`).
 
-See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
-`options` parameter.
+See the [`wait` Options](/reference/api#wait-options) section for more details on the available
+`options`.
 
 ### `waitForValueToChange`
 
@@ -140,10 +141,11 @@ Returns a `Promise` that resolves if the value returned from the provided select
 expected that the [`result` of `renderHook`](/reference/api#result) to select the value for
 comparison.
 
-The value is selected for comparison after each render of the hook.
+The value is selected for comparison after each render of the hook. By default, errors raised from
+selecting the value will not be suppressed (`suppressErrors = false`).
 
-See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
-`options` parameter.
+See the [`wait` Options](/reference/api#wait-options) section for more details on the available
+`options`.
 
 ### `wait` Options
 
@@ -152,3 +154,10 @@ The async utilities accepts the following options:
 #### `timeout`
 
 The maximum amount of time in milliseconds (ms) to wait. By default, no timeout is applied.
+
+#### `suppressErrors`
+
+If this option is set to `true`, any errors that occur while waiting are treated as a failed check.
+If this option is set to `false`, any errors that occur while waiting cause the promise to be
+rejected. Please refer to the [utility descriptions](/reference/api#async-utilities) for the default
+values of this option (if applicable).

docs/usage/advanced-hooks.md

@@ -95,9 +95,9 @@ you, your team, and your project.
 ## Async
 
 Sometimes, a hook can trigger asynchronous updates that will not be immediately reflected in the
-`result.current` value. Luckily, `renderHook` returns a utility that allows the test to wait for the
-hook to update using `async/await` (or just promise callbacks if you prefer) called
-`waitForNextUpdate`.
+`result.current` value. Luckily, `renderHook` returns some utilities that allows the test to wait
+for the hook to update using `async/await` (or just promise callbacks if you prefer). The most basic
+async utility is called `waitForNextUpdate`.
 
 Let's further extend `useCounter` to have an `incrementAsync` callback that will update the `count`
 after `100ms`:
@@ -132,11 +132,14 @@ test('should increment counter after delay', async () => {
 })
 ```
 
+For more details on the the other async utilities, please refer to the
+[API Reference](/reference/api#async-utilities).
+
 ### Suspense
 
-`waitForNextUpdate` will also wait for hooks that suspends using
-[React's `Suspense`](https://reactjs.org/docs/code-splitting.html#suspense) functionality finish
-rendering.
+All the [async utilities](/reference/api#async-utilities) will also wait for hooks that suspends
+using [React's `Suspense`](https://reactjs.org/docs/code-splitting.html#suspense) functionality to
+complete rendering.
 
 ## Errors
 

src/asyncUtils.js

@@ -1,14 +1,6 @@
 import { act } from 'react-test-renderer'
 
-function actForResult(callback) {
-  let value
-  act(() => {
-    value = callback()
-  })
-  return value
-}
-
-function createTimeoutError(utilName, timeout) {
+function createTimeoutError(utilName, { timeout }) {
   const timeoutError = new Error(`Timed out in ${utilName} after ${timeout}ms.`)
   timeoutError.timeout = true
   return timeoutError
@@ -17,65 +9,77 @@ function createTimeoutError(utilName, timeout) {
 function asyncUtils(addResolver) {
   let nextUpdatePromise = null
 
-  const resolveOnNextUpdate = ({ timeout }) => (resolve, reject) => {
-    let timeoutId
-    if (timeout > 0) {
-      timeoutId = setTimeout(
-        () => reject(createTimeoutError('waitForNextUpdate', timeout)),
-        timeout
-      )
-    }
-    addResolver(() => {
-      clearTimeout(timeoutId)
-      nextUpdatePromise = null
-      resolve()
-    })
-  }
-
   const waitForNextUpdate = async (options = {}) => {
     if (!nextUpdatePromise) {
-      nextUpdatePromise = new Promise(resolveOnNextUpdate(options))
+      const resolveOnNextUpdate = (resolve, reject) => {
+        let timeoutId
+        if (options.timeout > 0) {
+          timeoutId = setTimeout(
+            () => reject(createTimeoutError('waitForNextUpdate', options)),
+            options.timeout
+          )
+        }
+        addResolver(() => {
+          clearTimeout(timeoutId)
+          nextUpdatePromise = null
+          resolve()
+        })
+      }
+
+      nextUpdatePromise = new Promise(resolveOnNextUpdate)
       await act(() => nextUpdatePromise)
     }
     return await nextUpdatePromise
   }
 
-  const wait = async (callback, options = {}) => {
-    const initialTimeout = options.timeout
-    while (true) {
-      const startTime = Date.now()
+  const wait = async (callback, { timeout, suppressErrors = true } = {}) => {
+    const checkResult = () => {
       try {
-        await waitForNextUpdate(options)
-        const callbackResult = actForResult(callback)
-        if (callbackResult || callbackResult === undefined) {
-          break
-        }
+        const callbackResult = callback()
+        return callbackResult || callbackResult === undefined
       } catch (e) {
-        if (e.timeout) {
-          throw createTimeoutError('wait', initialTimeout)
+        if (!suppressErrors) {
+          throw e
         }
       }
-      options.timeout -= Date.now() - startTime
+    }
+
+    const waitForResult = async () => {
+      const initialTimeout = timeout
+      while (true) {
+        const startTime = Date.now()
+        try {
+          await waitForNextUpdate({ timeout })
+          if (checkResult()) {
+            return
+          }
+        } catch (e) {
+          if (e.timeout) {
+            throw createTimeoutError('wait', { timeout: initialTimeout })
+          }
+          throw e
+        }
+        timeout -= Date.now() - startTime
+      }
+    }
+
+    if (!checkResult()) {
+      await waitForResult()
     }
   }
 
   const waitForValueToChange = async (selector, options = {}) => {
-    const initialTimeout = options.timeout
-    const initialValue = actForResult(selector)
-    while (true) {
-      const startTime = Date.now()
-      try {
-        await waitForNextUpdate(options)
-        if (actForResult(selector) !== initialValue) {
-          break
-        }
-      } catch (e) {
-        if (e.timeout) {
-          throw createTimeoutError('waitForValueToChange', initialTimeout)
-        }
-        throw e
+    const initialValue = selector()
+    try {
+      await wait(() => selector() !== initialValue, {
+        suppressErrors: false,
+        ...options
+      })
+    } catch (e) {
+      if (e.timeout) {
+        throw createTimeoutError('waitForValueToChange', options)
       }
-      options.timeout -= Date.now() - startTime
+      throw e
     }
   }
 

test/asyncHook.test.js

@@ -9,8 +9,10 @@ describe('async hook tests', () => {
 
     useEffect(() => {
       const interval = setInterval(() => {
-        setValue(otherValues[index.current])
-        index.current++
+        setValue(otherValues[index.current++])
+        if (index.current === otherValues.length) {
+          clearInterval(interval)
+        }
       }, 50)
       return () => {
         clearInterval(interval)
@@ -77,6 +79,57 @@ describe('async hook tests', () => {
     expect(complete).toBe(true)
   })
 
+  test('should not hang if expectation is already passing', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second'))
+
+    expect(result.current).toBe('first')
+
+    let complete = false
+    await wait(() => {
+      expect(result.current).toBe('first')
+      complete = true
+    })
+    expect(complete).toBe(true)
+  })
+
+  test('should reject if callback throws error', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
+
+    expect(result.current).toBe('first')
+
+    await expect(
+      wait(
+        () => {
+          console.log(result.current)
+          if (result.current === 'second') {
+            throw new Error('Something Unexpected')
+          }
+          return result.current === 'third'
+        },
+        {
+          suppressErrors: false
+        }
+      )
+    ).rejects.toThrow(Error('Something Unexpected'))
+  })
+
+  test('should reject if callback immediately throws error', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
+
+    expect(result.current).toBe('first')
+
+    await expect(
+      wait(
+        () => {
+          throw new Error('Something Unexpected')
+        },
+        {
+          suppressErrors: false
+        }
+      )
+    ).rejects.toThrow(Error('Something Unexpected'))
+  })
+
   test('should wait for truthy value', async () => {
     const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
 
@@ -142,4 +195,24 @@ describe('async hook tests', () => {
       })
     ).rejects.toThrow(Error('Something Unexpected'))
   })
+
+  test('should not reject if selector throws error and suppress errors option is enabled', async () => {
+    const { result, waitForValueToChange } = renderHook(() =>
+      useSequence('first', 'second', 'third')
+    )
+
+    expect(result.current).toBe('first')
+
+    await waitForValueToChange(
+      () => {
+        if (result.current === 'second') {
+          throw new Error('Something Unexpected')
+        }
+        return result.current === 'third'
+      },
+      { suppressErrors: true }
+    )
+
+    expect(result.current).toBe('third')
+  })
 })