fix: try to catch unhandled error outside of a test (#7968)

sheremet-va · web-flow · commit 464218f42cb4 · 2025-05-13T19:28:56.000+02:00
diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ Next generation testing framework powered by Vite.
 - Out-of-box TypeScript / JSX support
 - Filtering, timeouts, concurrent for suite and tests
 - Sharding support
+- Reporting Uncaught Errors
 - Run your tests in the browser natively (experimental)
 
 > Vitest requires Vite >=v5.0.0 and Node >=v18.0.0
diff --git a/docs/.vitepress/components/FeaturesList.vue b/docs/.vitepress/components/FeaturesList.vue
@@ -26,7 +26,8 @@
     <ListItem>Code coverage via <a target="_blank" href="https://v8.dev/blog/javascript-code-coverage" rel="noopener noreferrer">v8</a> or <a target="_blank" href="https://istanbul.js.org/" rel="noopener noreferrer">istanbul</a></ListItem>
     <ListItem>Rust-like <a href="/guide/in-source">in-source testing</a></ListItem>
     <ListItem>Type Testing via <a target="_blank" href="https://github.com/mmkal/expect-type" rel="noopener noreferrer">expect-type</a></ListItem>
-    <ListItem>Sharding support</ListItem>
+    <ListItem>Sharding Support</ListItem>
+    <ListItem>Reporting Uncaught Errors</ListItem>
   </ul>
 </template>
 
diff --git a/docs/guide/features.md b/docs/guide/features.md
@@ -259,3 +259,60 @@ export default defineConfig(({ mode }) => ({
   },
 }))
 ```
+
+## Unhandled Errors
+
+By default, Vitest catches and reports all [unhandled rejections](https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event), [uncaught exceptions](https://nodejs.org/api/process.html#event-uncaughtexception) (in Node.js) and [error](https://developer.mozilla.org/en-US/docs/Web/API/Window/error_event) events (in the [browser](/guide/browser/)).
+
+You can disable this behaviour by catching them manually. Vitest assumes the callback is handled by you and won't report the error.
+
+::: code-group
+```ts [setup.node.js]
+// in Node.js
+process.on('unhandledRejection', () => {
+  // your own handler
+})
+
+process.on('uncaughtException', () => {
+  // your own handler
+})
+```
+```ts [setup.browser.js]
+// in the browser
+window.addEventListener('error', () => {
+  // your own handler
+})
+
+window.addEventListener('unhandledrejection', () => {
+  // your own handler
+})
+```
+:::
+
+Alternatively, you can also ignore reported errors with a [`dangerouslyIgnoreUnhandledErrors`](/config/#dangerouslyignoreunhandlederrors) option. Vitest will still report them, but they won't affect the test result (exit code won't be changed).
+
+If you need to test that error was not caught, you can create a test that looks like this:
+
+```ts
+test('my function throws uncaught error', async ({ onTestFinished }) => {
+  onTestFinished(() => {
+    // if the event was never called during the test,
+    // make sure it's removed before the next test starts
+    process.removeAllListeners('unhandledrejection')
+  })
+
+  return new Promise((resolve, reject) => {
+    process.once('unhandledrejection', (error) => {
+      try {
+        expect(error.message).toBe('my error')
+        resolve()
+      }
+      catch (error) {
+        reject(error)
+      }
+    })
+
+    callMyFunctionThatRejectsError()
+  })
+})
+```
diff --git a/packages/vitest/src/runtime/execute.ts b/packages/vitest/src/runtime/execute.ts
@@ -58,14 +58,11 @@ function listenForErrors(state: () => WorkerGlobalState) {
   function catchError(err: unknown, type: string, event: 'uncaughtException' | 'unhandledRejection') {
     const worker = state()
 
-    // if error happens during a test
-    if (worker.current?.type === 'test') {
-      const listeners = process.listeners(event as 'uncaughtException')
-      // if there is another listener, assume that it's handled by user code
-      // one is Vitest's own listener
-      if (listeners.length > 1) {
-        return
-      }
+    const listeners = process.listeners(event as 'uncaughtException')
+    // if there is another listener, assume that it's handled by user code
+    // one is Vitest's own listener
+    if (listeners.length > 1) {
+      return
     }
 
     const error = processError(err)
diff --git a/test/cli/fixtures/fails/unhandled-suite.test.ts b/test/cli/fixtures/fails/unhandled-suite.test.ts
@@ -0,0 +1,8 @@
+import { expect, it } from 'vitest';
+
+it('foo', () => {
+  expect(1).toBe(1)
+  new Promise((resolve, reject) => {
+    reject('promise error');
+  });
+});
diff --git a/test/cli/test/__snapshots__/fails.test.ts.snap b/test/cli/test/__snapshots__/fails.test.ts.snap
@@ -127,3 +127,5 @@ exports[`should fail unhandled.test.ts 1`] = `
 "Error: some error
 Error: Uncaught [Error: some error]"
 `;
+
+exports[`should fail unhandled-suite.test.ts 1`] = `"Unknown Error: promise error"`;
diff --git a/test/core/test/unhandled.test.ts b/test/core/test/unhandled.test.ts
@@ -0,0 +1,12 @@
+import { test } from 'vitest'
+
+process.on('unhandledRejection', () => {
+  // ignore errors
+})
+
+test('throws unhandled but not reported', () => {
+  // eslint-disable-next-line no-new
+  new Promise((resolve, reject) => {
+    reject(new Error('promise error'))
+  })
+})
