coverage-node

A simple CLI to run Node.js and report code coverage.

• ✨ Zero config.
• 🏁 ~308 SLOC, written from scratch to use code coverage features built into Node.js v10+.
• 📦 < 400 kB install size, compared to 2.2 MB for c8 v7.7.1 or 8.84 MB for nyc v15.1.0.
• 🖱 Displays ignored or uncovered source code ranges as paths, clickable in IDEs such as VS Code.

Setup

To install with npm, run:

npm install coverage-node --save-dev

In a package.json script, replace the node command with coverage-node:

 {
   "scripts": {
-    "test": "node test.mjs"
+    "test": "coverage-node test.mjs"
   }
 }

Support

• Linux, macOS.
• Node.js ^12.20 || >= 14.13, but for Node.js versions < v13.3 that produce unreliable coverage data the command coverage-node skips code coverage and logs a warning.

Ignored files

Code coverage analysis ignores:

• node_modules directory files, e.g. node_modules/foo/index.mjs.
• test directory files, e.g. test/index.mjs.
• Files with .test prefixed before the extension, e.g. foo.test.mjs.
• Files named test (regardless of extension), e.g. test.mjs.

Ignored lines

In source code, a comment (case insensitive) can be used to ignore code coverage ranges that start on the the next line:

// coverage ignore next line
if (false) console.log('Never runs.');

CLI

Command coverage-node

Substitutes the normal node command; any node CLI options can be used to run a test script. If the script doesn’t error a code coverage analysis is reported to the console, and if coverage is incomplete the exit code is 1.

Examples

Using npx.

npx can be used to quickly check code coverage for a script:

npx coverage-node test.mjs

Using a package.json script.

{
  "scripts": {
    "test": "coverage-node test.mjs"
  }
}

API

Table of contents

• function analyseCoverage
• function reportCoverage
• constant coverageSupported
• constant coverageSupportedMinNodeVersion
• type CoverageAnalysis
• type SemanticVersion
• type SourceCodeLocation
• type SourceCodeRange
• type SourceCodeRanges

function analyseCoverage

Analyzes Node.js generated V8 JavaScript code coverage data in a directory; useful for reporting.

Returns: Promise<CoverageAnalysis> — Resolves the coverage analysis.

Examples

Ways to import.

import { analyseCoverage } from 'coverage-node';

import analyseCoverage from 'coverage-node/public/analyseCoverage.mjs';

function reportCoverage

Reports a code coverage analysis to the console.

Examples

Ways to import.

import { reportCoverage } from 'coverage-node';

import reportCoverage from 'coverage-node/public/reportCoverage.mjs';

constant coverageSupported

Is the process Node.js version greater at least the minimum required to support code coverage.

Type: boolean

Examples

Ways to import.

import { coverageSupported } from 'coverage-node';

import coverageSupported from 'coverage-node/public/coverageSupported.mjs';

constant coverageSupportedMinNodeVersion

Minimum Node.js version supported for code coverage. Although Node.js v10+ supports coverage, only v13.3+ produces coverage data reliable enough to use.

Type: SemanticVersion

Examples

Ways to import.

import { coverageSupportedMinNodeVersion } from 'coverage-node';

import coverageSupportedMinNodeVersion from 'coverage-node/public/coverageSupportedMinNodeVersion.mjs';

type CoverageAnalysis

Node.js generated V8 JavaScript code coverage data analysis; useful for reporting.

Type: object

type SemanticVersion

A semantic version.

Type: object

type SourceCodeLocation

Source code location.

Type: object

type SourceCodeRange

Source code range details.

Type: object

type SourceCodeRanges

A source code file with ranges of interest.

Type: object