feat(waitFor): add onTimeout which adds DOM output to timeout errors (#671)

kentcdodds · web-flow · commit 6bc8e2e7e5c6 · 2020-06-24T15:13:41.000-06:00
Closes #559
diff --git a/src/__tests__/base-queries-warn-on-invalid-container.js b/src/__tests__/base-queries-warn-on-invalid-container.js
@@ -112,7 +112,7 @@ describe('asynchronous queries throw on invalid container type', () => {
     ['findAllByTestId', findAllByTestId],
   ])('%s', (_queryName, query) => {
     const queryOptions = {}
-    const waitOptions = {timeout: 1}
+    const waitOptions = {timeout: 1, onTimeout: e => e}
     return expect(
       query(
         'invalid type for container',
diff --git a/src/__tests__/fake-timers.js b/src/__tests__/fake-timers.js
@@ -42,7 +42,7 @@ test('fake timer timeout', async () => {
       () => {
         throw new Error('always throws')
       },
-      {timeout: 10},
+      {timeout: 10, onTimeout: e => e},
     ),
   ).rejects.toMatchInlineSnapshot(`[Error: always throws]`)
 })
@@ -53,7 +53,7 @@ test('times out after 1000ms by default', async () => {
   // there's a bug with this rule here...
   // eslint-disable-next-line jest/valid-expect
   await expect(
-    waitForElementToBeRemoved(() => container),
+    waitForElementToBeRemoved(() => container, {onTimeout: e => e}),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
     `"Timed out in waitForElementToBeRemoved."`,
   )
diff --git a/src/__tests__/wait-for-element-to-be-removed.js b/src/__tests__/wait-for-element-to-be-removed.js
@@ -96,7 +96,7 @@ test('rethrows non-testing-lib errors', () => {
 test('logs timeout error when it times out', async () => {
   const div = document.createElement('div')
   await expect(
-    waitForElementToBeRemoved(() => div, {timeout: 1}),
+    waitForElementToBeRemoved(() => div, {timeout: 1, onTimeout: e => e}),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
     `"Timed out in waitForElementToBeRemoved."`,
   )
diff --git a/src/__tests__/wait-for.js b/src/__tests__/wait-for.js
@@ -35,7 +35,7 @@ test('if no error is thrown then throws a timeout error', async () => {
       // eslint-disable-next-line no-throw-literal
       throw undefined
     },
-    {timeout: 8, interval: 5},
+    {timeout: 8, interval: 5, onTimeout: e => e},
   ).catch(e => e)
   expect(result).toMatchInlineSnapshot(`[Error: Timed out in waitFor.]`)
 })
@@ -101,3 +101,27 @@ test('throws nice error if provided callback is not a function', () => {
     'Received `callback` arg must be a function',
   )
 })
+
+test('timeout logs a pretty DOM', async () => {
+  renderIntoDocument(`<div id="pretty">how pretty</div>`)
+  const error = await waitFor(
+    () => {
+      throw new Error('always throws')
+    },
+    {timeout: 1},
+  ).catch(e => e)
+  expect(error.message).toMatchInlineSnapshot(`
+    "always throws
+
+    <html>
+      <head />
+      <body>
+        <div
+          id="pretty"
+        >
+          how pretty
+        </div>
+      </body>
+    </html>"
+  `)
+})
diff --git a/src/wait-for.js b/src/wait-for.js
@@ -10,6 +10,7 @@ import {
   clearTimeout,
 } from './helpers'
 import {getConfig, runWithExpensiveErrorDiagnosticsDisabled} from './config'
+import {prettyDOM} from './pretty-dom'
 
 // This is so the stack trace the developer sees is one that's
 // closer to their code (because async stack traces are hard to follow).
@@ -25,6 +26,10 @@ function waitFor(
     showOriginalStackTrace = getConfig().showOriginalStackTrace,
     stackTraceError,
     interval = 50,
+    onTimeout = error => {
+      error.message = `${error.message}\n\n${prettyDOM(container)}`
+      return error
+    },
     mutationObserverOptions = {
       subtree: true,
       childList: true,
@@ -41,7 +46,7 @@ function waitFor(
     let lastError, intervalId, observer
     let finished = false
 
-    const overallTimeoutTimer = setTimeout(onTimeout, timeout)
+    const overallTimeoutTimer = setTimeout(handleTimeout, timeout)
 
     const usingFakeTimers = jestFakeTimersAreEnabled()
     if (usingFakeTimers) {
@@ -106,7 +111,7 @@ function waitFor(
       }
     }
 
-    function onTimeout() {
+    function handleTimeout() {
       let error
       if (lastError) {
         error = lastError
@@ -122,7 +127,7 @@ function waitFor(
           copyStackTrace(error, stackTraceError)
         }
       }
-      onDone(error, null)
+      onDone(onTimeout(error), null)
     }
   })
 }
diff --git a/types/wait-for.d.ts b/types/wait-for.d.ts
@@ -2,6 +2,7 @@ export interface waitForOptions {
   container?: HTMLElement
   timeout?: number
   interval?: number
+  onTimeout?: (error: Error) => Error
   mutationObserverOptions?: MutationObserverInit
 }
 

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,7 @@ test('rethrows non-testing-lib errors', () => {`
`96`	`96`	`test('logs timeout error when it times out', async () => {`
`97`	`97`	`const div = document.createElement('div')`
`98`	`98`	`await expect(`
`99`		`- waitForElementToBeRemoved(() => div, {timeout: 1}),`
	`99`	`+ waitForElementToBeRemoved(() => div, {timeout: 1, onTimeout: e => e}),`
`100`	`100`	`).rejects.toThrowErrorMatchingInlineSnapshot(`
`101`	`101`	`"Timed out in waitForElementToBeRemoved."`,
`102`	`102`	`)`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@ export interface waitForOptions {`
`2`	`2`	`container?: HTMLElement`
`3`	`3`	`timeout?: number`
`4`	`4`	`interval?: number`
	`5`	`+ onTimeout?: (error: Error) => Error`
`5`	`6`	`mutationObserverOptions?: MutationObserverInit`
`6`	`7`	`}`
`7`	`8`