or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-vitest--coverage-istanbul

Istanbul coverage provider for Vitest that instruments JavaScript and TypeScript code to track code execution during tests

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@vitest/coverage-istanbul@3.2.x

To install, run

npx @tessl/cli install tessl/npm-vitest--coverage-istanbul@3.2.0

@vitest/coverage-istanbul

Istanbul coverage provider for Vitest that instruments JavaScript and TypeScript code to track code execution during tests. This package provides an alternative to Vitest's default V8 coverage provider, offering the mature Istanbul toolchain for comprehensive code coverage analysis.

Package Information

Package Name: @vitest/coverage-istanbul
Package Type: npm
Language: TypeScript
Installation: npm install @vitest/coverage-istanbul

Core Imports

import istanbulProvider from "@vitest/coverage-istanbul";
// istanbulProvider is a CoverageProviderModule with takeCoverage, startCoverage, and getProvider methods

For CommonJS:

const istanbulProvider = require("@vitest/coverage-istanbul");

Note: This package exports a default module implementing the CoverageProviderModule interface, not named exports.

Basic Usage

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul',
      reporter: ['text', 'json', 'html'],
      reportsDirectory: './coverage'
    }
  }
})

Architecture

The package implements Vitest's coverage provider interface through several key components:

Coverage Provider Module: Main export implementing CoverageProviderModule interface
Istanbul Coverage Provider: Core provider class that handles instrumentation and reporting
Instrumentation: Uses Istanbul's instrumenter to add coverage tracking to source code
Coverage Collection: Gathers coverage data during test execution via global storage
Report Generation: Produces coverage reports in multiple formats using Istanbul reporters

Capabilities

Coverage Provider Module

Main export that integrates with Vitest's coverage system.

interface CoverageProviderModule {
  takeCoverage(): CoverageMapData;
  startCoverage(): void;  
  getProvider(): Promise<IstanbulCoverageProvider>;
}

interface CoverageMapData {
  [filename: string]: FileCoverage;
}

interface FileCoverage {
  f: FunctionCoverage;
  s: StatementCoverage;
  b: BranchCoverage;
}

interface FunctionCoverage {
  [key: string]: number;
}

interface StatementCoverage {
  [key: string]: number;
}

interface BranchCoverage {
  [key: string]: number[];
}

The default export provides three core functions:

takeCoverage() - Retrieves coverage data from the global coverage store
startCoverage() - Resets coverage counters to prevent duplicate results between test runs
getProvider() - Returns an instance of the Istanbul coverage provider

Istanbul Coverage Provider

Core coverage provider implementation that handles instrumentation and reporting.

class IstanbulCoverageProvider extends BaseCoverageProvider<ResolvedCoverageOptions<'istanbul'>> implements CoverageProvider {
  name: 'istanbul';
  version: string;
  instrumenter: Instrumenter;
  testExclude: InstanceType<typeof TestExclude>;

  initialize(ctx: Vitest): void;
  onFileTransform(sourceCode: string, id: string, pluginCtx: any): { code: string; map: any } | undefined;
  createCoverageMap(): CoverageMap;
  generateCoverage(reportContext: ReportContext): Promise<CoverageMap>;
  generateReports(coverageMap: CoverageMap, allTestsRun: boolean | undefined): Promise<void>;
  parseConfigModule(configFilePath: string): Promise<ProxifiedModule<any>>;
}

interface ReportContext {
  allTestsRun?: boolean;
}

interface CoverageMap {
  files(): string[];
  merge(other: CoverageMap): void;
  filter(fn: (filename: string) => boolean): void;
  addFileCoverage(coverage: FileCoverage): void;
}

Key methods:

initialize(ctx) - Sets up the provider with Vitest context, configures instrumenter and file exclusion rules
onFileTransform(sourceCode, id, pluginCtx) - Instruments source code during build process for coverage tracking
createCoverageMap() - Creates a new Istanbul coverage map instance
generateCoverage(reportContext) - Collects and processes coverage data from test execution
generateReports(coverageMap, allTestsRun) - Generates coverage reports in configured formats
parseConfigModule(configFilePath) - Parses configuration files using magicast for dynamic config processing

Usage Examples

Basic Configuration

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul',
      reporter: ['text', 'json-summary', 'html'],
      reportsDirectory: './coverage',
      exclude: [
        'node_modules/',
        'src/test-utils/',
        '**/*.{test,spec}.{js,ts}',
      ],
      include: ['src/**/*.{js,ts}'],
      all: true,
      skipFull: false
    }
  }
})

Advanced Configuration

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul',
      reporter: [
        ['text'],
        ['html', { subdir: 'html' }],
        ['json', { file: 'coverage.json' }],
        ['lcov', { file: 'lcov.info' }]
      ],
      reportsDirectory: './coverage',
      watermarks: {
        statements: [80, 95],
        functions: [80, 95],
        branches: [80, 95],
        lines: [80, 95]
      },
      thresholds: {
        statements: 90,
        functions: 90,
        branches: 90,
        lines: 90
      },
      ignoreClassMethods: ['toString', 'toJSON'],
      excludeAfterRemap: true,
      all: true,
      cleanOnRerun: true
    }
  }
})

Using with Custom Reporters

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul',
      reporter: [
        'text-summary',
        ['html', { 
          subdir: 'html-report',
          skipFull: false 
        }],
        ['cobertura', { 
          file: 'cobertura-coverage.xml' 
        }],
        ['teamcity', { 
          file: 'teamcity-coverage.txt' 
        }]
      ]
    }
  }
})

Configuration Types

The Istanbul coverage provider supports specific configuration options through Vitest's coverage configuration.

interface CoverageIstanbulOptions extends BaseCoverageOptions {
  /**
   * Set to array of class method names to ignore for coverage
   *
   * @default []
   */
  ignoreClassMethods?: string[];
}

interface BaseCoverageOptions {
  enabled?: boolean;
  include?: string[];
  extension?: string | string[];
  exclude?: string[];
  all?: boolean;
  clean?: boolean;
  cleanOnRerun?: boolean;
  reportsDirectory?: string;
  reporter?: CoverageReporter[];
  skipFull?: boolean;
  thresholds?: Thresholds;
  watermarks?: {
    statements?: [number, number];
    functions?: [number, number];
    branches?: [number, number];
    lines?: [number, number];
  };
  reportOnFailure?: boolean;
  allowExternal?: boolean;
  excludeAfterRemap?: boolean;
  processingConcurrency?: number;
}

type CoverageReporter = 'text' | 'json' | 'html' | 'lcov' | 'text-summary' | 'json-summary' | 'cobertura' | 'teamcity' | (string & {});

interface Thresholds {
  statements?: number;
  functions?: number;
  branches?: number;
  lines?: number;
}

type ResolvedCoverageOptions<T extends 'istanbul'> = CoverageIstanbulOptions & Required<Pick<CoverageIstanbulOptions, 'enabled' | 'clean' | 'cleanOnRerun' | 'all' | 'skipFull' | 'reportOnFailure' | 'allowExternal' | 'excludeAfterRemap'>>;

Constants

/** Key used to store coverage data in global scope */
const COVERAGE_STORE_KEY: string = '__VITEST_COVERAGE__';

Core Types

interface CoverageProviderModule {
  takeCoverage(): CoverageMapData;
  startCoverage(): void;
  getProvider(): Promise<IstanbulCoverageProvider>;
}

interface CoverageMapData {
  [filename: string]: FileCoverage;
}

interface FileCoverage {
  f: FunctionCoverage;
  s: StatementCoverage;
  b: BranchCoverage;
}

interface FunctionCoverage {
  [key: string]: number;
}

interface StatementCoverage {
  [key: string]: number;
}

interface BranchCoverage {
  [key: string]: number[];
}

interface CoverageMap {
  files(): string[];
  merge(other: CoverageMap): void;
  filter(fn: (filename: string) => boolean): void;
  addFileCoverage(coverage: FileCoverage): void;
}

interface ReportContext {
  allTestsRun?: boolean;
}

interface ProxifiedModule<T> {
  $ast: any;
  $code: string;
  exports: T;
}