Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js test coverage

Measure code coverage with the built-in Node.js test runner: the coverage flags, include and exclude globs, line, branch and function thresholds, and the coverage event.

Code coverage tells you which parts of your source files ran while the tests were running: which lines, which branches of if and ?: expressions, and which functions. The Node.js test runner can collect it with no extra package, using the coverage support built into V8, the JavaScript engine.

Coverage answers one question: "which code did my tests never touch?" It does not tell you whether the code that ran was checked properly. A test without assertions can reach 100% coverage and find nothing. Use the numbers to discover blind spots, and use thresholds to stop coverage from silently shrinking.

NODE
node --test --experimental-test-coverage --test-coverage-lines=80

Try it

Node.js Reading the coverage event

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js A threshold that fails the run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

Command line flags:

NODE
--experimental-test-coverage
--test-coverage-include=<glob>      (repeatable)
--test-coverage-exclude=<glob>      (repeatable)
--test-coverage-lines=<percent>
--test-coverage-branches=<percent>
--test-coverage-functions=<percent>

The same settings in run():

NODE
run({
  files, coverage: true,
  coverageIncludeGlobs: ["src/**"],
  coverageExcludeGlobs: ["**/*.test.js"],
  lineCoverage: 90, branchCoverage: 80, functionCoverage: 90,
});
Option Description
--experimental-test-coverage / coverage: true Turns collection on. Without it nothing is measured.
--test-coverage-include / coverageIncludeGlobs Only files matching these globs are reported.
--test-coverage-exclude / coverageExcludeGlobs Files matching these globs are left out of the report.
--test-coverage-lines / lineCoverage Minimum percentage of covered lines (0 to 100).
--test-coverage-branches / branchCoverage Minimum percentage of covered branches.
--test-coverage-functions / functionCoverage Minimum percentage of covered functions.

The test:coverage event. When coverage is on, the runner emits one test:coverage event at the end. Its data.summary holds files (one entry per source file with path, totalLineCount, coveredLineCount, coveredLinePercent, the same three fields for branches and functions, plus arrays lines, branches and functions with the hit counts), totals, thresholds and workingDirectory.

Errors and edge cases. If a percentage is below its threshold, the runner prints a message such as "85.71% line coverage does not meet threshold of 100%." as a diagnostic and sets the process exit code to 1, even when every test passed. A threshold of 0 (the default) disables the check.

Usage notes

  • By default the report skips files inside node_modules and the test files themselves, so the numbers describe your own code. Add --test-coverage-include to narrow it further.
  • Only files that were loaded are reported by default. A source file that no test imports does not appear at all, which can make coverage look better than it is. Include it with a glob if you want it counted as 0%.
  • Coverage can be combined with any reporter. spec prints a table; lcov writes the lcov format that coverage services read, for example --test-reporter=lcov --test-reporter-destination=lcov.info.
  • Mark a region that cannot be reached on purpose with a comment: /* node:coverage ignore next */ skips the next line, and /* node:coverage disable */ ... /* node:coverage enable */ skips a block.
  • Branch counts follow V8's block coverage, so one if produces more than one branch. Line and branch percentages rarely match exactly.
  • Coverage is marked experimental in the flag name. The numbers are reliable, but option names may still change between releases.
  • Collecting coverage slows tests slightly, because V8 tracks every block it executes.