Istanbul Coverage Threshold Checker

Common errors

• TypeError: Cannot read properties of undefined (reading 'Collector') or checker.checkFailures is not a function

  cause The `istanbul` or `istanbul-threshold-checker` packages are not installed or are not imported correctly, or their versions are incompatible.
  fix Ensure both `istanbul` (e.g., `npm install istanbul@^0.4.0`) and `istanbul-threshold-checker` (`npm install istanbul-threshold-checker`) are installed. Verify that `require('istanbul')` and `require('istanbul-threshold-checker')` are used, and that the `Collector` and `checkFailures` methods exist on the respective objects for the installed versions.

• Error: Invalid coverage object

  cause The coverage JSON object provided to `istanbul.Collector.add()` or `checker.checkFailures()` is not in the expected format for the `istanbul` version this package depends on.
  fix Consult the `istanbul` documentation for the correct coverage object structure for versions around `0.4.x`. If using a newer coverage report, consider migrating to `nyc` which handles modern report formats and threshold checking natively.

Warnings

• deprecated This package, last updated in 2016, is considered abandoned and its functionality has largely been absorbed into the main `istanbul` project's command-line interface, `nyc`. It is highly recommended to use `nyc`'s built-in threshold checking instead.
  Fix: Migrate to `nyc` for coverage reporting and threshold checks. See `nyc` documentation for `check-coverage` command and configuration options.
• gotcha The package relies on an older version of `istanbul`. Using it with modern versions of `istanbul` (via `nyc`) or coverage reports generated by other tools (like Jest) might lead to compatibility issues or incorrect results due to changes in coverage report formats.
  Fix: If direct integration with `istanbul-threshold-checker` is unavoidable, ensure your `istanbul` dependency is pinned to a version compatible with this package (e.g., `^0.4.0`). Otherwise, migrate to `nyc`'s native threshold features.
• gotcha This package is strictly CommonJS and does not support ES Modules (`import`/`export`). Attempting to import it using ESM syntax will result in errors.
  Fix: Always use `const checker = require('istanbul-threshold-checker');` when importing this module in a CommonJS environment.

Install

• npm install istanbul-threshold-checker npm
• yarn add istanbul-threshold-checker yarn
• pnpm add istanbul-threshold-checker pnpm

Imports

• checker
  wrong:

  import checker from 'istanbul-threshold-checker';

  correct:

  const checker = require('istanbul-threshold-checker');

  This package uses CommonJS `require` syntax exclusively. ESM `import` is not supported.
• Collector
  wrong:

  import { Collector } from 'istanbul';

  correct:

  const istanbul = require('istanbul');
  const Collector = istanbul.Collector;

  Relies on the CommonJS `istanbul` package (older version) for coverage report collection.

Quickstart

Demonstrates how to manually collect a coverage report using `istanbul` and then use `istanbul-threshold-checker` to validate it against defined global and per-file thresholds.

/* package.json (excerpt) */
// {
//   "dependencies": {
//     "istanbul": "^0.4.0", // Use a compatible istanbul version
//     "istanbul-threshold-checker": "^0.2.0"
//   }
// }

const istanbul = require('istanbul');
const checker = require('istanbul-threshold-checker');

// Mock a coverage JSON object (replace with actual report)
const coverageJsonObject = {
  '/path/to/my-file.js': {
    path: '/path/to/my-file.js',
    s: { '1': 1, '2': 1, '3': 0 }, // Statements
    b: { '1': [1, 0] },         // Branches
    f: { '1': 1 },             // Functions
    l: { '1': 1, '2': 1, '3': 0 }  // Lines
  }
};

const collector = new istanbul.Collector();
collector.add(coverageJsonObject);
const coverage = collector.getFinalCoverage();

const thresholds = {
  global: {
    statements: 50,
    branches: 50,
    lines: 50,
    functions: 50
  },
  each: {
    statements: 0, // 0% means any file with less than 0% statements coverage fails (always passes if some coverage exists)
    branches: -5,  // No more than 5 uncovered branches per file
    lines: 70,
    functions: 100
  }
};

const results = checker.checkFailures(thresholds, coverage);

if (results.some(r => r.global?.failed || r.each?.failed)) {
  console.error('Coverage thresholds failed:');
  console.error(JSON.stringify(results, null, 2));
  // process.exit(1);
} else {
  console.log('Coverage thresholds passed!');
  console.log(JSON.stringify(results, null, 2));
}

/* Example of 'results' output:
[
  {
    "type": "statements",
    "global": {
      "failed": false,
      "value": 66.66666666666667
    },
    "each": {
      "failed": true,
      "failures": [
        "/path/to/my-file.js"
      ]
    }
  },
  {
    "type": "branches",
    "global": {
      "failed": true,
      "value": 50
    },
    "each": {
      "failed": false
    }
  },
  {
    "type": "functions",
    "global": {
      "failed": false,
      "value": 100
    },
    "each": {
      "failed": false
    }
  },
  {
    "type": "lines",
    "global": {
      "failed": false,
      "value": 66.66666666666667
    },
    "each": {
      "failed": true,
      "failures": [
        "/path/to/my-file.js"
      ]
    }
  }
]
*/