Coverage Provider Module (Node.js)

import coverageModule from '@vitest/coverage-v8';

interface CoverageProviderModule {
  /**
   * Initialize V8 coverage collection using Node.js Inspector API
   * @param options - Configuration options
   * @param options.isolate - If false and coverage is already enabled, skip initialization
   */
  startCoverage(options: { isolate?: boolean }): Promise<void>;

  /**
   * Take a snapshot of current V8 coverage data
   * @param options - Configuration options
   * @param options.moduleExecutionInfo - Map of file paths to execution metadata including startOffset
   * @returns Object containing array of script coverage results with offset information
   */
  takeCoverage(options?: {
    moduleExecutionInfo?: Map<string, { startOffset: number }>;
  }): Promise<{ result: ScriptCoverageWithOffset[] }>;

  /**
   * Stop coverage collection and disconnect from V8 Inspector
   * @param options - Configuration options
   * @param options.isolate - If false, skip stopping (leave coverage enabled)
   */
  stopCoverage(options: { isolate?: boolean }): Promise<void>;

  /**
   * Factory method to get the V8CoverageProvider instance
   * @returns Promise resolving to V8CoverageProvider instance
   */
  getProvider(): Promise<V8CoverageProvider>;
}

/**
 * Initialize V8 coverage collection using Node.js Inspector API.
 * Creates an inspector session, enables the Profiler, and starts precise coverage collection.
 *
 * @param options - Configuration options
 * @param options.isolate - If false and coverage is already enabled, skip initialization.
 *                          This allows multiple test files to share the same coverage session.
 * @returns Promise that resolves when coverage collection is started
 *
 * @example
 * // Start coverage for a single test file
 * await coverageModule.startCoverage({ isolate: true });
 *
 * @example
 * // Start coverage in shared mode (won't restart if already enabled)
 * await coverageModule.startCoverage({ isolate: false });
 */
function startCoverage(options: { isolate?: boolean }): Promise<void>;

/**
 * Take a snapshot of current V8 coverage data.
 * Retrieves coverage from the V8 profiler and filters out irrelevant files
 * (non-file URLs, node_modules). Also adds startOffset information for module wrappers.
 *
 * @param options - Configuration options
 * @param options.moduleExecutionInfo - Map of normalized file paths to execution metadata.
 *                                       The startOffset from this map is added to each coverage entry
 *                                       to account for wrapper code added during module execution.
 * @returns Promise resolving to object containing array of script coverage results
 *
 * @example
 * const { result } = await coverageModule.takeCoverage({
 *   moduleExecutionInfo: new Map([
 *     ['/path/to/file.js', { startOffset: 0 }],
 *     ['/path/to/module.js', { startOffset: 42 }]
 *   ])
 * });
 *
 * console.log(result); // Array of ScriptCoverageWithOffset objects
 */
function takeCoverage(options?: {
  moduleExecutionInfo?: Map<string, { startOffset: number }>;
}): Promise<{ result: ScriptCoverageWithOffset[] }>;

{
  result: ScriptCoverageWithOffset[] // Array of coverage entries
}

/**
 * Stop coverage collection and disconnect from V8 Inspector.
 * Stops the profiler and disconnects the inspector session.
 *
 * @param options - Configuration options
 * @param options.isolate - If false, skip stopping. This allows the coverage session
 *                          to remain active for subsequent test files.
 * @returns Promise that resolves when coverage collection is stopped
 *
 * @example
 * // Stop coverage and clean up
 * await coverageModule.stopCoverage({ isolate: true });
 *
 * @example
 * // Keep coverage session active (no-op)
 * await coverageModule.stopCoverage({ isolate: false });
 */
function stopCoverage(options: { isolate?: boolean }): Promise<void>;

/**
 * Factory method to get the V8CoverageProvider instance.
 * The provider is dynamically imported to prevent bundling.
 *
 * @returns Promise resolving to new V8CoverageProvider instance
 *
 * @example
 * const provider = await coverageModule.getProvider();
 * provider.initialize(vitestContext);
 * const coverageMap = await provider.generateCoverage({ allTestsRun: true });
 */
function getProvider(): Promise<V8CoverageProvider>;

interface ScriptCoverageWithOffset extends Profiler.ScriptCoverage {
  /**
   * Offset for wrapper code added during module execution.
   * Module systems (CommonJS, ESM) often wrap module code with additional code.
   * This offset adjusts coverage ranges to account for that wrapper code.
   */
  startOffset: number;
}

interface ScriptCoverage {
  /** Unique script identifier assigned by V8 */
  scriptId: string;

  /** URL of the script (e.g., "file:///path/to/file.js") */
  url: string;

  /** Coverage entries for functions in the script */
  functions: FunctionCoverage[];
}

interface FunctionCoverage {
  /** Name of the function (empty string for anonymous functions) */
  functionName: string;

  /** Coverage ranges within the function showing which parts were executed */
  ranges: Range[];

  /**
   * Indicates whether this is block-level coverage (true) or function-level only (false).
   * When true, ranges contain detailed execution counts for code blocks.
   */
  isBlockCoverage: boolean;
}

interface Range {
  /** Start offset in the script source code (in characters) */
  startOffset: number;

  /** End offset in the script source code (in characters) */
  endOffset: number;

  /** Number of times this range was executed */
  count: number;
}

import coverageModule from '@vitest/coverage-v8';

// 1. Start coverage collection
await coverageModule.startCoverage({ isolate: true });

// 2. Run your test code
// ... test execution happens here ...

// 3. Take coverage snapshot after tests
const { result } = await coverageModule.takeCoverage({
  moduleExecutionInfo: new Map([
    ['/path/to/file.js', { startOffset: 0 }]
  ])
});

console.log(`Collected coverage for ${result.length} files`);

// 4. Stop coverage collection
await coverageModule.stopCoverage({ isolate: true });

// 5. Get provider for processing coverage data
const provider = await coverageModule.getProvider();