or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lcov-parse

Parse LCOV results files and return JSON formatted coverage data

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lcov-parse@1.0.x

To install, run

npx @tessl/cli install tessl/npm-lcov-parse@1.0.0

index.mddocs/

LCOV Parse

LCOV Parse is a simple and effective LCOV file parser that converts code coverage data from the LCOV format into structured JSON output. It supports parsing both LCOV files from disk and LCOV data strings directly, making it versatile for different integration scenarios.

Package Information

  • Package Name: lcov-parse
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lcov-parse

Core Imports

const parse = require('lcov-parse');

ES6 import:

import parse from 'lcov-parse';

Basic Usage

const parse = require('lcov-parse');

// Parse an LCOV file from disk
parse('./path/to/file.info', function(err, data) {
    if (err) {
        console.error('Parse error:', err);
        return;
    }
    console.log('Coverage data:', data);
});

// Parse LCOV string data directly
const lcovString = `TN:Test #1
SF:src/example.js
FN:1,myFunction
FNDA:5,myFunction
FNF:1
FNH:1
DA:1,5
DA:2,3
LF:2
LH:2
end_of_record`;

parse(lcovString, function(err, data) {
    if (err) {
        console.error('Parse error:', err);
        return;
    }
    console.log('Parsed coverage:', data);
});

CLI Usage

The package includes a command-line interface for parsing LCOV files:

# Parse a file and output JSON
lcov-parse ./lcov.info

# Use with pipes
cat lcov.info | xargs -0 lcov-parse

Capabilities

Main Parse Function

The primary parsing function that handles both file paths and LCOV string data.

/**
 * Parse LCOV coverage data from file or string
 * @param {string} file - Either a file path to an LCOV file or raw LCOV data string
 * @param {function} callback - Error-first callback function (err, data) => void
 */
function parse(file, callback);

Parameters:

  • file (string): File path to LCOV file or raw LCOV string data
  • callback (function): Error-first callback with signature (err, data) => void

Behavior:

  • If file parameter is a valid file path, reads and parses the file
  • If file parameter is not a valid file path, treats it as raw LCOV string data
  • Calls callback with parsed JSON data array on success
  • Calls callback with error string on failure

Source String Parser

Direct string parsing function for raw LCOV data.

/**
 * Parse raw LCOV string data directly
 * @param {string} str - Raw LCOV data string
 * @param {function} callback - Error-first callback function (err, data) => void
 */
parse.source(str, callback);

Parameters:

  • str (string): Raw LCOV format string
  • callback (function): Error-first callback with signature (err, data) => void

Behavior:

  • Parses LCOV format string without file system operations
  • Supports all standard LCOV record types
  • Returns array of coverage objects for each file

CLI Command

Command-line interface for parsing LCOV files.

lcov-parse <file>

Parameters:

  • file (string): Path to LCOV file

Output:

  • JSON string printed to stdout
  • Error messages printed to stderr

Data Structure

The parser returns an array of coverage objects, one for each source file found in the LCOV data. Each coverage object has the following structure:

/**
 * Coverage data structure returned by the parser
 */
interface CoverageData {
  title: string;        // Test name (from TN record)
  file: string;         // Source file path (from SF record)
  functions: {
    found: number;      // Total functions found (from FNF record)
    hit: number;        // Functions with coverage (from FNH record)
    details: Array<{    // Function details array
      name: string;     // Function name (from FN record)
      line: number;     // Line number (from FN record)  
      hit: number;      // Hit count (from FNDA record)
    }>;
  };
  lines: {
    found: number;      // Total lines found (from LF record)
    hit: number;        // Lines with coverage (from LH record)
    details: Array<{    // Line details array
      line: number;     // Line number (from DA record)
      hit: number;      // Hit count (from DA record)
    }>;
  };
  branches: {
    found: number;      // Total branches found (from BRF record)
    hit: number;        // Branches with coverage (from BRH record)
    details: Array<{    // Branch details array
      line: number;     // Line number (from BRDA record)
      block: number;    // Block number (from BRDA record)
      branch: number;   // Branch number (from BRDA record)
      taken: number;    // Times taken (from BRDA record, 0 if '-')
    }>;
  };
}

Example Output

[
  {
    "title": "Test #1",
    "file": "src/example.js",
    "functions": {
      "hit": 23,
      "found": 29,
      "details": [
        {
          "name": "myFunction",
          "line": 7,
          "hit": 6
        },
        {
          "name": "anotherFunction", 
          "line": 25,
          "hit": 3
        }
      ]
    },
    "lines": {
      "found": 181,
      "hit": 143,
      "details": [
        {
          "line": 7,
          "hit": 6
        },
        {
          "line": 29,
          "hit": 6
        }
      ]
    },
    "branches": {
      "found": 12,
      "hit": 10,
      "details": [
        {
          "line": 15,
          "block": 0,
          "branch": 0,
          "taken": 5
        }
      ]
    }
  }
]

LCOV Format Support

The parser supports all standard LCOV record types:

  • TN: Test name
  • SF: Source file path
  • FN: Function name and line number
  • FNDA: Function execution count
  • FNF: Functions found
  • FNH: Functions hit
  • DA: Line execution count
  • LF: Lines found
  • LH: Lines hit
  • BRDA: Branch coverage data
  • BRF: Branches found
  • BRH: Branches hit
  • end_of_record: Record separator

Error Handling

The parser handles several error conditions:

  • File not found: If the first parameter is not a valid file path, it's treated as string data
  • Parse failure: Returns error string "Failed to parse string" via callback if parsing fails
  • Invalid data: May result in incomplete or malformed output objects with default values

Example error handling:

parse('./nonexistent.info', function(err, data) {
    if (err) {
        console.error('Error:', err);
        // Handle error - could be parse failure or invalid data
        return;
    }
    // Process successful data
    console.log('Coverage reports:', data.length);
});

Dependencies

  • Built-in modules: fs, path (Node.js standard library)
  • No external runtime dependencies

Use Cases

  • CI/CD Pipelines: Parse coverage reports in continuous integration workflows
  • Development Tools: Integrate coverage data into development environments
  • Coverage Analysis: Convert LCOV data for further processing and analysis
  • Reporting Systems: Transform coverage data for custom reporting formats
  • Test Automation: Process coverage results in automated testing workflows