feat: add onUnhandledError callback (#8162)

Author: sheremet-va

docs/config/index.md

@@ -2191,6 +2191,30 @@ export default defineConfig({
 })
 ```
 
+### onUnhandledError<NonProjectOption /> {#onunhandlederror}
+
+- **Type:** `(error: (TestError | Error) & { type: string }) => boolean | void`
+
+A custom handler to filter out unhandled errors that should not be reported. If an error is filtered out, it will no longer affect the test results.
+
+If you want unhandled errors to be reported without impacting the test outcome, consider using the [`dangerouslyIgnoreUnhandledErrors`](#dangerouslyIgnoreUnhandledErrors) option
+
+```ts
+import type { ParsedStack } from 'vitest'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    onUnhandledError(error): boolean | void {
+      // Ignore all errors with the name "MySpecialError".
+      if (error.name === 'MySpecialError') {
+        return false
+      }
+    },
+  },
+})
+```
+
 ### diff
 
 - **Type:** `string`

packages/vitest/src/node/core.ts

@@ -221,7 +221,9 @@ export class Vitest {
     const resolved = resolveConfig(this, options, server.config)
 
     this._config = resolved
-    this._state = new StateManager()
+    this._state = new StateManager({
+      onUnhandledError: resolved.onUnhandledError,
+    })
     this._cache = new VitestCache(this.version)
     this._snapshot = new SnapshotManager({ ...resolved.snapshotOptions })
     this._testRun = new TestRun(this)

packages/vitest/src/node/state.ts

@@ -2,6 +2,7 @@ import type { File, Task, TaskResultPack } from '@vitest/runner'
 import type { UserConsoleLog } from '../types/general'
 import type { TestProject } from './project'
 import type { MergedBlobs } from './reporters/blob'
+import type { OnUnhandledErrorCallback } from './types/config'
 import { createFileTask } from '@vitest/runner/utils'
 import { TestCase, TestModule, TestSuite } from './reporters/reported-tasks'
 
@@ -23,31 +24,43 @@ export class StateManager {
   reportedTasksMap: WeakMap<Task, TestModule | TestCase | TestSuite> = new WeakMap()
   blobs?: MergedBlobs
 
-  catchError(err: unknown, type: string): void {
-    if (isAggregateError(err)) {
-      return err.errors.forEach(error => this.catchError(error, type))
+  onUnhandledError?: OnUnhandledErrorCallback
+
+  constructor(
+    options: {
+      onUnhandledError?: OnUnhandledErrorCallback
+    },
+  ) {
+    this.onUnhandledError = options.onUnhandledError
+  }
+
+  catchError(error: unknown, type: string): void {
+    if (isAggregateError(error)) {
+      return error.errors.forEach(error => this.catchError(error, type))
     }
 
-    if (err === Object(err)) {
-      (err as Record<string, unknown>).type = type
+    if (typeof error === 'object' && error !== null) {
+      (error as Record<string, unknown>).type = type
     }
     else {
-      err = { type, message: err }
+      error = { type, message: error }
     }
 
-    const _err = err as Record<string, any>
-    if (_err && typeof _err === 'object' && _err.code === 'VITEST_PENDING') {
-      const task = this.idMap.get(_err.taskId)
+    const _error = error as Record<string, any>
+    if (_error && typeof _error === 'object' && _error.code === 'VITEST_PENDING') {
+      const task = this.idMap.get(_error.taskId)
       if (task) {
         task.mode = 'skip'
         task.result ??= { state: 'skip' }
         task.result.state = 'skip'
-        task.result.note = _err.note
+        task.result.note = _error.note
       }
       return
     }
 
-    this.errorsSet.add(err)
+    if (!this.onUnhandledError || this.onUnhandledError(error as any) !== false) {
+      this.errorsSet.add(error)
+    }
   }
 
   clearErrors(): void {

packages/vitest/src/node/types/config.ts

@@ -638,6 +638,11 @@ export interface InlineConfig {
    */
   onStackTrace?: (error: TestError, frame: ParsedStack) => boolean | void
 
+  /**
+   * A callback that can return `false` to ignore an unhandled error
+   */
+  onUnhandledError?: OnUnhandledErrorCallback
+
   /**
    * Indicates if CSS files should be processed.
    *
@@ -978,6 +983,8 @@ export interface UserConfig extends InlineConfig {
   mergeReports?: string
 }
 
+export type OnUnhandledErrorCallback = (error: (TestError | Error) & { type: string }) => boolean | void
+
 export interface ResolvedConfig
   extends Omit<
     Required<UserConfig>,

test/browser/specs/unhandled.test.ts

@@ -14,3 +14,16 @@ test('prints correct unhandled error stack', async () => {
     expect(stderr).toContain('throw-unhandled-error.test.ts:9:20')
   }
 })
+
+test('ignores unhandled errors', async () => {
+  const { stderr } = await runBrowserTests({
+    root: './fixtures/unhandled',
+    onUnhandledError(error) {
+      if (error.message.includes('custom_unhandled_error')) {
+        return false
+      }
+    },
+  })
+
+  expect(stderr).toBe('')
+})

test/browser/specs/utils.ts

@@ -1,13 +1,13 @@
 import type { UserConfig as ViteUserConfig } from 'vite'
-import type { UserConfig } from 'vitest/node'
+import type { TestUserConfig } from 'vitest/node'
 import type { VitestRunnerCLIOptions } from '../../test-utils'
 import { runVitest } from '../../test-utils'
 import { browser } from '../settings'
 
 export { browser, instances, provider } from '../settings'
 
 export async function runBrowserTests(
-  config?: Omit<UserConfig, 'browser'> & { browser?: Partial<UserConfig['browser']> },
+  config?: Omit<TestUserConfig, 'browser'> & { browser?: Partial<TestUserConfig['browser']> },
   include?: string[],
   viteOverrides?: Partial<ViteUserConfig>,
   runnerOptions?: VitestRunnerCLIOptions,
@@ -19,6 +19,6 @@ export async function runBrowserTests(
     browser: {
       headless: browser !== 'safari',
       ...config?.browser,
-    } as UserConfig['browser'],
+    } as TestUserConfig['browser'],
   }, include, 'test', viteOverrides, runnerOptions)
 }

test/cli/test/unhandled-ignore.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from 'vitest'
+import { runVitest } from '../../test-utils'
+
+test('run mode does not get stuck when TTY', async () => {
+  const { vitest } = await runVitest({
+    root: './fixtures/fails',
+    include: ['unhandled.test.ts'],
+    onUnhandledError(err) {
+      if (err.message === 'some error') {
+        return false
+      }
+    },
+    // jsdom also prints a warning, but we don't care for our use case
+    onConsoleLog() {
+      return false
+    },
+  })
+
+  // Regression #3642
+  expect(vitest.stderr).toBe('')
+})