feat(browser): add trackUnhandledErrors option (#8386)

sheremet-va · web-flow · commit c0ec08a90533 · 2025-08-06T19:13:32.000+02:00
diff --git a/docs/guide/browser/config.md b/docs/guide/browser/config.md
@@ -326,6 +326,17 @@ The timeout in milliseconds. If connection to the browser takes longer, the test
 This is the time it should take for the browser to establish the WebSocket connection with the Vitest server. In normal circumstances, this timeout should never be reached.
 :::
 
+## browser.trackUnhandledErrors
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Enables tracking uncaught errors and exceptions so they can be reported by Vitest.
+
+If you need to hide certain errors, it is recommended to use [`onUnhandledError`](/config/#onunhandlederror) option instead.
+
+Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on.
+
 ## browser.expect
 
 - **Type:** `ExpectOptions`
diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -376,6 +376,13 @@ Should browser test files run in parallel. Use `--browser.fileParallelism=false`
 
 If connection to the browser takes longer, the test suite will fail (default: `60_000`)
 
+### browser.trackUnhandledErrors
+
+- **CLI:** `--browser.trackUnhandledErrors`
+- **Config:** [browser.trackUnhandledErrors](/guide/browser/config#browser-trackunhandlederrors)
+
+Control if Vitest catches uncaught exceptions so they can be reported (default: `true`)
+
 ### pool
 
 - **CLI:** `--pool <pool>`
diff --git a/packages/browser/src/client/public/error-catcher.js b/packages/browser/src/client/public/error-catcher.js
@@ -55,10 +55,14 @@ function catchWindowErrors(errorEvent, prop, cb) {
 }
 
 function registerUnexpectedErrors() {
-  catchWindowErrors('error', 'error', event =>
+  const offError = catchWindowErrors('error', 'error', event =>
     reportUnexpectedError('Error', event.error))
-  catchWindowErrors('unhandledrejection', 'reason', event =>
+  const offRejection = catchWindowErrors('unhandledrejection', 'reason', event =>
     reportUnexpectedError('Unhandled Rejection', event.reason))
+  return () => {
+    offError()
+    offRejection()
+  }
 }
 
 async function reportUnexpectedError(
@@ -71,4 +75,4 @@ async function reportUnexpectedError(
   }).catch(console.error)
 }
 
-registerUnexpectedErrors()
+globalThis.__vitest_browser_runner__.disposeExceptionTracker = registerUnexpectedErrors()
diff --git a/packages/browser/src/client/public/esm-client-injector.js b/packages/browser/src/client/public/esm-client-injector.js
@@ -19,6 +19,7 @@
   window.__vitest_browser_runner__ = {
     wrapModule,
     wrapDynamicImport: wrapModule,
+    disposeExceptionTracker: () => {},
     moduleCache,
     cleanups: [],
     config: { __VITEST_CONFIG__ },
diff --git a/packages/browser/src/client/tester/tester.ts b/packages/browser/src/client/tester/tester.ts
@@ -217,6 +217,10 @@ async function prepare(options: PrepareOptions) {
       })
     })(),
   ])
+
+  if (!config.browser.trackUnhandledErrors) {
+    getBrowserState().disposeExceptionTracker()
+  }
 }
 
 async function cleanup() {
diff --git a/packages/browser/src/client/utils.ts b/packages/browser/src/client/utils.ts
@@ -75,6 +75,7 @@ export interface BrowserRunnerState {
   }
   providedContext: string
   type: 'tester' | 'orchestrator'
+  disposeExceptionTracker: () => void
   wrapModule: <T>(module: () => T) => T
   iframeId?: string
   sessionId: string
diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -411,6 +411,9 @@ export const cliOptionsConfig: VitestCLIOptions = {
         description: 'If connection to the browser takes longer, the test suite will fail (default: `60_000`)',
         argument: '<timeout>',
       },
+      trackUnhandledErrors: {
+        description: 'Control if Vitest catches uncaught exceptions so they can be reported (default: `true`)',
+      },
       orchestratorScripts: null,
       testerScripts: null,
       commands: null,
diff --git a/packages/vitest/src/node/config/serializeConfig.ts b/packages/vitest/src/node/config/serializeConfig.ts
@@ -156,6 +156,7 @@ export function serializeConfig(
               actionTimeout: (browser.providerOptions as any)?.context?.actionTimeout,
             }
           : {},
+        trackUnhandledErrors: browser.trackUnhandledErrors ?? true,
       }
     })(config.browser),
     standalone: config.standalone,
diff --git a/packages/vitest/src/node/types/browser.ts b/packages/vitest/src/node/types/browser.ts
@@ -248,6 +248,16 @@ export interface BrowserConfigOptions {
       }
     }[keyof ToMatchScreenshotComparators] & ToMatchScreenshotOptions
   }
+
+  /**
+   * Enables tracking uncaught errors and exceptions so they can be reported by Vitest.
+   *
+   * If you need to hide certain errors, it is recommended to use [`onUnhandledError`](https://vitest.dev/config/#onunhandlederror) option instead.
+   *
+   * Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on.
+   * @default true
+   */
+  trackUnhandledErrors?: boolean
 }
 
 export interface BrowserCommandContext {
diff --git a/packages/vitest/src/runtime/config.ts b/packages/vitest/src/runtime/config.ts
@@ -122,6 +122,7 @@ export interface SerializedConfig {
       // for playwright
       actionTimeout?: number
     }
+    trackUnhandledErrors: boolean
   }
   standalone: boolean
   logHeapUsage: boolean | undefined
diff --git a/test/browser/specs/unhandled.test.ts b/test/browser/specs/unhandled.test.ts
@@ -27,3 +27,13 @@ test('ignores unhandled errors', async () => {
 
   expect(stderr).toBe('')
 })
+
+test('disables tracking', async () => {
+  const { stderr } = await runBrowserTests({
+    root: './fixtures/unhandled',
+    browser: {
+      trackUnhandledErrors: false,
+    },
+  })
+  expect(stderr).toBe('')
+})

Original file line number	Diff line number	Diff line change
`@@ -55,10 +55,14 @@ function catchWindowErrors(errorEvent, prop, cb) {`
`55`	`55`	`}`
`56`	`56`
`57`	`57`	`function registerUnexpectedErrors() {`
`58`		`- catchWindowErrors('error', 'error', event =>`
	`58`	`+ const offError = catchWindowErrors('error', 'error', event =>`
`59`	`59`	`reportUnexpectedError('Error', event.error))`
`60`		`- catchWindowErrors('unhandledrejection', 'reason', event =>`
	`60`	`+ const offRejection = catchWindowErrors('unhandledrejection', 'reason', event =>`
`61`	`61`	`reportUnexpectedError('Unhandled Rejection', event.reason))`
	`62`	`+ return () => {`
	`63`	`+ offError()`
	`64`	`+ offRejection()`
	`65`	`+ }`
`62`	`66`	`}`
`63`	`67`
`64`	`68`	`async function reportUnexpectedError(`
`@@ -71,4 +75,4 @@ async function reportUnexpectedError(`
`71`	`75`	`}).catch(console.error)`
`72`	`76`	`}`
`73`	`77`
`74`		`-registerUnexpectedErrors()`
	`78`	`+globalThis.__vitest_browser_runner__.disposeExceptionTracker = registerUnexpectedErrors()`
Original file line number	Diff line number	Diff line change
`@@ -75,6 +75,7 @@ export interface BrowserRunnerState {`
`75`	`75`	`}`
`76`	`76`	`providedContext: string`
`77`	`77`	`type: 'tester' \| 'orchestrator'`
	`78`	`+ disposeExceptionTracker: () => void`
`78`	`79`	`wrapModule: <T>(module: () => T) => T`
`79`	`80`	`iframeId?: string`
`80`	`81`	`sessionId: string`
Original file line number	Diff line number	Diff line change
`@@ -156,6 +156,7 @@ export function serializeConfig(`
`156`	`156`	`actionTimeout: (browser.providerOptions as any)?.context?.actionTimeout,`
`157`	`157`	`}`
`158`	`158`	`: {},`
	`159`	`+ trackUnhandledErrors: browser.trackUnhandledErrors ?? true,`
`159`	`160`	`}`
`160`	`161`	`})(config.browser),`
`161`	`162`	`standalone: config.standalone,`
Original file line number	Diff line number	Diff line change
`@@ -248,6 +248,16 @@ export interface BrowserConfigOptions {`
`248`	`248`	`}`
`249`	`249`	`}[keyof ToMatchScreenshotComparators] & ToMatchScreenshotOptions`
`250`	`250`	`}`
	`251`	`+`
	`252`	`+ /**`
	`253`	`+ * Enables tracking uncaught errors and exceptions so they can be reported by Vitest.`
	`254`	`+ *`
	`255`	+ * If you need to hide certain errors, it is recommended to use [`onUnhandledError`](https://vitest.dev/config/#onunhandlederror) option instead.
	`256`	`+ *`
	`257`	`+ * Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on.`
	`258`	`+ * @default true`
	`259`	`+ */`
	`260`	`+ trackUnhandledErrors?: boolean`
`251`	`261`	`}`
`252`	`262`
`253`	`263`	`export interface BrowserCommandContext {`
Original file line number	Diff line number	Diff line change
`@@ -122,6 +122,7 @@ export interface SerializedConfig {`
`122`	`122`	`// for playwright`
`123`	`123`	`actionTimeout?: number`
`124`	`124`	`}`
	`125`	`+ trackUnhandledErrors: boolean`
`125`	`126`	`}`
`126`	`127`	`standalone: boolean`
`127`	`128`	`logHeapUsage: boolean \| undefined`