tessl/npm-istanbul-lib-coverage

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Coverage Summaries

Name: tessl/npm-istanbul-lib-coverage
Author: tessl

Coverage summaries provide aggregated coverage statistics with totals, covered counts, and percentages for lines, statements, functions, and branches.

Capabilities

CoverageSummary Constructor

Creates a coverage summary object from existing data or creates an empty summary.

/**
 * Creates a CoverageSummary instance
 * @param {Object|CoverageSummary} [obj] - Summary data or existing CoverageSummary
 */
constructor(obj)

Usage Examples:

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

// Create empty coverage summary
const summary = createCoverageSummary();

// Create from existing summary data
const summary = createCoverageSummary(existingSummaryData);

// Create from another CoverageSummary
const summary = createCoverageSummary(existingSummary);

Merge Coverage Summaries

Merges another coverage summary into this one, combining all statistics.

/**
 * Merges another coverage summary into this one
 * @param {CoverageSummary} obj - Summary to merge
 * @returns {CoverageSummary} This summary (for chaining)
 */
merge(obj): CoverageSummary

Usage Examples:

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

const totalSummary = createCoverageSummary();
const fileSummary1 = createCoverageSummary(file1Summary);
const fileSummary2 = createCoverageSummary(file2Summary);

// Merge multiple summaries
totalSummary.merge(fileSummary1).merge(fileSummary2);

console.log('Combined coverage:', totalSummary);

Check If Empty

Returns true if the summary represents zero lines of code.

/**
 * Returns true if summary has no lines of code
 * @returns {boolean} True if no lines of code
 */
isEmpty(): boolean

Usage Examples:

const summary = createCoverageSummary();

if (summary.isEmpty()) {
  console.log('No coverage data available');
} else {
  console.log('Coverage data present');
}

JSON Serialization

Returns a JSON-serializable representation of the coverage summary.

/**
 * Returns JSON-serializable POJO
 * @returns {Object} Raw summary data
 */
toJSON(): Object

Usage Examples:

const summary = createCoverageSummary(summaryData);
const jsonData = summary.toJSON();

// Save summary to file
const fs = require('fs');
fs.writeFileSync('coverage-summary.json', JSON.stringify(jsonData, null, 2));

// Send in API response
response.json(jsonData);

Data Properties

Coverage summary objects expose statistics through getter properties:

// Coverage statistics for each metric
lines: CoverageStats             // Line coverage statistics
statements: CoverageStats        // Statement coverage statistics  
functions: CoverageStats         // Function coverage statistics
branches: CoverageStats          // Branch coverage statistics
branchesTrue: CoverageStats      // Branch truthiness statistics (optional)

Usage Examples:

const summary = createCoverageSummary(summaryData);

console.log('Coverage Statistics:');
console.log(`Lines: ${summary.lines.covered}/${summary.lines.total} (${summary.lines.pct}%)`);
console.log(`Statements: ${summary.statements.covered}/${summary.statements.total} (${summary.statements.pct}%)`);
console.log(`Functions: ${summary.functions.covered}/${summary.functions.total} (${summary.functions.pct}%)`);
console.log(`Branches: ${summary.branches.covered}/${summary.branches.total} (${summary.branches.pct}%)`);

// Check for branch truthiness data
if (summary.branchesTrue && summary.branchesTrue.total > 0) {
  console.log(`Branch Truthiness: ${summary.branchesTrue.covered}/${summary.branchesTrue.total} (${summary.branchesTrue.pct}%)`);
}

Coverage Statistics Structure

Each coverage metric (lines, statements, functions, branches) follows this structure:

interface CoverageStats {
  total: number;                 // Total count of items
  covered: number;               // Count of covered items
  skipped: number;               // Count of skipped items
  pct: number | 'Unknown';       // Coverage percentage (0-100) or 'Unknown'
}

Summary Data Structure

The complete coverage summary data structure:

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

Example Summary Object:

{
  lines: { total: 100, covered: 85, skipped: 0, pct: 85.0 },
  statements: { total: 150, covered: 120, skipped: 0, pct: 80.0 },
  functions: { total: 25, covered: 20, skipped: 0, pct: 80.0 },
  branches: { total: 50, covered: 30, skipped: 0, pct: 60.0 },
  branchesTrue: { total: 50, covered: 25, skipped: 0, pct: 50.0 }
}

Common Usage Patterns

Aggregating File Summaries

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

// Aggregate coverage from multiple files
const totalSummary = createCoverageSummary();

fileCoverageObjects.forEach(fc => {
  const fileSummary = fc.toSummary();
  totalSummary.merge(fileSummary);
});

console.log('Total project coverage:', totalSummary);

Coverage Reporting

function generateCoverageReport(summary) {
  const metrics = ['lines', 'statements', 'functions', 'branches'];
  
  console.log('Coverage Report:');
  console.log('================');
  
  metrics.forEach(metric => {
    const stats = summary[metric];
    const status = stats.pct >= 80 ? '✓' : '✗';
    console.log(`${status} ${metric}: ${stats.covered}/${stats.total} (${stats.pct}%)`);
  });
}

Threshold Checking

function checkCoverageThresholds(summary, thresholds = { lines: 80, statements: 80, functions: 80, branches: 80 }) {
  const results = {};
  
  Object.entries(thresholds).forEach(([metric, threshold]) => {
    const actual = summary[metric].pct;
    results[metric] = {
      actual,
      threshold,
      passed: typeof actual === 'number' && actual >= threshold
    };
  });
  
  return results;
}