How do you make Node 24's built-in test runner fail a CI build when line coverage drops, and what can its coverage report miss?
answer
- an experimental flag turns it on
- per-metric thresholds set exit code 1
- include and exclude globs
- lcov needs a second reporter
- unloaded files never appear
basics
~20 sRun node --test with --experimental-test-coverage and a threshold such as --test-coverage-lines=80, which exits with code 1 below the bar; the V8-based report omits files no test loads and, by default, test files, node_modules and core modules.
solid answer
~40 sCoverage in Node 24 is still experimental: `--experimental-test-coverage` collects V8 coverage while the tests run and prints a table through the `spec` or `tap` reporter. The gate is `--test-coverage-lines=<percent>`, with `--test-coverage-branches` and `--test-coverage-functions` beside it; a miss sets exit code 1. `--test-coverage-include` and `--test-coverage-exclude` filter files by glob, and passing any exclude replaces the default that leaves test files out. For CI tooling, add `--test-reporter=lcov` with its own `--test-reporter-destination`, paired with a human reporter. The blind spots: files that no test loads produce no V8 data, so they are absent rather than shown at 0%, no report is produced when no tests run, and `/* node:coverage disable */` or `ignore next` comments remove lines from the count.
code
bash · 5 linesnode --test --experimental-test-coverage \
--test-coverage-include="src/**" \
--test-coverage-lines=80 --test-coverage-branches=70 \
--test-reporter=spec --test-reporter-destination=stdout \
--test-reporter=lcov --test-reporter-destination=lcov.infogo deeper
Recall that --experimental-test-coverage turns coverage on and that the report shows line, branch and function percentages per file.
Explain the three threshold flags and their exit code, the default exclusions, and how include and exclude globs combine.
Set up a CI gate that cannot be gamed by unloaded files or ignore comments, pair lcov with a human reporter, and pin Node because the feature is experimental.
Decide whether a coverage threshold is a hard gate or a trend signal for the team, and who approves coverage-ignore comments.
## Turning coverage on The runner measures **code coverage** with V8's built-in instrumentation, the same data `NODE_V8_COVERAGE` exposes, so no instrumenting transform or extra package is involved. In Node 24 the feature is still **Stability 1, Experimental**, and the flag says so: `--experimental-test-coverage`. When it is set, the runner collects coverage from the test processes and, once all tests have completed, prints a table of line, branch and function percentages with the uncovered line ranges for each file. If no tests run at all, no coverage report is generated. When `NODE_V8_COVERAGE` already names a directory, the raw V8 coverage files are also written there. ## Gating a build Three threshold flags turn the report into a pass or fail signal. Each takes a minimum percentage and, when coverage falls short, **sets the process exit code to 1**, so the CI step fails like a failing test: | Flag | Metric | |---|---| | `--test-coverage-lines=<n>` | Covered lines | | `--test-coverage-branches=<n>` | Covered branches | | `--test-coverage-functions=<n>` | Covered functions | All three were added in Node 22.8.0 and are experimental like coverage itself, so a team that gates on them should pin the Node version its CI runs and expect output and edge cases to move between releases. ## Deciding which files count By default, the report leaves out three groups: - **Node core modules**, whose URLs are not `file:` URLs; - **files under `node_modules/`**; - **test files**, but only those matching the **default** test-name patterns; a suite discovered through an explicit glob such as `"**/*.spec.js"` is not excluded, so its files show up in the table. Two glob flags change that, and each may be repeated: 1. `--test-coverage-include=<glob>` keeps only matching files, for example `"src/**"`; it is also how a file under `node_modules` is brought in. 2. `--test-coverage-exclude=<glob>` drops matching files. **Passing it replaces the default exclusion of test files**, so add the test patterns back in if you still want them out. 3. With both flags, a file must satisfy **both** to stay in the report. Lines can also be dropped in the source with comments: `/* node:coverage disable */` and `/* node:coverage enable */` bracket a region, and `/* node:coverage ignore next 3 */` skips the next three lines, or one line without a number. Each use deserves review, because each is a line the threshold no longer sees. ## Reporters for humans and for tools The `spec` and `tap` reporters print the coverage summary in the console. The **`lcov`** reporter writes an lcov file for coverage viewers and review tools, but **reports no test results**, so the documentation recommends using it alongside another reporter. With more than one reporter, every reporter needs its own `--test-reporter-destination` (`stdout`, `stderr` or a file path), and they are paired in the order given. Custom reporters receive the data through the `'test:coverage'` event. ## How collection works across processes Under the default process isolation, every test file runs in its own child process. The runner sets `NODE_V8_COVERAGE` for its children so their coverage lands in one directory, then merges it into a single report once every file has finished. Two practical consequences follow: - a source module imported by ten test files is reported once, with the union of what those files executed; - flags the runner manages itself, including `--experimental-test-coverage`, are filtered out of what the children inherit, so you set coverage once, on the parent command. The programmatic `run()` API from `node:test` exposes the same switch as `coverage: true`, with `coverageIncludeGlobs` and `coverageExcludeGlobs` options. ## What the number does not tell you - **Files no test loads are invisible.** The report is built from what V8 recorded, and the include and exclude globs only filter that set. A module that no test imports does not appear at 0%; it does not appear at all, so adding a large untested file leaves the percentage where it was. - **Coverage is execution, not verification.** A line counts once it runs, whether or not any assertion checked what it did. - **Disabled regions count as covered by omission.** A wide `node:coverage disable` block can keep a threshold green over code nobody tests. - **Mocked modules drop out.** A module replaced by `mock.module()` is skipped by the report. A sound gate therefore pairs a threshold with an include glob that names the source tree, a review rule for ignore comments, and a habit of importing every module somewhere in the suite.
- After adding `--test-coverage-exclude="src/generated/**"`, test files suddenly appear in the coverage table. Why?By default the runner excludes the files matched by the test patterns, but any explicit `--test-coverage-exclude` replaces that default instead of adding to it. Repeat the flag with the test file globs, for example `--test-coverage-exclude="**/*.test.js"`, or narrow the report with `--test-coverage-include="src/**"`.
- A teammate adds a large module with no tests, and the coverage percentage does not move. Why?The report only covers files V8 saw load during the run. If no test imports the new module, it is not in the report at all, so it cannot drag the percentage down. Importing every source module from the suite, even in a trivial smoke test, makes untested files visible and lets the threshold see them.
- Coverage in Node 24 needs no flag; node --test always reports it
- A threshold miss prints a warning but leaves the exit code at 0
- A module no test imports shows up in the report at 0%
- The lcov reporter also prints the test results
- Adding one exclude glob keeps the default test-file exclusion
Assumes Node 24, where --experimental-test-coverage is still Stability 1 and the --test-coverage-lines, -branches and -functions thresholds date from 22.8.0; the Node 26 docs keep the same flag and stability.