feat(coverage): v8 to track node:child_process and node:worker_threads contexts

Author: AriPerkkio

docs/config/coverage.md

@@ -458,3 +458,14 @@ Note that setting this option does not change where coverage HTML report is gene
 - **CLI:** `--coverage.changed`, `--coverage.changed=<commit/branch>`
 
 Collect coverage only for files changed since a specified commit or branch. When set to `true`, it uses staged and unstaged changes.
+
+## coverage.trackProcessAndWorker
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Available for providers:** `'v8'`
+- **CLI:** `--coverage.trackProcessAndWorker`
+
+Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run.
+
+Note that this option has some performance overhead as its using [`NODE_V8_COVERAGE`](https://nodejs.org/api/cli.html#node-v8-coveragedir) internally. This triggers Node to write lots of unnecessary files on file system.

docs/guide/cli-generated.md

@@ -299,6 +299,13 @@ Apply exclusions again after coverage has been remapped to original sources. (de
 
 Directory of HTML coverage output to be served in UI mode and HTML reporter.
 
+### coverage.trackProcessAndWorker
+
+- **CLI:** `--coverage.trackProcessAndWorker`
+- **Config:** [coverage.trackProcessAndWorker](/config/coverage#coverage-trackprocessandworker)
+
+Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run. Supported only by `v8` provider. (default: false)
+
 ### mode
 
 - **CLI:** `--mode <name>`

packages/coverage-v8/src/index.ts

@@ -1,23 +1,40 @@
 import type { Profiler } from 'node:inspector'
 import type { CoverageProviderModule } from 'vitest/node'
 import type { ScriptCoverageWithOffset, V8CoverageProvider } from './provider'
+import { randomUUID } from 'node:crypto'
+import { readdir, readFile } from 'node:fs/promises'
 import inspector from 'node:inspector/promises'
+import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { normalize } from 'pathe'
 import { provider } from 'std-env'
 import { loadProvider } from './load-provider'
 
-const session = new inspector.Session()
 let enabled = false
 
-const mod: CoverageProviderModule = {
-  async startCoverage({ isolate }) {
+const mod: CoverageProviderModule & {
+  extendedContextCoverageDir?: string
+  // Use unknown to avoid bundling node:inspector
+  session?: unknown | null
+} = {
+  extendedContextCoverageDir: undefined,
+  session: null,
+
+  async startCoverage({ isolate, trackProcessAndWorker, reportsDirectory }) {
     if (isolate === false && enabled) {
       return
     }
 
     enabled = true
 
+    if (trackProcessAndWorker) {
+      this.extendedContextCoverageDir = resolve(reportsDirectory, 'tmp', randomUUID())
+      process.env.NODE_V8_COVERAGE = this.extendedContextCoverageDir
+    }
+
+    this.session ||= new inspector.Session()
+    const session = this.session as inspector.Session
+
     session.connect()
     await session.post('Profiler.enable')
     await session.post('Profiler.startPreciseCoverage', { callCount: true, detailed: true })
@@ -28,16 +45,43 @@ const mod: CoverageProviderModule = {
       return { result: [] }
     }
 
+    const session = this.session as inspector.Session
+
+    if (!session) {
+      throw new Error('V8 provider missing inspector session.')
+    }
+
     const coverage = await session.post('Profiler.takePreciseCoverage')
     const result: ScriptCoverageWithOffset[] = []
 
     // Reduce amount of data sent over rpc by doing some early result filtering
-    for (const entry of coverage.result) {
+    for (const entry of coverage.result as ScriptCoverageWithOffset[]) {
       if (filterResult(entry)) {
-        result.push({
-          ...entry,
-          startOffset: options?.moduleExecutionInfo?.get(normalize(fileURLToPath(entry.url)))?.startOffset || 0,
-        })
+        entry.startOffset = options?.moduleExecutionInfo?.get(normalize(fileURLToPath(entry.url)))?.startOffset || 0
+
+        result.push(entry)
+      }
+    }
+
+    if (this.extendedContextCoverageDir) {
+      const filenames = await readdir(this.extendedContextCoverageDir)
+      const contents = await Promise.all(
+        filenames
+          .filter(filename => filename.endsWith('.json'))
+          .map(filename => readFile(`${this.extendedContextCoverageDir}/${filename}`, 'utf8')),
+      )
+
+      for (const content of contents) {
+        const json: { result: ScriptCoverageWithOffset[] } = JSON.parse(content)
+
+        for (const entry of json.result) {
+          if (filterResult(entry)) {
+            entry.startOffset = 0
+            entry.isExtendedContext = true
+
+            result.push(entry)
+          }
+        }
       }
     }
 
@@ -49,9 +93,16 @@ const mod: CoverageProviderModule = {
       return
     }
 
+    const session = this.session as inspector.Session
+
+    if (!session) {
+      throw new Error('V8 provider missing inspector session.')
+    }
+
     await session.post('Profiler.stopPreciseCoverage')
     await session.post('Profiler.disable')
     session.disconnect()
+    this.session = null
   },
 
   async getProvider(): Promise<V8CoverageProvider> {

packages/coverage-v8/src/provider.ts

@@ -20,6 +20,9 @@ import { version } from '../package.json' with { type: 'json' }
 
 export interface ScriptCoverageWithOffset extends Profiler.ScriptCoverage {
   startOffset: number
+
+  /** Whether script ran outside Vite, e.g. in sub-processes or worker threads */
+  isExtendedContext?: boolean
 }
 
 interface RawCoverage { result: ScriptCoverageWithOffset[] }
@@ -34,6 +37,18 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
 
   initialize(ctx: Vitest): void {
     this._initialize(ctx)
+
+    if (this.options.trackProcessAndWorker) {
+      const isAnyThreadsPools = ctx.projects.some(p => p.config.pool === 'threads' || p.config.pool === 'vmThreads')
+
+      if (isAnyThreadsPools) {
+        // Work-around for https://github.com/nodejs/node/issues/46378
+        // Node never does anything with this directory, it's just required so that
+        // the next Workers read **their** env.NODE_V8_COVERAGE.
+        // Node never creates this .unused directory at all.
+        process.env.NODE_V8_COVERAGE = `${this.coverageFilesDirectory}/.unused`
+      }
+    }
   }
 
   createCoverageMap(): CoverageMap {
@@ -46,16 +61,26 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
     const coverageMap = this.createCoverageMap()
     let merged: RawCoverage = { result: [] }
 
+    const trackProcessAndWorker = this.options.trackProcessAndWorker
+
     await this.readCoverageFiles<RawCoverage>({
       onFileRead(coverage) {
         merged = mergeProcessCovs([merged, coverage])
 
+        // mergeProcessCovs sometimes loses trackProcessAndWorker
+        const fromExtendedContext = trackProcessAndWorker ? coverage.result.filter(r => r.isExtendedContext) : []
+
         // mergeProcessCovs sometimes loses startOffset, e.g. in vue
         merged.result.forEach((result) => {
           if (!result.startOffset) {
             const original = coverage.result.find(r => r.url === result.url)
             result.startOffset = original?.startOffset || 0
           }
+
+          if (trackProcessAndWorker && !result.isExtendedContext) {
+            const actual = fromExtendedContext.find(r => r.url === result.url)
+            result.isExtendedContext = actual?.isExtendedContext
+          }
         })
       },
       onFinished: async (project, environment) => {
@@ -331,8 +356,9 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
 
   private async getSources(
     url: string,
-    onTransform: (filepath: string) => Promise<Vite.TransformResult | undefined | null>,
+    onTransform: (filepath: string, isExtendedContext?: ScriptCoverageWithOffset['isExtendedContext']) => Promise<Vite.TransformResult | undefined | null>,
     functions: Profiler.FunctionCoverage[] = [],
+    isExtendedContext: ScriptCoverageWithOffset['isExtendedContext'] = false,
   ): Promise<{
     code: string
     map?: Vite.Rollup.SourceMap
@@ -342,7 +368,7 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
       ? url.slice(8)
       : removeStartsWith(url, FILE_PROTOCOL)
     // TODO: do we still need to "catch" here? why would it fail?
-    const transformResult = await onTransform(filepath).catch(() => null)
+    const transformResult = await onTransform(filepath, isExtendedContext).catch(() => null)
 
     const map = transformResult?.map as Vite.Rollup.SourceMap | undefined
     const code = transformResult?.code
@@ -385,8 +411,8 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
       throw new Error(`Cannot access browser module graph because it was torn down.`)
     }
 
-    const onTransform = async (filepath: string) => {
-      const result = await this.transformFile(filepath, project, environment)
+    const onTransform = async (filepath: string, isExtendedContext: ScriptCoverageWithOffset['isExtendedContext'] = false) => {
+      const result = await this.transformFile(filepath, project, environment, !isExtendedContext)
       if (result && environment === '__browser__' && project.browser) {
         return { ...result, code: `${result.code}// <inline-source-map>` }
       }
@@ -423,7 +449,7 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
       }
 
       await Promise.all(
-        chunk.map(async ({ url, functions, startOffset }) => {
+        chunk.map(async ({ url, functions, startOffset, isExtendedContext }) => {
           let timeout: ReturnType<typeof setTimeout> | undefined
           let start: number | undefined
 
@@ -436,6 +462,7 @@ export class V8CoverageProvider extends BaseCoverageProvider implements Coverage
             url,
             onTransform,
             functions,
+            isExtendedContext,
           )
 
           coverageMap.merge(await this.remapCoverage(

packages/vitest/src/defaults.ts

@@ -53,6 +53,7 @@ export const coverageConfigDefaults: Required<Pick<CoverageOptions, FieldsWithDe
     branches: [50, 80],
     lines: [50, 80],
   },
+  trackProcessAndWorker: false,
 }
 
 export const fakeTimersDefaults: NonNullable<UserConfig['fakeTimers']> = {

packages/vitest/src/integrations/coverage.ts

@@ -3,21 +3,25 @@ import type { RuntimeCoverageModuleLoader } from '../utils/coverage'
 import { resolveCoverageProviderModule } from '../utils/coverage'
 
 export async function startCoverageInsideWorker(
-  options: SerializedCoverageConfig | undefined,
+  options: SerializedCoverageConfig,
   loader: RuntimeCoverageModuleLoader,
   runtimeOptions: { isolate: boolean },
 ): Promise<unknown> {
   const coverageModule = await resolveCoverageProviderModule(options, loader)
 
   if (coverageModule) {
-    return coverageModule.startCoverage?.(runtimeOptions)
+    return coverageModule.startCoverage?.({
+      ...runtimeOptions,
+      trackProcessAndWorker: options.trackProcessAndWorker,
+      reportsDirectory: options.reportsDirectory,
+    })
   }
 
   return null
 }
 
 export async function takeCoverageInsideWorker(
-  options: SerializedCoverageConfig | undefined,
+  options: SerializedCoverageConfig,
   loader: RuntimeCoverageModuleLoader,
 ): Promise<unknown> {
   const coverageModule = await resolveCoverageProviderModule(options, loader)
@@ -30,7 +34,7 @@ export async function takeCoverageInsideWorker(
 }
 
 export async function stopCoverageInsideWorker(
-  options: SerializedCoverageConfig | undefined,
+  options: SerializedCoverageConfig,
   loader: RuntimeCoverageModuleLoader,
   runtimeOptions: { isolate: boolean },
 ): Promise<unknown> {

packages/vitest/src/node/cli/cli-config.ts

@@ -326,6 +326,9 @@ export const cliOptionsConfig: VitestCLIOptions = {
         description: 'Directory of HTML coverage output to be served in UI mode and HTML reporter.',
         argument: '<path>',
       },
+      trackProcessAndWorker: {
+        description: 'Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run. Supported only by `v8` provider. (default: false)',
+      },
     },
   },
   mode: {

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

@@ -1,6 +1,7 @@
 import type { SerializedConfig } from '../../runtime/config'
 import type { TestProject } from '../project'
 import type { ApiConfig } from '../types/config'
+import { resolve } from 'node:path'
 import { configDefaults } from '../../defaults'
 import { isAgent } from '../../utils/env'
 
@@ -53,13 +54,14 @@ export function serializeConfig(project: TestProject): SerializedConfig {
     passWithNoTests: config.passWithNoTests,
     coverage: ((coverage) => {
       return {
-        reportsDirectory: coverage.reportsDirectory,
+        reportsDirectory: resolve(globalConfig.root, coverage.reportsDirectory),
         provider: coverage.provider,
         enabled: coverage.enabled,
         customProviderModule: 'customProviderModule' in coverage
           ? coverage.customProviderModule
           : undefined,
         htmlDir: coverage.htmlDir,
+        trackProcessAndWorker: coverage.trackProcessAndWorker ?? false,
       }
     })(config.coverage),
     fakeTimers: config.fakeTimers,

packages/vitest/src/node/coverage.ts

@@ -685,11 +685,11 @@ export class BaseCoverageProvider {
   // TODO: should this be abstracted in `project`/`vitest` instead?
   // if we decide to keep `viteModuleRunner: false`, we will need to abstract transformation in both main thread and tests
   // custom --import=module.registerHooks need to be transformed as well somehow
-  async transformFile(url: string, project: TestProject, viteEnvironment: string): Promise<TransformResult | null | undefined> {
+  async transformFile(url: string, project: TestProject, viteEnvironment: string, isTransformedByVite = true): Promise<TransformResult | null | undefined> {
     const config = project.config
 
     // vite is disabled, should transform manually if possible
-    if (config.experimental.viteModuleRunner === false) {
+    if (config.experimental.viteModuleRunner === false || !isTransformedByVite) {
       const pathname = url.split('?')[0]
       const filename = pathname.startsWith('file://') ? fileURLToPath(pathname) : pathname
       const extension = path.extname(filename)

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

@@ -111,6 +111,7 @@ export type FieldsWithDefaultValues
     | 'ignoreClassMethods'
     | 'skipFull'
     | 'watermarks'
+    | 'trackProcessAndWorker'
 
 export type ResolvedCoverageOptions
   = CoverageOptions
@@ -264,6 +265,14 @@ export interface CoverageOptions {
    */
   processingConcurrency?: number
 
+  /**
+   * Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run.
+   * Supported only by `v8` provider.
+   *
+   * @default false
+   */
+  trackProcessAndWorker?: boolean
+
   /**
    * Set to array of class method names to ignore for coverage
    *