or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

coverage-maps.mdcoverage-summaries.mdfile-coverage.mdindex.md
tile.json

tessl/npm-istanbul-lib-coverage

Data library for istanbul coverage objects providing read-only API with merge and summarize capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/istanbul-lib-coverage@3.2.x

To install, run

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

index.mddocs/

Istanbul Lib Coverage

Istanbul Lib Coverage is a data library for Istanbul coverage objects providing a read-only API with the ability to merge and summarize coverage information. It supersedes object-utils and collector from the v0 Istanbul API and serves as a foundational component for code coverage analysis and reporting.

Package Information

  • Package Name: istanbul-lib-coverage
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install istanbul-lib-coverage

Core Imports

const { 
  createCoverageMap, 
  createFileCoverage, 
  createCoverageSummary 
} = require('istanbul-lib-coverage');

For ES modules:

import { 
  createCoverageMap, 
  createFileCoverage, 
  createCoverageSummary 
} from 'istanbul-lib-coverage';

Basic Usage

const libCoverage = require('istanbul-lib-coverage');

// Create a coverage map from global coverage data
const map = libCoverage.createCoverageMap(globalCoverageVar);

// Create a summary to aggregate coverage statistics
const summary = libCoverage.createCoverageSummary();

// Merge another coverage map
map.merge(otherCoverageMap);

// Process all files and aggregate summaries
map.files().forEach(function(f) {
    const fc = map.fileCoverageFor(f);
    const s = fc.toSummary();
    summary.merge(s);
});

console.log('Global summary', summary);

Architecture

Istanbul Lib Coverage is built around three core components:

  • Coverage Maps: Collections of file coverage objects keyed by file path, providing operations for merging and filtering coverage data across multiple files
  • File Coverage: Individual file coverage objects containing statement, function, and branch coverage data with methods for analysis and merging
  • Coverage Summaries: Aggregated coverage statistics with totals, covered counts, and percentages for lines, statements, functions, and branches

Capabilities

Factory Functions

Core factory functions for creating coverage objects with validation and type coercion.

/**
 * Creates a coverage summary object
 * @param {Object} [obj] - Optional coverage summary data
 * @returns {CoverageSummary}
 */
function createCoverageSummary(obj);

/**
 * Creates a CoverageMap object
 * @param {Object} [obj] - Optional coverage map data
 * @returns {CoverageMap}
 */
function createCoverageMap(obj);

/**
 * Creates a FileCoverage object  
 * @param {Object|String} [obj] - File path or coverage data
 * @returns {FileCoverage}
 */
function createFileCoverage(obj);

Classes Export

Access to the underlying classes for advanced usage scenarios.

/**
 * Classes exported for reuse
 */
const classes = {
  FileCoverage: FileCoverage  // The FileCoverage constructor class
};

Usage Examples:

const { classes } = require('istanbul-lib-coverage');

// Direct instantiation using the class constructor
const fileCoverage = new classes.FileCoverage('/src/file.js');

// Access class for type checking
if (coverageObj instanceof classes.FileCoverage) {
  console.log('This is a FileCoverage instance');
}

Coverage Maps

Map-like collections of file coverage objects with merging, filtering, and analysis capabilities.

class CoverageMap {
  constructor(obj);
  merge(obj): void;
  filter(callback): void;
  files(): string[];
  fileCoverageFor(file): FileCoverage;
  addFileCoverage(fc): void;
  getCoverageSummary(): CoverageSummary;
  toJSON(): Object;
}

Coverage Maps

File Coverage

Individual file coverage objects with detailed coverage analysis and merging capabilities.

class FileCoverage {
  constructor(pathOrObj, reportLogic);
  getLineCoverage(): Object;
  getUncoveredLines(): string[];
  getBranchCoverageByLine(): Object;
  merge(other): void;
  resetHits(): void;
  toSummary(): CoverageSummary;
  toJSON(): Object;
}

File Coverage

Coverage Summaries

Aggregated coverage statistics with merging capabilities for comprehensive reporting.

class CoverageSummary {
  constructor(obj);
  merge(obj): CoverageSummary;
  isEmpty(): boolean;
  toJSON(): Object;
}

Coverage Summaries

Types

// Coverage data structure for individual files
interface FileCoverageData {
  path: string;                    // File path
  statementMap: Object;            // Statement location mapping
  fnMap: Object;                   // Function metadata mapping  
  branchMap: Object;               // Branch metadata mapping
  s: Object;                       // Statement hit counts
  f: Object;                       // Function hit counts
  b: Object;                       // Branch hit counts
  bT?: Object;                     // Branch truthiness (optional)
}

// Coverage summary statistics
interface CoverageStats {
  total: number;                   // Total count
  covered: number;                 // Covered count
  skipped: number;                 // Skipped count
  pct: number | string;            // Coverage percentage
}

// Complete coverage summary
interface CoverageSummaryData {
  lines: CoverageStats;            // Line coverage
  statements: CoverageStats;       // Statement coverage
  functions: CoverageStats;        // Function coverage
  branches: CoverageStats;         // Branch coverage
  branchesTrue?: CoverageStats;    // Branch truthiness (optional)
}