Added waitForValueToChange async util with documentation

Author: mpeyper

docs/api-reference.md

@@ -110,10 +110,10 @@ function wait(callback: function(): boolean|void, options?: WaitOptions): Promis
 ```
 
 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.
+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.
 
-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.
 
 See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
 `options` parameter.
@@ -130,6 +130,21 @@ the result of an asynchronous update.
 See the [`wait` Options](/reference/api#wait-options) section for more details on the optional
 `options` parameter.
 
+### `waitForValueToChange`
+
+```js
+function waitForValueToChange(selector: function(): any, options?: WaitOptions): Promise<void>
+```
+
+Returns a `Promise` that resolves if the value returned from the provided selector changes. It
+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.
+
+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:

src/asyncUtils.js

@@ -59,9 +59,30 @@ function asyncUtils(addResolver) {
     }
   }
 
+  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
+      }
+      options.timeout -= Date.now() - startTime
+    }
+  }
+
   return {
     wait,
-    waitForNextUpdate
+    waitForNextUpdate,
+    waitForValueToChange
   }
 }
 

test/asyncHook.test.js

@@ -101,4 +101,45 @@ describe('async hook tests', () => {
       )
     ).rejects.toThrow(Error('Timed out in wait after 75ms.'))
   })
+
+  test('should wait for value to change', async () => {
+    const { result, waitForValueToChange } = renderHook(() =>
+      useSequence('first', 'second', 'third')
+    )
+
+    expect(result.current).toBe('first')
+
+    await waitForValueToChange(() => result.current === 'third')
+
+    expect(result.current).toBe('third')
+  })
+
+  test('should reject if timeout exceeded when waiting for value to change', async () => {
+    const { result, waitForValueToChange } = renderHook(() =>
+      useSequence('first', 'second', 'third')
+    )
+
+    expect(result.current).toBe('first')
+
+    await expect(
+      waitForValueToChange(() => result.current === 'third', {
+        timeout: 75
+      })
+    ).rejects.toThrow(Error('Timed out in waitForValueToChange after 75ms.'))
+  })
+
+  test('should reject if selector throws error', async () => {
+    const { result, waitForValueToChange } = renderHook(() => useSequence('first', 'second'))
+
+    expect(result.current).toBe('first')
+
+    await expect(
+      waitForValueToChange(() => {
+        if (result.current === 'second') {
+          throw new Error('Something Unexpected')
+        }
+        return result.current
+      })
+    ).rejects.toThrow(Error('Something Unexpected'))
+  })
 })