feat: adds onTimeout option to waitFor (#885)

Author: jmbeach

src/__tests__/waitFor.test.js

@@ -115,6 +115,32 @@ test.each([TimerMode.Legacy, TimerMode.Modern])(
   }
 );
 
+test.each([TimerMode.Legacy, TimerMode.Modern])(
+  'waits for assertion until timeout is met with %s fake timers',
+  async (fakeTimerType) => {
+    jest.useFakeTimers(fakeTimerType);
+
+    const mockErrorFn = jest.fn(() => {
+      throw Error('test');
+    });
+
+    const mockHandleFn = jest.fn((e) => e);
+
+    try {
+      await waitFor(() => mockErrorFn(), {
+        timeout: 400,
+        interval: 200,
+        onTimeout: mockHandleFn,
+      });
+    } catch (error) {
+      // suppress
+    }
+
+    expect(mockErrorFn).toHaveBeenCalledTimes(3);
+    expect(mockHandleFn).toHaveBeenCalledTimes(1);
+  }
+);
+
 test.each([TimerMode.Legacy, TimerMode.Legacy])(
   'awaiting something that succeeds before timeout works with %s fake timers',
   async (fakeTimerType) => {

src/waitFor.js

@@ -29,6 +29,7 @@ export type WaitForOptions = {
   timeout?: number,
   interval?: number,
   stackTraceError?: ErrorWithStack,
+  onTimeout?: (error: Error) => Error,
 };
 
 function waitForInternal<T>(
@@ -37,6 +38,7 @@ function waitForInternal<T>(
     timeout = DEFAULT_TIMEOUT,
     interval = DEFAULT_INTERVAL,
     stackTraceError,
+    onTimeout,
   }: WaitForOptions
 ): Promise<T> {
   if (typeof expectation !== 'function') {
@@ -179,6 +181,9 @@ function waitForInternal<T>(
           copyStackTrace(error, stackTraceError);
         }
       }
+      if (typeof onTimeout === 'function') {
+        onTimeout(error);
+      }
       onDone(error, null);
     }
   });

typings/index.d.ts

@@ -388,6 +388,7 @@ type TextMatchOptions = {
 type WaitForOptions = {
   timeout?: number;
   interval?: number;
+  onTimeout?: (error: Error) => Error;
 };
 
 export type WaitForFunction = <T = any>(