@vitest/coverage-v8

@vitest/coverage-v8 is a V8-based code coverage provider for the Vitest testing framework. It enables high-performance coverage collection using Chrome's V8 JavaScript engine native profiler capabilities, without requiring source code instrumentation. The provider collects coverage data directly from V8's runtime profiler and converts it to Istanbul format for comprehensive reporting.

Package Information

• Package Name: @vitest/coverage-v8
• Package Type: npm
• Language: TypeScript
• Installation: npm install -D @vitest/coverage-v8 or pnpm add -D @vitest/coverage-v8
• Peer Dependencies: vitest (required), @vitest/browser (optional, for browser mode)

Core Imports

Important: This package is typically not imported directly in user code. Instead, it's configured in your Vitest configuration file and loaded automatically by Vitest.

The package provides two main entry points for different environments (used internally by Vitest):

Node.js environment (internal):

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

Browser environment (internal):

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

These modules are loaded automatically by Vitest based on your configuration - you don't need to import them manually.

Basic Usage

Configure in your Vitest configuration file:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      enabled: true,
      reporter: ['text', 'json', 'html'],
      include: ['src/**/*.ts'],
      exclude: ['node_modules/', 'test/'],
    },
  },
});

Run tests with coverage:

vitest run --coverage

Architecture

The @vitest/coverage-v8 package is structured around several key components:

• Coverage Provider Module: Implements the CoverageProviderModule interface from Vitest, providing lifecycle methods for coverage collection in both Node.js and browser environments
• V8CoverageProvider Class: Core provider implementation that manages the entire coverage workflow including collection, conversion, source mapping, and reporting
• V8 Profiler Integration: Direct integration with V8's native profiler via Node.js Inspector API (Node.js) or Chrome DevTools Protocol (browsers)
• Coverage Conversion Pipeline: Converts raw V8 coverage data to Istanbul format using AST-based remapping for accurate source map handling
• Multi-Environment Support: Separate implementations for Node.js and browser environments with appropriate platform-specific APIs

The coverage collection workflow:

1. Initialization: Provider is initialized with Vitest context and configuration
2. Collection Start: V8 profiler is enabled before test execution
3. Runtime Collection: V8 tracks execution counts natively without instrumentation
4. Coverage Snapshot: After each test file, coverage data is captured from V8
5. Conversion: Raw V8 coverage is converted to Istanbul format with AST-based remapping
6. Source Mapping: Coverage is remapped to original source files via source maps
7. Report Generation: Istanbul reporters generate coverage reports in configured formats

Capabilities

Coverage Provider Module (Node.js)

Coverage provider module implementation for Node.js environments that manages the V8 profiler lifecycle and coverage data collection using the Node.js Inspector API.

interface CoverageProviderModule {
  startCoverage(options: { isolate?: boolean }): Promise<void>;
  takeCoverage(options?: {
    moduleExecutionInfo?: Map<string, { startOffset: number }>;
  }): Promise<{ result: ScriptCoverageWithOffset[] }>;
  stopCoverage(options: { isolate?: boolean }): Promise<void>;
  getProvider(): Promise<V8CoverageProvider>;
}

Coverage Provider Module (Node.js)

Coverage Provider Module (Browser)

Coverage provider module implementation for browser environments that manages the V8 profiler lifecycle using Chrome DevTools Protocol for browser-based testing.

interface CoverageProviderModule {
  startCoverage(): Promise<void>;
  takeCoverage(): Promise<{ result: any[] }>;
  stopCoverage(): void;
  getProvider(): Promise<V8CoverageProvider>;
}

Coverage Provider Module (Browser)

V8 Coverage Provider

The main coverage provider class that implements the complete coverage workflow including data collection, conversion to Istanbul format, source map handling, and report generation.

class V8CoverageProvider extends BaseCoverageProvider<ResolvedCoverageOptions<'v8'>> {
  name: 'v8';
  version: string;

  initialize(ctx: Vitest): void;
  createCoverageMap(): CoverageMap;
  generateCoverage(options: ReportContext): Promise<CoverageMap>;
  generateReports(coverageMap: CoverageMap, allTestsRun?: boolean): Promise<void>;
  parseConfigModule(configFilePath: string): Promise<ProxifiedModule<any>>;
}

interface ReportContext {
  allTestsRun?: boolean;
}

V8 Coverage Provider

Types

ScriptCoverageWithOffset

Extended script coverage type that includes offset information for module wrapper code.

interface ScriptCoverageWithOffset extends Profiler.ScriptCoverage {
  /**
   * Offset for wrapper code added during module execution.
   * Used to adjust coverage ranges to account for code added by the module system.
   */
  startOffset: number;
}

Profiler.ScriptCoverage

V8 script coverage data from the Node.js inspector API:

interface ScriptCoverage {
  /** Unique script identifier */
  scriptId: string;
  /** URL of the script */
  url: string;
  /** Coverage entries for functions in the script */
  functions: FunctionCoverage[];
}

interface FunctionCoverage {
  /** Name of the function */
  functionName: string;
  /** Coverage ranges within the function */
  ranges: Range[];
  /** Indicates whether this function was executed at least once */
  isBlockCoverage: boolean;
}

interface Range {
  /** Start offset in the script */
  startOffset: number;
  /** End offset in the script */
  endOffset: number;
  /** Execution count for this range */
  count: number;
}

CoverageMap

Istanbul coverage map type from istanbul-lib-coverage:

interface CoverageMap {
  /** Get list of covered file paths */
  files(): string[];
  /** Get coverage data for a specific file */
  fileCoverageFor(filename: string): FileCoverage;
  /** Merge another coverage map into this one */
  merge(other: CoverageMap): void;
  /** Filter coverage map based on predicate */
  filter(predicate: (filename: string) => boolean): void;
}

Platform Support

• Node.js: Requires Node.js environment with V8 engine and Inspector API support
• Browser: Requires Chrome or Chromium-based browser with DevTools Protocol support
• V8 Requirement: Only works in environments using V8 JavaScript engine (Node.js, Chrome, Chromium, Electron, Deno)
• Not Supported: Non-V8 browsers (Firefox, Safari), Bun, Cloudflare Workers

Configuration Options

The provider inherits all configuration options from Vitest's coverage configuration (ResolvedCoverageOptions<'v8'>):

• enabled: Enable/disable coverage collection
• include: Glob patterns for files to include in coverage
• exclude: Glob patterns for files to exclude from coverage
• reporter: Array of Istanbul reporter names/configurations
• reportsDirectory: Directory for coverage reports (default: ./coverage)
• clean: Clean coverage results before running tests
• cleanOnRerun: Clean coverage on watch mode reruns
• thresholds: Coverage threshold requirements
• skipFull: Skip files with 100% coverage in reports
• processingConcurrency: Concurrency limit for coverage processing
• ignoreClassMethods: Class method names to ignore for coverage
• excludeAfterRemap: Apply exclusions after source map remapping

Features

1. Zero Instrumentation: Collects coverage directly from V8 without modifying source code
2. AST-Based Remapping: Accurate coverage remapping using AST analysis with ast-v8-to-istanbul
3. Source Map Support: Full source map support via istanbul-lib-source-maps
4. Multi-Project Support: Handles Vitest multi-project workspaces
5. Untested File Tracking: Can include files not executed during tests
6. Vite Integration: Seamless integration with Vite's transformation pipeline
7. Istanbul Format: Converts to Istanbul format for compatibility with standard coverage tools
8. Concurrent Processing: Processes coverage files concurrently for better performance
9. Threshold Checking: Built-in coverage threshold validation
10. Multiple Reporters: Supports all Istanbul reporters (text, html, json, lcov, etc.)