feat: add --detect-async-leaks (#9528)

AriPerkkio · web-flow · commit c594d4af306a · 2026-02-11T15:13:40.000+02:00
diff --git a/docs/config/detectasyncleaks.md b/docs/config/detectasyncleaks.md
@@ -0,0 +1,44 @@
+---
+title: detectAsyncLeaks | Config
+outline: deep
+---
+
+# detectAsyncLeaks
+
+- **Type:** `boolean`
+- **CLI:** `--detectAsyncLeaks`, `--detect-async-leaks`
+- **Default:** `false`
+
+::: warning
+Enabling this option will make your tests run much slower. Use only when debugging or developing tests.
+:::
+
+Detect asynchronous resources leaking from the test file.
+Uses [`node:async_hooks`](https://nodejs.org/api/async_hooks.html) to track creation of async resources. If a resource is not cleaned up, it will be logged after tests have finished.
+
+For example if your code has `setTimeout` calls that execute the callback after tests have finished, you will see following error:
+
+```sh
+⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯ Async Leaks 1 ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
+
+Timeout leaking in test/checkout-screen.test.tsx
+ 26|
+ 27|   useEffect(() => {
+ 28|     setTimeout(() => setWindowWidth(window.innerWidth), 150)
+   |     ^
+ 29|   })
+ 30|
+```
+
+To fix this, you'll need to make sure your code cleans the timeout properly:
+
+```js
+useEffect(() => {
+  setTimeout(() => setWindowWidth(window.innerWidth), 150) // [!code --]
+  const timeout = setTimeout(() => setWindowWidth(window.innerWidth), 150) // [!code ++]
+
+  return function cleanup() { // [!code ++]
+    clearTimeout(timeout) // [!code ++]
+  } // [!code ++]
+})
+```
diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -464,6 +464,13 @@ Pass when no tests are found
 
 Show the size of heap for each test when running in node
 
+### detectAsyncLeaks
+
+- **CLI:** `--detectAsyncLeaks`
+- **Config:** [detectAsyncLeaks](/config/detectasyncleaks)
+
+Detect asynchronous resources leaking from the test file (default: `false`)
+
 ### allowOnly
 
 - **CLI:** `--allowOnly`
diff --git a/packages/vitest/src/defaults.ts b/packages/vitest/src/defaults.ts
@@ -89,6 +89,7 @@ export const configDefaults: Readonly<{
   }
   slowTestThreshold: number
   disableConsoleIntercept: boolean
+  detectAsyncLeaks: boolean
 }> = Object.freeze({
   allowOnly: !isCI,
   isolate: true,
@@ -126,4 +127,5 @@ export const configDefaults: Readonly<{
   },
   slowTestThreshold: 300,
   disableConsoleIntercept: false,
+  detectAsyncLeaks: false,
 })
diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -441,6 +441,9 @@ export const cliOptionsConfig: VitestCLIOptions = {
   logHeapUsage: {
     description: 'Show the size of heap for each test when running in node',
   },
+  detectAsyncLeaks: {
+    description: 'Detect asynchronous resources leaking from the test file (default: `false`)',
+  },
   allowOnly: {
     description:
       'Allow tests and suites that are marked as only (default: `!process.env.CI`)',
diff --git a/packages/vitest/src/node/config/resolveConfig.ts b/packages/vitest/src/node/config/resolveConfig.ts
@@ -354,6 +354,10 @@ export function resolveConfig(
     throw new Error(`"Istanbul" coverage provider is not compatible with "experimental.viteModuleRunner: false". Please, enable "viteModuleRunner" or switch to "v8" coverage provider.`)
   }
 
+  if (browser.enabled && resolved.detectAsyncLeaks) {
+    logger.console.warn(c.yellow('The option "detectAsyncLeaks" is not supported in browser mode and will be ignored.'))
+  }
+
   const containsChromium = hasBrowserChromium(vitest, resolved)
   const hasOnlyChromium = hasOnlyBrowserChromium(vitest, resolved)
 
diff --git a/packages/vitest/src/node/config/serializeConfig.ts b/packages/vitest/src/node/config/serializeConfig.ts
@@ -96,6 +96,7 @@ export function serializeConfig(project: TestProject): SerializedConfig {
     inspect: globalConfig.inspect,
     inspectBrk: globalConfig.inspectBrk,
     inspector: globalConfig.inspector,
+    detectAsyncLeaks: globalConfig.detectAsyncLeaks,
     watch: config.watch,
     includeTaskLocation:
       config.includeTaskLocation
diff --git a/packages/vitest/src/node/pools/rpc.ts b/packages/vitest/src/node/pools/rpc.ts
@@ -143,6 +143,9 @@ export function createMethodsRPC(project: TestProject, methodsOptions: MethodsOp
     onUnhandledError(err, type) {
       vitest.state.catchError(err, type)
     },
+    onAsyncLeaks(leaks) {
+      vitest.state.catchLeaks(leaks)
+    },
     onCancel(reason) {
       vitest.cancelCurrentRun(reason)
     },
diff --git a/packages/vitest/src/node/printError.ts b/packages/vitest/src/node/printError.ts
@@ -389,14 +389,14 @@ function printErrorMessage(error: TestError, logger: ErrorLogger) {
   }
 }
 
-function printStack(
+export function printStack(
   logger: ErrorLogger,
   project: TestProject,
   stack: ParsedStack[],
   highlight: ParsedStack | undefined,
   errorProperties: Record<string, unknown>,
   onStack?: (stack: ParsedStack) => void,
-) {
+): void {
   for (const frame of stack) {
     const color = frame === highlight ? c.cyan : c.gray
     const path = relative(project.config.root, frame.file)
diff --git a/packages/vitest/src/node/projects/resolveProjects.ts b/packages/vitest/src/node/projects/resolveProjects.ts
@@ -41,6 +41,7 @@ export async function resolveProjects(
   // not all options are allowed to be overridden
   const overridesOptions = [
     'logHeapUsage',
+    'detectAsyncLeaks',
     'allowOnly',
     'sequence',
     'testTimeout',
diff --git a/packages/vitest/src/node/reporters/base.ts b/packages/vitest/src/node/reporters/base.ts
@@ -5,6 +5,7 @@ import type { Vitest } from '../core'
 import type { TestSpecification } from '../test-specification'
 import type { Reporter, TestRunEndReason } from '../types/reporter'
 import type { TestCase, TestCollection, TestModule, TestModuleState, TestResult, TestSuite, TestSuiteState } from './reported-tasks'
+import { readFileSync } from 'node:fs'
 import { performance } from 'node:perf_hooks'
 import { getSuites, getTestName, getTests, hasFailed } from '@vitest/runner/utils'
 import { toArray } from '@vitest/utils/helpers'
@@ -14,6 +15,7 @@ import c from 'tinyrainbow'
 import { groupBy } from '../../utils/base'
 import { isTTY } from '../../utils/env'
 import { hasFailedSnapshot } from '../../utils/tasks'
+import { generateCodeFrame, printStack } from '../printError'
 import { F_CHECK, F_DOWN_RIGHT, F_POINTER } from './renderers/figures'
 import {
   countTestErrors,
@@ -519,6 +521,7 @@ export abstract class BaseReporter implements Reporter {
 
   reportSummary(files: File[], errors: unknown[]): void {
     this.printErrorsSummary(files, errors)
+    this.printLeaksSummary()
 
     if (this.ctx.config.mode === 'benchmark') {
       this.reportBenchmarkSummary(files)
@@ -572,6 +575,12 @@ export abstract class BaseReporter implements Reporter {
       )
     }
 
+    const leaks = this.ctx.state.leakSet.size
+
+    if (leaks) {
+      this.log(padSummaryTitle('Leaks'), c.bold(c.red(`${leaks} leak${leaks > 1 ? 's' : ''}`)))
+    }
+
     this.log(padSummaryTitle('Start at'), this._timeStart)
 
     const collectTime = sum(files, file => file.collectDuration)
@@ -776,6 +785,51 @@ export abstract class BaseReporter implements Reporter {
     }
   }
 
+  private printLeaksSummary() {
+    const leaks = this.ctx.state.leakSet
+
+    if (leaks.size === 0) {
+      return
+    }
+
+    this.error(`\n${errorBanner(`Async Leaks ${leaks.size}`)}\n`)
+
+    for (const leak of leaks) {
+      const filename = this.relative(leak.filename)
+
+      this.ctx.logger.error(c.red(`${leak.type} leaking in ${filename}`))
+
+      const stacks = parseStacktrace(leak.stack)
+
+      if (stacks.length === 0) {
+        continue
+      }
+
+      try {
+        const sourceCode = readFileSync(stacks[0].file, 'utf-8')
+
+        this.ctx.logger.error(generateCodeFrame(
+          sourceCode.length > 100_000
+            ? sourceCode
+            : this.ctx.logger.highlight(stacks[0].file, sourceCode),
+          undefined,
+          stacks[0],
+        ))
+      }
+      catch {
+        // ignore error, do not produce more detailed message with code frame.
+      }
+
+      printStack(
+        this.ctx.logger,
+        this.ctx.getProjectByName(leak.projectName),
+        stacks,
+        stacks[0],
+        {},
+      )
+    }
+  }
+
   reportBenchmarkSummary(files: File[]): void {
     const benches = getTests(files)
     const topBenches = benches.filter(i => i.result?.benchmark?.rank === 1)
diff --git a/packages/vitest/src/node/state.ts b/packages/vitest/src/node/state.ts
@@ -1,5 +1,5 @@
 import type { File, FileSpecification, Task, TaskResultPack } from '@vitest/runner'
-import type { UserConsoleLog } from '../types/general'
+import type { AsyncLeak, UserConsoleLog } from '../types/general'
 import type { TestProject } from './project'
 import type { MergedBlobs } from './reporters/blob'
 import type { OnUnhandledErrorCallback } from './types/config'
@@ -22,6 +22,7 @@ export class StateManager {
   idMap: Map<string, Task> = new Map()
   taskFileMap: WeakMap<Task, File> = new WeakMap()
   errorsSet: Set<unknown> = new Set()
+  leakSet: Set<AsyncLeak> = new Set()
   reportedTasksMap: WeakMap<Task, TestModule | TestCase | TestSuite> = new WeakMap()
   blobs?: MergedBlobs
   transformTime = 0
@@ -82,8 +83,13 @@ export class StateManager {
     }
   }
 
+  catchLeaks(leaks: AsyncLeak[]): void {
+    leaks.forEach(leak => this.leakSet.add(leak))
+  }
+
   clearErrors(): void {
     this.errorsSet.clear()
+    this.leakSet.clear()
   }
 
   getUnhandledErrors(): unknown[] {
diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts
@@ -601,6 +601,13 @@ export interface InlineConfig {
    */
   logHeapUsage?: boolean
 
+  /**
+   * Detect asynchronous resources leaking from the test file.
+   *
+   * @default false
+   */
+  detectAsyncLeaks?: boolean
+
   /**
    * Custom environment variables assigned to `process.env` before running tests.
    */
diff --git a/packages/vitest/src/runtime/config.ts b/packages/vitest/src/runtime/config.ts
@@ -117,6 +117,7 @@ export interface SerializedConfig {
   }
   standalone: boolean
   logHeapUsage: boolean | undefined
+  detectAsyncLeaks: boolean
   coverage: SerializedCoverageConfig
   benchmark: {
     includeSamples: boolean
diff --git a/packages/vitest/src/runtime/detect-async-leaks.ts b/packages/vitest/src/runtime/detect-async-leaks.ts
@@ -0,0 +1,99 @@
+import type { AsyncLeak } from '../types/general'
+import { createHook } from 'node:async_hooks'
+
+interface PossibleLeak extends AsyncLeak {
+  isActive: () => boolean
+}
+
+const IGNORED_TYPES = new Set([
+  'DNSCHANNEL',
+  'ELDHISTOGRAM',
+  'PerformanceObserver',
+  'RANDOMBYTESREQUEST',
+  'SIGNREQUEST',
+  'STREAM_END_OF_STREAM',
+  'TCPWRAP',
+  'TIMERWRAP',
+  'TLSWRAP',
+  'ZLIB',
+])
+
+export function detectAsyncLeaks(testFile: string, projectName: string): () => Promise<AsyncLeak[]> {
+  const resources = new Map<number, PossibleLeak>()
+
+  const hook = createHook({
+    init(asyncId, type, triggerAsyncId, resource) {
+      if (IGNORED_TYPES.has(type)) {
+        return
+      }
+
+      let stack = ''
+
+      // VitestModuleEvaluator's async wrapper of node:vm causes out-of-bound stack traces, simply skip it.
+      // Crash fixed in https://github.com/vitejs/vite/pull/21585
+      try {
+        stack = new Error('VITEST_DETECT_ASYNC_LEAKS').stack || ''
+      }
+      catch {
+        return
+      }
+
+      if (!stack.includes(testFile)) {
+        const trigger = resources.get(triggerAsyncId)
+
+        if (!trigger) {
+          return
+        }
+
+        stack = trigger.stack
+      }
+
+      let isActive = isActiveDefault
+
+      if ('hasRef' in resource) {
+        const ref = new WeakRef(resource as { hasRef: () => boolean })
+
+        isActive = () => ref.deref()?.hasRef() ?? false
+      }
+
+      resources.set(asyncId, { type, stack, projectName, filename: testFile, isActive })
+    },
+    destroy(asyncId) {
+      if (resources.get(asyncId)?.type !== 'PROMISE') {
+        resources.delete(asyncId)
+      }
+    },
+    promiseResolve(asyncId) {
+      resources.delete(asyncId)
+    },
+  })
+
+  hook.enable()
+
+  return async function collect() {
+    await Promise.resolve(setImmediate)
+
+    hook.disable()
+
+    const leaks = []
+
+    for (const resource of resources.values()) {
+      if (resource.isActive()) {
+        leaks.push({
+          stack: resource.stack,
+          type: resource.type,
+          filename: resource.filename,
+          projectName: resource.projectName,
+        })
+      }
+    }
+
+    resources.clear()
+
+    return leaks
+  }
+}
+
+function isActiveDefault() {
+  return true
+}
diff --git a/packages/vitest/src/runtime/runBaseTests.ts b/packages/vitest/src/runtime/runBaseTests.ts
diff --git a/packages/vitest/src/runtime/runVmTests.ts b/packages/vitest/src/runtime/runVmTests.ts
diff --git a/packages/vitest/src/types/general.ts b/packages/vitest/src/types/general.ts
diff --git a/packages/vitest/src/types/rpc.ts b/packages/vitest/src/types/rpc.ts
diff --git a/test/cli/test/detect-async-leaks.test.ts b/test/cli/test/detect-async-leaks.test.ts
diff --git a/test/config/test/failures.test.ts b/test/config/test/failures.test.ts

Original file line number	Diff line number	Diff line change
`@@ -354,6 +354,10 @@ export function resolveConfig(`
`354`	`354`	throw new Error(`"Istanbul" coverage provider is not compatible with "experimental.viteModuleRunner: false". Please, enable "viteModuleRunner" or switch to "v8" coverage provider.`)
`355`	`355`	`}`
`356`	`356`
	`357`	`+ if (browser.enabled && resolved.detectAsyncLeaks) {`
	`358`	`+ logger.console.warn(c.yellow('The option "detectAsyncLeaks" is not supported in browser mode and will be ignored.'))`
	`359`	`+ }`
	`360`	`+`
`357`	`361`	`const containsChromium = hasBrowserChromium(vitest, resolved)`
`358`	`362`	`const hasOnlyChromium = hasOnlyBrowserChromium(vitest, resolved)`
`359`	`363`