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 --test --experimental-test-coverage --test-coverage-lines=80
Try it
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.
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:
--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():
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_modulesand the test files themselves, so the numbers describe your own code. Add--test-coverage-includeto 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.
specprints a table;lcovwrites thelcovformat 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
ifproduces 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.