Improve error stack traces for async errors

src/__tests__/wait-for.js

@@ -23,7 +23,7 @@ test('can timeout after the given timeout time', async () => {
   expect(result).toBe(error)
 })
 
-test('uses generic error if there was no last error', async () => {
+test('if no error is thrown then throws a timeout error', async () => {
   const result = await waitFor(
     () => {
       // eslint-disable-next-line no-throw-literal
@@ -34,6 +34,58 @@ test('uses generic error if there was no last error', async () => {
   expect(result).toMatchInlineSnapshot(`[Error: Timed out in waitFor.]`)
 })
 
+test('if showOriginalStackTrace on a timeout error then the stack trace does not include this file', async () => {
+  const result = await waitFor(
+    () => {
+      // eslint-disable-next-line no-throw-literal
+      throw undefined
+    },
+    {timeout: 8, interval: 5, showOriginalStackTrace: true},
+  ).catch(e => e)
+  expect(result.stack).not.toMatch(__dirname)
+})
+
+test('uses full stack error trace when showOriginalStackTrace present', async () => {
+  const error = new Error('Throws the full stack trace')
+  // even if the error is a TestingLibraryElementError
+  error.name = 'TestingLibraryElementError'
+  const originalStackTrace = error.stack
+  const result = await waitFor(
+    () => {
+      throw error
+    },
+    {timeout: 8, interval: 5, showOriginalStackTrace: true},
+  ).catch(e => e)
+  expect(result.stack).toBe(originalStackTrace)
+})
+
+test('does not change the stack trace if the thrown error is not a TestingLibraryElementError', async () => {
+  const error = new Error('Throws the full stack trace')
+  const originalStackTrace = error.stack
+  const result = await waitFor(
+    () => {
+      throw error
+    },
+    {timeout: 8, interval: 5},
+  ).catch(e => e)
+  expect(result.stack).toBe(originalStackTrace)
+})
+
+test('provides an improved stack trace if the thrown error is a TestingLibraryElementError', async () => {
+  const error = new Error('Throws the full stack trace')
+  error.name = 'TestingLibraryElementError'
+  const originalStackTrace = error.stack
+  const result = await waitFor(
+    () => {
+      throw error
+    },
+    {timeout: 8, interval: 5},
+  ).catch(e => e)
+  // too hard to test that the stack trace is what we want it to be
+  // so we'll just make sure that it's not the same as the origianl
+  expect(result.stack).not.toBe(originalStackTrace)
+})
+
 test('throws nice error if provided callback is not a function', () => {
   const {queryByTestId} = renderIntoDocument(`
     <div data-testid="div"></div>

src/config.js

@@ -16,6 +16,8 @@ let config = {
   asyncWrapper: cb => cb(),
   // default value for the `hidden` option in `ByRole` queries
   defaultHidden: false,
+  //showOriginalStackTrace flag to show the full error stack traces for async errors
+  showOriginalStackTrace: false,
 
   // called when getBy* queries fail. (message, container) => Error
   getElementError(message, container) {

src/wait-for.js

@@ -8,26 +8,32 @@ import {
 } from './helpers'
 import {getConfig} from './config'
 
+// 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).
+function copyStackTrace(target, source) {
+  target.stack = source.stack.replace(source.message, target.message)
+}
+
 function waitFor(
   callback,
   {
     container = getDocument(),
     timeout = getConfig().asyncUtilTimeout,
+    showOriginalStackTrace = getConfig().showOriginalStackTrace,
+    stackTraceError,
     interval = 50,
     mutationObserverOptions = {
       subtree: true,
       childList: true,
       attributes: true,
       characterData: true,
     },
-  } = {},
+  },
 ) {
   if (typeof callback !== 'function') {
     throw new TypeError('Received `callback` arg must be a function')
   }
 
-  // created here so we get a nice stacktrace
-  const timedOutError = new Error('Timed out in waitFor.')
   if (interval < 1) interval = 1
   return new Promise((resolve, reject) => {
     let lastError
@@ -63,13 +69,33 @@ function waitFor(
     }
 
     function onTimeout() {
-      onDone(lastError || timedOutError, null)
+      let error
+      if (lastError) {
+        error = lastError
+        if (
+          !showOriginalStackTrace &&
+          error.name === 'TestingLibraryElementError'
+        ) {
+          copyStackTrace(error, stackTraceError)
+        }
+      } else {
+        error = new Error('Timed out in waitFor.')
+        if (!showOriginalStackTrace) {
+          copyStackTrace(error, stackTraceError)
+        }
+      }
+      onDone(error, null)
     }
   })
 }
 
-function waitForWrapper(...args) {
-  return getConfig().asyncWrapper(() => waitFor(...args))
+function waitForWrapper(callback, options) {
+  // create the error here so its stack trace is as close to the
+  // calling code as possible
+  const stackTraceError = new Error('STACK_TRACE_MESSAGE')
+  return getConfig().asyncWrapper(() =>
+    waitFor(callback, {stackTraceError, ...options}),
+  )
 }
 
 let hasWarned = false