fix(coverage): fail fast when coverage.reportsDirectory conflicts between concurrent runs (#10466)

jgamaraalv · AriPerkkio · web-flow · commit 833f0936ce16 · 2026-06-23T12:59:10.000+03:00
Co-authored-by: Ari Perkkiö &lt;ari.perkkio@gmail.com&gt;
diff --git a/packages/vitest/src/node/coverage.ts b/packages/vitest/src/node/coverage.ts
@@ -5,8 +5,10 @@ import type { CoverageModuleLoader, CoverageOptions, CoverageProvider, ReportCon
 import type { SerializedCoverageConfig } from '../runtime/config'
 import type { AfterSuiteRunMeta } from '../types/general'
 import type { TestProject } from './project'
+import { createHash } from 'node:crypto'
 import { existsSync, promises as fs, readdirSync, writeFileSync } from 'node:fs'
 import module from 'node:module'
+import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { cleanUrl, slash } from '@vitest/utils/helpers'
@@ -89,6 +91,7 @@ export class BaseCoverageProvider {
   coverageFiles: CoverageFiles = new Map()
   pendingPromises: Promise<void>[] = []
   coverageFilesDirectory!: string
+  reportsDirectoryLock!: ReportsDirectoryLock
   roots: string[] = []
   changedFiles?: string[]
 
@@ -140,6 +143,7 @@ export class BaseCoverageProvider {
       this.options.reportsDirectory,
       tempDirectory,
     )
+    this.reportsDirectoryLock = new ReportsDirectoryLock(resolve(this.options.reportsDirectory))
 
     // If --project filter is set pick only roots of resolved projects
     this.roots = ctx.config.project?.length
@@ -245,6 +249,8 @@ export class BaseCoverageProvider {
   }
 
   async clean(clean = true): Promise<void> {
+    await this.reportsDirectoryLock.acquire()
+
     if (clean && existsSync(this.options.reportsDirectory)) {
       await fs.rm(this.options.reportsDirectory, {
         recursive: true,
@@ -354,12 +360,17 @@ export class BaseCoverageProvider {
   }
 
   async cleanAfterRun(): Promise<void> {
-    this.coverageFiles = new Map()
-    await fs.rm(this.coverageFilesDirectory, { recursive: true })
+    try {
+      this.coverageFiles = new Map()
+      await fs.rm(this.coverageFilesDirectory, { recursive: true })
 
-    // Remove empty reports directory, e.g. when only text-reporter is used
-    if (readdirSync(this.options.reportsDirectory).length === 0) {
-      await fs.rm(this.options.reportsDirectory, { recursive: true })
+      // Remove empty reports directory, e.g. when only text-reporter is used
+      if (readdirSync(this.options.reportsDirectory).length === 0) {
+        await fs.rm(this.options.reportsDirectory, { recursive: true })
+      }
+    }
+    finally {
+      await this.reportsDirectoryLock.release()
     }
   }
 
@@ -952,3 +963,112 @@ function resolveMergeConfig(mod: any): any {
     }
   }
 }
+
+/**
+ * Cross-process lock on a coverage `reportsDirectory`.
+ *
+ * Two `vitest run --coverage` runs pointed at the same reports directory delete
+ * each other's reports, so the second one to start fails fast instead. The lock
+ * file lives in the OS temp directory so it survives the cleanup it guards, and a
+ * lock left behind by a process that no longer exists is reclaimed on the next run.
+ */
+interface LockOwner {
+  pid: number
+  reportsDirectory: string
+}
+
+class ReportsDirectoryLock {
+  readonly lockFile: string
+
+  constructor(private readonly reportsDirectory: string) {
+    const hash = createHash('sha256')
+      .update(reportsDirectory)
+      .digest('hex')
+      .slice(0, 16)
+
+    this.lockFile = resolve(tmpdir(), `vitest-coverage-${hash}.lock`)
+  }
+
+  async acquire(): Promise<void> {
+    if (await this.tryWrite()) {
+      return
+    }
+
+    const owner = await this.readOwner()
+
+    // We already hold the lock for this directory (e.g. watch-mode reruns).
+    if (owner?.pid === process.pid) {
+      return
+    }
+
+    // Another running Vitest owns this directory.
+    if (owner && isProcessAlive(owner.pid)) {
+      throw this.inUseError(owner)
+    }
+
+    // The lock was left behind by a process that no longer exists. Reclaim it.
+    await fs.rm(this.lockFile, { force: true })
+
+    if (!(await this.tryWrite())) {
+      throw this.inUseError(await this.readOwner())
+    }
+  }
+
+  async release(): Promise<void> {
+    const owner = await this.readOwner()
+
+    if (owner?.pid === process.pid) {
+      await fs.rm(this.lockFile, { force: true })
+    }
+  }
+
+  private async tryWrite(): Promise<boolean> {
+    const payload = JSON.stringify({ pid: process.pid, reportsDirectory: this.reportsDirectory })
+
+    try {
+      // `wx` fails with EEXIST if the file already exists, so only one process wins.
+      await fs.writeFile(this.lockFile, payload, { flag: 'wx' })
+      return true
+    }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+        return false
+      }
+      throw error
+    }
+  }
+
+  private async readOwner(): Promise<LockOwner | null> {
+    try {
+      const owner = JSON.parse(await fs.readFile(this.lockFile, 'utf-8'))
+      return typeof owner?.pid === 'number' ? owner : null
+    }
+    catch {
+      return null
+    }
+  }
+
+  private inUseError(owner: LockOwner | null): Error {
+    return new Error(
+      `The coverage report directory "${this.reportsDirectory}" is already in use by `
+      + `another Vitest process${owner ? ` (pid ${owner.pid})` : ''}. Running coverage for multiple `
+      + `Vitest processes in the same directory at the same time is not supported, because they would `
+      + `delete each other's reports.\nGive each run its own "coverage.reportsDirectory" `
+      + `(e.g. --coverage.reportsDirectory=coverage-${process.pid}) or run them sequentially.`,
+    )
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    // Sending signal 0 checks if the process exists without actually killing it:
+    // https://nodejs.org/api/process.html#processkillpid-signal
+    process.kill(pid, 0)
+    return true
+  }
+  catch (error) {
+    // ESRCH means the process is gone. Treat anything else (e.g. EPERM) as alive
+    // so we never reclaim a lock from a process that is still running.
+    return (error as NodeJS.ErrnoException).code !== 'ESRCH'
+  }
+}
diff --git a/test/coverage-test/test/temporary-files.unit.test.ts b/test/coverage-test/test/temporary-files.unit.test.ts
@@ -1,5 +1,8 @@
-import { resolve } from 'node:path'
-import { expect, test } from 'vitest'
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { assert, expect, onTestFinished, test } from 'vitest'
 import { BaseCoverageProvider } from 'vitest/node'
 
 test('missing coverage temp directory throws an actionable error', async () => {
@@ -17,3 +20,99 @@ test('missing coverage temp directory throws an actionable error', async () => {
     `Something removed the coverage directory "${provider.coverageFilesDirectory}" Vitest created earlier. Make sure you are not running multiple Vitests with the same "coverage.reportsDirectory" at the same time.`,
   )
 })
+
+test('clean() acquires the reportsDirectory lock and cleanAfterRun() releases it', async () => {
+  const { provider, lockFile } = createProvider()
+
+  await provider.clean(true)
+
+  expect(existsSync(provider.coverageFilesDirectory)).toBe(true)
+  expect(existsSync(lockFile)).toBe(true)
+  expect(JSON.parse(readFileSync(lockFile, 'utf-8')).pid).toBe(process.pid)
+
+  await provider.cleanAfterRun()
+
+  expect(existsSync(lockFile)).toBe(false)
+})
+
+test('clean() is re-entrant for the same process (e.g. watch mode reruns)', async () => {
+  const { provider } = createProvider()
+
+  await provider.clean(true)
+
+  // Should not throw lockfile acquiring errors
+  await expect(provider.clean(true)).resolves.toBeUndefined()
+
+  await provider.cleanAfterRun()
+})
+
+test('clean() throws an actionable error when another live process holds the lock', async () => {
+  const { provider, reportsDirectory, lockFile } = createProvider()
+
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' })
+  onTestFinished(() => void child.kill())
+  await new Promise(resolve => child.once('spawn', resolve))
+
+  const childPid = child.pid
+  assert(childPid != null, 'child process did not start')
+
+  writeFileSync(lockFile, JSON.stringify({ pid: childPid, reportsDirectory }))
+
+  await expect(provider.clean(true)).rejects.toThrow(
+    `The coverage report directory "${reportsDirectory.replaceAll(sep, '/')}" is already in use by `
+    + `another Vitest process (pid ${childPid}). Running coverage for multiple `
+    + `Vitest processes in the same directory at the same time is not supported, because they would `
+    + `delete each other's reports.\nGive each run its own "coverage.reportsDirectory" `
+    + `(e.g. --coverage.reportsDirectory=coverage-${process.pid}) or run them sequentially.`,
+  )
+
+  expect(JSON.parse(readFileSync(lockFile, 'utf-8')).pid).toBe(childPid)
+})
+
+test('clean() reclaims an empty / non-JSON lock file without crashing', async () => {
+  const { provider, lockFile } = createProvider()
+
+  writeFileSync(lockFile, 'not-valid-json{')
+
+  await expect(provider.clean(true)).resolves.toBeUndefined()
+
+  expect(JSON.parse(readFileSync(lockFile, 'utf-8')).pid).toBe(process.pid)
+
+  await provider.cleanAfterRun()
+})
+
+test('clean() reclaims a stale lock left by a process that no longer exists', async () => {
+  const { provider, reportsDirectory, lockFile } = createProvider()
+
+  const child = spawn(process.execPath, ['-e', ''], { stdio: 'ignore' })
+  await new Promise(resolve => child.once('exit', resolve))
+
+  const deadPid = child.pid
+  assert(deadPid != null, 'child process did not start')
+
+  writeFileSync(lockFile, JSON.stringify({ pid: deadPid, reportsDirectory }))
+
+  await expect(provider.clean(true)).resolves.toBeUndefined()
+
+  expect(JSON.parse(readFileSync(lockFile, 'utf-8')).pid).toBe(process.pid)
+
+  await provider.cleanAfterRun()
+})
+
+function createProvider() {
+  const reportsDirectory = mkdtempSync(join(tmpdir(), 'vitest-coverage-reports-'))
+  onTestFinished(() => rmSync(reportsDirectory, { recursive: true, force: true }))
+
+  const provider = new BaseCoverageProvider()
+  provider._initialize({
+    logger: { warn: () => {} },
+    config: { root: process.cwd() },
+    _coverageOptions: { reportsDirectory },
+  } as any)
+
+  // eslint-disable-next-line dot-notation -- Accessing private property
+  const lockFile = provider['reportsDirectoryLock'].lockFile
+  onTestFinished(() => rmSync(lockFile, { force: true }))
+
+  return { provider, reportsDirectory, lockFile }
+}
