or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

babel-integration.mdcoverage-reading.mdindex.mdinstrumentation.md
tile.json

tessl/npm-istanbul-lib-instrument

Core istanbul API for JS code coverage instrumentation and analysis

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

To install, run

npx @tessl/cli install tessl/npm-istanbul-lib-instrument@6.0.0

index.mddocs/

Istanbul Lib Instrument

Istanbul Lib Instrument is the core Istanbul API for JavaScript code coverage instrumentation. It transforms JavaScript code by adding coverage tracking capabilities using Babel AST transformations, enabling comprehensive line, branch, and function coverage analysis for testing frameworks.

Package Information

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

Core Imports

const { createInstrumenter, programVisitor, readInitialCoverage, defaultOpts } = require("istanbul-lib-instrument");

For ES modules:

import { createInstrumenter, programVisitor, readInitialCoverage, defaultOpts } from "istanbul-lib-instrument";

Basic Usage

const { createInstrumenter } = require("istanbul-lib-instrument");

// Create an instrumenter with default options
const instrumenter = createInstrumenter();

// Instrument JavaScript code
const code = 'function add(a, b) { return a + b; }';
const instrumentedCode = instrumenter.instrumentSync(code, 'math.js');

// Get coverage data for the last instrumented file
const coverage = instrumenter.lastFileCoverage();
console.log(coverage);

Architecture

Istanbul Lib Instrument provides two primary instrumentation approaches:

  • Legacy API: Direct instrumenter usage with createInstrumenter() and Instrumenter class for standalone instrumentation
  • Babel Plugin Integration: programVisitor function for direct integration with Babel plugins like babel-plugin-istanbul
  • Coverage Reading: readInitialCoverage utility for extracting existing coverage data from already instrumented code
  • AST Processing: Deep integration with Babel's AST manipulation for precise code transformation
  • Source Map Support: Full source map preservation and generation for debugging instrumented code

Capabilities

Code Instrumentation

Primary instrumenter functionality for transforming JavaScript code with coverage tracking. Supports both synchronous and callback-style instrumentation with extensive configuration options.

function createInstrumenter(opts?: InstrumenterOptions): Instrumenter;

interface InstrumenterOptions {
  coverageVariable?: string;
  reportLogic?: boolean;
  preserveComments?: boolean;
  compact?: boolean;
  esModules?: boolean;
  autoWrap?: boolean;
  produceSourceMap?: boolean;
  ignoreClassMethods?: string[];
  sourceMapUrlCallback?: (filename: string, url: string) => void;
  debug?: boolean;
  parserPlugins?: string[];
  coverageGlobalScope?: string;
  coverageGlobalScopeFunc?: boolean;
  generatorOpts?: object;
}

class Instrumenter {
  instrumentSync(code: string, filename: string, inputSourceMap?: object): string;
  instrument(code: string, filename: string, callback: (err: Error | null, result: string) => void, inputSourceMap?: object): void;
  lastFileCoverage(): object;
  lastSourceMap(): object | null;
}

Instrumentation

Babel Plugin Integration

Programmatic visitor function for integrating coverage instrumentation directly into Babel transformation pipelines. Used by babel-plugin-istanbul and other Babel-based tools.

function programVisitor(
  types: object,
  sourceFilePath?: string,
  opts?: ProgramVisitorOptions
): ProgramVisitorResult;

interface ProgramVisitorOptions {
  coverageVariable?: string;
  reportLogic?: boolean;
  coverageGlobalScope?: string;
  coverageGlobalScopeFunc?: boolean;
  ignoreClassMethods?: string[];
  inputSourceMap?: object;
}

interface ProgramVisitorResult {
  enter(path: object): void;
  exit(path: object): { fileCoverage: object; sourceMappingURL?: string };
}

Babel Integration

Coverage Data Reading

Utility for extracting existing coverage data from already instrumented JavaScript code, enabling coverage analysis of pre-instrumented files.

function readInitialCoverage(code: string | object): CoverageData | null;

interface CoverageData {
  path: string;
  hash: string;
  gcv: string;
  coverageData: object;
}

Coverage Reading

Types

// Default instrumenter options from @istanbuljs/schema
const defaultOpts: InstrumenterOptions;

// Coverage variable scope types
type CoverageScope = "this" | "global" | "window" | string;

// Parser plugin names for Babel
type ParserPlugin = string;

// Source map callback function type
type SourceMapCallback = (filename: string, url: string) => void;