perf(coverage-v8): resolve raw coverage in main process (#1501)

9aoy · web-flow · commit e8f7f6390a1b · 2026-07-06T15:01:16.000+08:00
diff --git a/packages/core/src/core/runTests.ts b/packages/core/src/core/runTests.ts
@@ -1,5 +1,9 @@
 import { constants as osConstants } from 'node:os';
-import { cleanCoverageReports, createCoverageProvider } from '../coverage';
+import {
+  cleanCoverageReports,
+  createCoverageProvider,
+  resolveAndMergeRawCoverage,
+} from '../coverage';
 import { ensureRunDependencies } from './dependencies';
 import { createPool } from '../pool';
 import type {
@@ -160,12 +164,38 @@ const notifyReportersOnTestRunEnd = async ({
 
 const isLifecycleDebugEnabled = isDebug();
 
+type LifecycleStepOptions = {
+  slowAfter?: number;
+  slowMessage?: string;
+  slowDoneMessage?: string;
+};
+
 const runLifecycleStep = async <T>(
   label: string,
   fn: () => Promise<T>,
+  options?: LifecycleStepOptions,
 ): Promise<T> => {
+  const { slowAfter, slowMessage, slowDoneMessage } = options ?? {};
+  let didShowSlowMessage = false;
+  const slowTimer = slowMessage
+    ? setTimeout(() => {
+        didShowSlowMessage = true;
+        logger.info(slowMessage);
+      }, slowAfter ?? 1000)
+    : undefined;
+
   if (!isLifecycleDebugEnabled) {
-    return fn();
+    try {
+      const result = await fn();
+      if (didShowSlowMessage && slowDoneMessage) {
+        logger.info(slowDoneMessage);
+      }
+      return result;
+    } finally {
+      if (slowTimer) {
+        clearTimeout(slowTimer);
+      }
+    }
   }
 
   const startTime = Date.now();
@@ -174,10 +204,17 @@ const runLifecycleStep = async <T>(
   try {
     const result = await fn();
     logger.debug(`lifecycle: finish ${label} (${Date.now() - startTime}ms)`);
+    if (didShowSlowMessage && slowDoneMessage) {
+      logger.info(slowDoneMessage);
+    }
     return result;
   } catch (error) {
     logger.debug(`lifecycle: fail ${label} (${Date.now() - startTime}ms)`);
     throw error;
+  } finally {
+    if (slowTimer) {
+      clearTimeout(slowTimer);
+    }
   }
 };
 
@@ -573,6 +610,7 @@ export async function runTests(context: Rstest): Promise<void> {
     const mergedCoverageMap: CoverageMap | undefined = coverageProvider
       ? coverageProvider.createCoverageMap()
       : undefined;
+    const rawCoverageResults: unknown[] = [];
 
     // Adopt the pre-allocated buffer (set above `runTests` or at the end of
     // the previous rerun's `finalize`) so browser events emitted before
@@ -688,6 +726,7 @@ export async function runTests(context: Rstest): Promise<void> {
           buildId,
           updateSnapshot: context.snapshotManager.options.updateSnapshot,
           onCoverageResult: (coverage) => mergedCoverageMap?.merge(coverage),
+          onRawCoverageResult: (coverage) => rawCoverageResults.push(coverage),
           onTraceEvents: traceRun.onEvents,
           traceSpan: span,
         });
@@ -704,8 +743,6 @@ export async function runTests(context: Rstest): Promise<void> {
     testStart ??= buildStart;
     const buildTime = testStart - buildStart;
 
-    const testTime = Date.now() - testStart;
-
     // Wait for browser tests to complete if running in parallel
     const browserResult = browserResultPromise
       ? await browserResultPromise
@@ -746,21 +783,6 @@ export async function runTests(context: Rstest): Promise<void> {
       // from the browser results to avoid reporter/state cache bloat (mirrors
       // the node-side pool layer's `delete result.coverage`).
 
-      // When unifying reporter output, combine browser and node durations
-      const duration: Duration =
-        shouldUnifyReporter && browserResult
-          ? {
-              totalTime:
-                testTime + buildTime + browserResult.duration.totalTime,
-              buildTime: buildTime + browserResult.duration.buildTime,
-              testTime: testTime + browserResult.duration.testTime,
-            }
-          : {
-              totalTime: testTime + buildTime,
-              buildTime,
-              testTime,
-            };
-
       const results = returns.flatMap((r) => r.results);
       const testResults = returns.flatMap((r) => r.testResults);
       const errors = returns.flatMap((r) => r.errors || []);
@@ -786,6 +808,28 @@ export async function runTests(context: Rstest): Promise<void> {
         errors.push(...browserResult.unhandledErrors);
       }
 
+      await resolveAndMergeRawCoverage({
+        coverageProvider,
+        mergedCoverageMap,
+        rawCoverageResults,
+        runCoverageStep: runLifecycleStep,
+      });
+
+      const testTime = Date.now() - testStart;
+      const duration: Duration =
+        shouldUnifyReporter && browserResult
+          ? {
+              totalTime:
+                testTime + buildTime + browserResult.duration.totalTime,
+              buildTime: buildTime + browserResult.duration.buildTime,
+              testTime: testTime + browserResult.duration.testTime,
+            }
+          : {
+              totalTime: testTime + buildTime,
+              buildTime,
+              testTime,
+            };
+
       // Check for failures including browser results when unified
       const nodeHasFailure =
         results.some((r) => r.status === 'fail') || errors.length;
diff --git a/packages/core/src/coverage/index.ts b/packages/core/src/coverage/index.ts
@@ -13,6 +13,7 @@ import {
   getCoverageProviderModuleName,
 } from './install';
 export { ensureCoverageProviderInstalled } from './install';
+export { resolveAndMergeRawCoverage } from './resolveRawCoverage';
 
 export const loadCoverageProvider = async (
   options: CoverageOptions,
diff --git a/packages/core/src/coverage/resolveRawCoverage.ts b/packages/core/src/coverage/resolveRawCoverage.ts
@@ -0,0 +1,40 @@
+import type { CoverageMap, CoverageProvider } from '../types/coverage';
+
+type RunCoverageStep = <T>(
+  label: string,
+  fn: () => Promise<T>,
+  options?: {
+    slowMessage?: string;
+    slowDoneMessage?: string;
+  },
+) => Promise<T>;
+
+export const resolveAndMergeRawCoverage = async ({
+  coverageProvider,
+  mergedCoverageMap,
+  rawCoverageResults,
+  runCoverageStep,
+}: {
+  coverageProvider: CoverageProvider | null;
+  mergedCoverageMap?: CoverageMap;
+  rawCoverageResults: unknown[];
+  runCoverageStep: RunCoverageStep;
+}): Promise<void> => {
+  const resolveRawCoverage =
+    coverageProvider?.resolveRawCoverage?.bind(coverageProvider);
+  if (!rawCoverageResults.length || !resolveRawCoverage) {
+    return;
+  }
+
+  const rawCoverageMap = await runCoverageStep(
+    'coverage collect',
+    async () => resolveRawCoverage(rawCoverageResults),
+    {
+      slowMessage: 'processing coverage results...',
+      slowDoneMessage: 'coverage results processed.',
+    },
+  );
+  if (rawCoverageMap) {
+    mergedCoverageMap?.merge(rawCoverageMap);
+  }
+};
diff --git a/packages/core/src/pool/index.ts b/packages/core/src/pool/index.ts
@@ -284,6 +284,7 @@ export const createPool = async ({
     buildId?: number;
     /** When provided, coverage data is passed to this callback immediately for caller-owned merging. */
     onCoverageResult?: (coverage: CoverageMapData) => void;
+    onRawCoverageResult?: (coverage: unknown) => void;
     /** Perfetto trace events forwarded for caller-owned dumping. */
     onTraceEvents?: (events: TraceEvent[]) => void;
     /** Records host-side pool slices in the caller-owned Perfetto trace. */
@@ -479,6 +480,7 @@ export const createPool = async ({
       updateSnapshot,
       buildId,
       onCoverageResult,
+      onRawCoverageResult,
       onTraceEvents,
       traceSpan,
     }) => {
@@ -538,6 +540,10 @@ export const createPool = async ({
             onCoverageResult?.(result.coverage);
             delete result.coverage;
           }
+          if (result.coverageRaw != null) {
+            onRawCoverageResult?.(result.coverageRaw);
+            delete result.coverageRaw;
+          }
           if (result.traceEvents) {
             onTraceEvents?.(result.traceEvents);
             delete result.traceEvents;
diff --git a/packages/core/src/runtime/worker/runInPool.ts b/packages/core/src/runtime/worker/runInPool.ts
@@ -686,20 +686,35 @@ export const runInPool = async (
 
     // Collect coverage data after test file completes
     if (coverageProvider) {
+      const provider = coverageProvider;
       tracker.transition('coverage');
-      const coverageMap = await coverageProvider.collect({
+      const collectOptions = {
         assetFiles,
         sourceMaps,
         outputModule: options.context.outputModule,
-      });
-      if (coverageMap) {
-        // Attach coverage data to test result
-        results.coverage = {};
-        Object.entries(coverageMap.toJSON()).forEach(([key, value]) => {
-          if ('toJSON' in value)
-            results.coverage![key] = value.toJSON() as FileCoverageData;
-          else results.coverage![key] = value;
-        });
+      };
+
+      const collectCoverage = async () => {
+        const coverageMap = await provider.collect(collectOptions);
+        if (coverageMap) {
+          results.coverage = {};
+          Object.entries(coverageMap.toJSON()).forEach(([key, value]) => {
+            if ('toJSON' in value)
+              results.coverage![key] = value.toJSON() as FileCoverageData;
+            else results.coverage![key] = value;
+          });
+        }
+      };
+
+      if (provider.collectRaw && provider.resolveRawCoverage) {
+        const rawCoverage = await provider.collectRaw(collectOptions);
+        if (rawCoverage != null) {
+          results.coverageRaw = rawCoverage;
+        } else {
+          await collectCoverage();
+        }
+      } else {
+        await collectCoverage();
       }
     }
 
diff --git a/packages/core/src/types/coverage.ts b/packages/core/src/types/coverage.ts
@@ -153,6 +153,12 @@ export type NormalizedCoverageOptions = Required<
   changed?: boolean | string;
 };
 
+export type CoverageCollectOptions = {
+  assetFiles?: Record<string, string>;
+  sourceMaps?: Record<string, string>;
+  outputModule?: boolean;
+};
+
 export declare class CoverageProvider {
   constructor(options: NormalizedCoverageOptions, root?: string);
   /**
@@ -161,13 +167,35 @@ export declare class CoverageProvider {
   init(): void | Promise<void>;
 
   /**
-   * Collect coverage data from global coverage object
+   * Collect coverage data into an Istanbul coverage map.
    */
-  collect(options?: {
-    assetFiles?: Record<string, string>;
-    sourceMaps?: Record<string, string>;
-    outputModule?: boolean;
-  }): CoverageMap | null | Promise<CoverageMap | null>;
+  collect(
+    options?: CoverageCollectOptions,
+  ): CoverageMap | null | Promise<CoverageMap | null>;
+
+  /**
+   * Collect lightweight, serializable raw coverage payloads in workers.
+   *
+   * Providers may implement this with `resolveRawCoverage` to defer expensive
+   * conversion work to the main process. Return `null` to indicate that no raw
+   * coverage was collected and the runner should not call `resolveRawCoverage`
+   * for that worker result.
+   */
+  collectRaw?(
+    options?: CoverageCollectOptions,
+  ): unknown | null | Promise<unknown | null>;
+
+  /**
+   * Resolve raw payloads produced by `collectRaw` into an Istanbul coverage map.
+   *
+   * The runner passes only non-null payloads returned by the same provider.
+   * Implementations should ignore malformed payloads only when they can still
+   * produce a valid partial report; otherwise they may reject to fail coverage
+   * finalization.
+   */
+  resolveRawCoverage?(
+    payloads: unknown[],
+  ): CoverageMap | null | Promise<CoverageMap | null>;
 
   /**
    * Create a new coverage map
diff --git a/packages/core/src/types/testSuite.ts b/packages/core/src/types/testSuite.ts
@@ -182,6 +182,13 @@ export type TestFileResult = TestResult & {
   results: TestResult[];
   snapshotResult?: SnapshotResult;
   coverage?: Record<string, FileCoverageData>;
+  /**
+   * Raw coverage payload used internally between workers and the pool.
+   * Stripped at the pool boundary before results are exposed to reporters.
+   *
+   * @internal
+   */
+  coverageRaw?: unknown;
   /**
    * Perfetto-compatible trace events. Stripped at the pool boundary.
    *
diff --git a/packages/coverage-v8/src/provider.ts b/packages/coverage-v8/src/provider.ts
diff --git a/packages/coverage-v8/tests/provider.test.ts b/packages/coverage-v8/tests/provider.test.ts
