Added wait async util with documentation

Author: mpeyper

docs/api-reference.md

@@ -103,23 +103,37 @@ This is the same [`act` function](https://reactjs.org/docs/test-utils.html#act)
 
 ## Async Utilities
 
+### `wait`
+
+```js
+function wait(callback: function(): boolean|void, options?: WaitOptions): Promise<void>
+```
+
+Returns a `Promise` that resolves if the provided callback executes without exception and returns a
+truthy or `undefined` value. The callback is tested after each render of the hook.
+
+It is safe to use the [`result` of `renderHook`](/reference/api#result) in the callback to perform
+assertion or to test values.
+
+See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
+`options` parameter.
+
 ### `waitForNextUpdate`
 
 ```js
 function waitForNextUpdate(options?: WaitOptions): Promise<void>
 ```
 
-`waitForNextUpdate` 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 the next time the hook renders, commonly when state is updated as
+the result of an asynchronous update.
 
-An options object is accepted as the first parameter to modify it's execution. See the
-[`wait` Options](/reference/api#wait-options) section for more details.
+See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
+`options` parameter.
 
 ### `wait` Options
 
 The async utilities accepts the following options:
 
 #### `timeout`
 
-The amount of time in milliseconds (ms) to wait. By default, the `wait` utilities will wait
-indefinitely.
+The maximum amount of time in milliseconds (ms) to wait. By default, no timeout is applied.

src/asyncUtils.js

@@ -1,5 +1,13 @@
 import { act } from 'react-test-renderer'
 
+function actForResult(callback) {
+  let value
+  act(() => {
+    value = callback()
+  })
+  return value
+}
+
 function createTimeoutError(utilName, timeout) {
   const timeoutError = new Error(`Timed out in ${utilName} after ${timeout}ms.`)
   timeoutError.timeout = true
@@ -32,7 +40,27 @@ function asyncUtils(addResolver) {
     return await nextUpdatePromise
   }
 
+  const wait = async (callback, options = {}) => {
+    const initialTimeout = options.timeout
+    while (true) {
+      const startTime = Date.now()
+      try {
+        await waitForNextUpdate(options)
+        const callbackResult = actForResult(callback)
+        if (callbackResult || callbackResult === undefined) {
+          break
+        }
+      } catch (e) {
+        if (e.timeout) {
+          throw createTimeoutError('wait', initialTimeout)
+        }
+      }
+      options.timeout -= Date.now() - startTime
+    }
+  }
+
   return {
+    wait,
     waitForNextUpdate
   }
 }

test/asyncHook.test.js

@@ -63,4 +63,42 @@ describe('async hook tests', () => {
       Error('Timed out in waitForNextUpdate after 10ms.')
     )
   })
+
+  test('should wait for expectation to pass', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
+
+    expect(result.current).toBe('first')
+
+    let complete = false
+    await wait(() => {
+      expect(result.current).toBe('third')
+      complete = true
+    })
+    expect(complete).toBe(true)
+  })
+
+  test('should wait for truthy value', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
+
+    expect(result.current).toBe('first')
+
+    await wait(() => result.current === 'third')
+
+    expect(result.current).toBe('third')
+  })
+
+  test('should reject if timeout exceeded when waiting for expectation to pass', async () => {
+    const { result, wait } = renderHook(() => useSequence('first', 'second', 'third'))
+
+    expect(result.current).toBe('first')
+
+    await expect(
+      wait(
+        () => {
+          expect(result.current).toBe('third')
+        },
+        { timeout: 75 }
+      )
+    ).rejects.toThrow(Error('Timed out in wait after 75ms.'))
+  })
 })