feat: add --detect-async-leaks

AriPerkkio · AriPerkkio · commit 284d33b2b80e · 2026-01-31T15:13:15.000+02:00
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
@@ -423,6 +423,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/serializeConfig.ts b/packages/vitest/src/node/config/serializeConfig.ts
@@ -14,6 +14,7 @@ export function serializeConfig(project: TestProject): SerializedConfig {
     maxWorkers: config.maxWorkers,
     base: config.base,
     logHeapUsage: config.logHeapUsage,
+    detectAsyncLeaks: config.detectAsyncLeaks,
     runner: config.runner,
     bail: config.bail,
     defines: config.defines,
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)
@@ -747,6 +756,39 @@ export abstract class BaseReporter implements Reporter {
     }
   }
 
+  private printLeaksSummary() {
+    const leaks = this.ctx.state.leakSet
+
+    if (leaks.size) {
+      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)
+
+        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],
+        ))
+
+        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
@@ -586,6 +586,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
@@ -112,6 +112,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,79 @@
+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',
+  'PROMISE',
+  'RANDOMBYTESREQUEST',
+  'SIGNREQUEST',
+  '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
+      }
+
+      const stack = new Error('VITEST_DETECT_ASYNC_LEAKS').stack || ''
+
+      if (!stack.includes(testFile)) {
+        return
+      }
+
+      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) {
+      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
@@ -11,6 +11,7 @@ import {
 } from '../integrations/coverage'
 import { resolveSnapshotEnvironment } from '../integrations/snapshot/environments/resolveSnapshotEnvironment'
 import { vi } from '../integrations/vi'
+import { detectAsyncLeaks } from './detect-async-leaks'
 import { closeInspector } from './inspector'
 import { resolveTestRunner } from './runners'
 import { setupGlobalEnv } from './setup-node'
@@ -57,11 +58,19 @@ export async function run(
         workerState.filepath = file.filepath
 
         if (method === 'run') {
+          const collectAsyncLeaks = config.detectAsyncLeaks ? detectAsyncLeaks(file.filepath, workerState.ctx.projectName) : undefined
+
           await traces.$(
             `vitest.test.runner.${method}.module`,
             { attributes: { 'code.file.path': file.filepath } },
             () => startTests([file], testRunner),
           )
+
+          const leaks = await collectAsyncLeaks?.()
+
+          if (leaks?.length) {
+            workerState.rpc.onAsyncLeaks(leaks)
+          }
         }
         else {
           await traces.$(
diff --git a/packages/vitest/src/runtime/runVmTests.ts b/packages/vitest/src/runtime/runVmTests.ts
@@ -16,6 +16,7 @@ import {
 } from '../integrations/coverage'
 import { resolveSnapshotEnvironment } from '../integrations/snapshot/environments/resolveSnapshotEnvironment'
 import * as VitestIndex from '../public/index'
+import { detectAsyncLeaks } from './detect-async-leaks'
 import { closeInspector } from './inspector'
 import { resolveTestRunner } from './runners'
 import { setupCommonEnv } from './setup-common'
@@ -97,11 +98,19 @@ export async function run(
         workerState.filepath = file.filepath
 
         if (method === 'run') {
+          const collectAsyncLeaks = config.detectAsyncLeaks ? detectAsyncLeaks(file.filepath, workerState.ctx.projectName) : undefined
+
           await traces.$(
             `vitest.test.runner.${method}.module`,
             { attributes: { 'code.file.path': file.filepath } },
             () => startTests([file], testRunner),
           )
+
+          const leaks = await collectAsyncLeaks?.()
+
+          if (leaks?.length) {
+            workerState.rpc.onAsyncLeaks(leaks)
+          }
         }
         else {
           await traces.$(
diff --git a/packages/vitest/src/types/general.ts b/packages/vitest/src/types/general.ts
@@ -44,3 +44,10 @@ export interface FetchCachedFileSystemResult {
 
 // These need to be compatible with Tinyrainbow's bg-colors, and CSS's background-color
 export type LabelColor = 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white'
+
+export interface AsyncLeak {
+  filename: string
+  projectName: string
+  stack: string
+  type: string
+}
diff --git a/packages/vitest/src/types/rpc.ts b/packages/vitest/src/types/rpc.ts
@@ -2,7 +2,7 @@ import type { CancelReason, File, TaskEventPack, TaskResultPack, TestArtifact }
 import type { SnapshotResult } from '@vitest/snapshot'
 import type { FetchFunctionOptions, FetchResult } from 'vite/module-runner'
 import type { OTELCarrier } from '../utils/traces'
-import type { AfterSuiteRunMeta, FetchCachedFileSystemResult, ResolveFunctionResult, UserConsoleLog } from './general'
+import type { AfterSuiteRunMeta, AsyncLeak, FetchCachedFileSystemResult, ResolveFunctionResult, UserConsoleLog } from './general'
 
 export interface RuntimeRPC {
   fetch: (
@@ -17,6 +17,7 @@ export interface RuntimeRPC {
 
   onUserConsoleLog: (log: UserConsoleLog) => void
   onUnhandledError: (err: unknown, type: string) => void
+  onAsyncLeaks: (leak: AsyncLeak[]) => void
   onQueued: (file: File) => void
   onCollected: (files: File[]) => Promise<void>
   onAfterSuiteRun: (meta: AfterSuiteRunMeta) => void
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
diff --git a/test/core/src/timer-example.ts b/test/core/src/timer-example.ts
diff --git a/test/core/test/math.test.ts b/test/core/test/math.test.ts

Original file line number	Diff line number	Diff line change
`@@ -112,6 +112,7 @@ export interface SerializedConfig {`
`112`	`112`	`}`
`113`	`113`	`standalone: boolean`
`114`	`114`	`logHeapUsage: boolean \| undefined`
	`115`	`+ detectAsyncLeaks: boolean`
`115`	`116`	`coverage: SerializedCoverageConfig`
`116`	`117`	`benchmark: {`
`117`	`118`	`includeSamples: boolean`