test_runner: add statement coverage support by Felipeness · Pull Request #62340 · nodejs/node

Felipeness · 2026-03-19T14:13:30Z

Summary

Add statement coverage to the test runner's coverage reporting, alongside existing line, branch, and function coverage
Parse source files with acorn to extract AST statement nodes, then map V8 coverage ranges to those statements using a most-specific-range algorithm
Add --test-coverage-statements CLI option for setting minimum statement coverage thresholds
Files that cannot be parsed by acorn gracefully degrade to 100% statement coverage

Implementation

Uses acorn-walk's Statement visitor to collect all non-BlockStatement nodes from the AST. For each statement, the algorithm finds the most specific (smallest) V8 coverage range that fully contains it, using that range's execution count as the statement's coverage count. This approach is similar to how @aspect-build/v8-coverage (used by Vitest) handles statement coverage.

Files changed

lib/internal/test_runner/coverage.js - Core statement extraction and coverage computation
lib/internal/test_runner/utils.js - Added stmts % column to coverage report table
lib/internal/test_runner/test.js - Statement coverage threshold checking
src/node_options.cc / src/node_options.h - --test-coverage-statements CLI option
doc/api/cli.md - Documentation for the new option
test/parallel/test-runner-coverage-statements.js - Tests

Test plan

Statement coverage fields appear in custom reporter JSON output
Coverage percentages are computed correctly (covered/uncovered statements)
--test-coverage-statements threshold passing and failing
Out-of-range threshold validation
stmts % column appears in tap/spec reporter output
100% coverage for fully covered files

Refs: #54530

Parse source files with acorn to extract AST statement nodes and map V8 coverage ranges to those statements, providing statement-level coverage metrics alongside existing line, branch, and function coverage. The implementation uses acorn-walk's Statement visitor to collect all non-BlockStatement nodes, then finds the most specific (smallest) V8 coverage range containing each statement to determine its execution count. Files that cannot be parsed by acorn gracefully degrade to 100% statement coverage. Adds --test-coverage-statements CLI option for setting minimum statement coverage thresholds, consistent with existing --test-coverage-lines, --test-coverage-branches, and --test-coverage-functions options. Refs: nodejs#54530

nodejs-github-bot · 2026-03-19T14:13:36Z

Review requested:

@nodejs/config
@nodejs/test_runner

avivkeller · 2026-03-19T14:46:09Z

How does this affect performance?

Felipeness · 2026-03-19T15:25:50Z

Good question. Here's the breakdown:

When coverage is disabled: zero overhead. The coverage module is lazy-loaded behind if (!globalOptions.coverage) in configureCoverage(), so acorn is never require'd.

When coverage IS enabled: getStatements() adds one acorn parse + walk per source file during summary(). The main new cost is the AST parse — getLines() already does a readFileSync per file, and getStatements() does another one (they cache independently via #sourceLines / #sourceStatements Maps, but both read the file). Worth noting that both reads are against the same file so the OS page cache makes the second read essentially free.

The parse results are cached per file URL, so repeated calls don't re-parse. Files that fail to parse gracefully degrade to null (100% statement coverage) rather than throwing.

Relative to V8's own coverage instrumentation overhead (which is already the cost of --experimental-test-coverage), one acorn parse per file at report time is negligible — it only runs once at the end, not during test execution.

One minor thing I noticed while looking at this: getStatements and getLines could potentially share the source read (pass the source from one to the other or cache at a shared level), but that's a small optimization and probably not worth the added coupling.

The acorn-walk `simple` function does not fire a generic "Statement" visitor for concrete statement node types, which meant the statements array was always empty and coveredStatementPercent was always 100%. Fix by enumerating each concrete statement type (ExpressionStatement, ReturnStatement, IfStatement, etc.) as individual visitor keys. Also fixes: - sourceType fallback: try 'module' first, catch and retry 'script' - Infinity primordial: replace bare Infinity with bestRange null pattern - double disk I/O: summary() now reads source once and passes it to both getLines() and getStatements() - tests: assert totalStatementCount > 0 to catch this regression

Need to re-review newer code

avivkeller · 2026-03-19T16:02:26Z

lib/internal/test_runner/coverage.js

+const kStatementTypes = [
+  'ExpressionStatement', 'ReturnStatement', 'ThrowStatement',
+  'IfStatement', 'WhileStatement', 'DoWhileStatement',
+  'ForStatement', 'ForInStatement', 'ForOfStatement',
+  'SwitchStatement', 'TryStatement', 'BreakStatement',
+  'ContinueStatement', 'VariableDeclaration', 'LabeledStatement',
+  'WithStatement', 'DebuggerStatement',


I don't like this level of hard coding, is there not a general Statement handler or something?

Good call — acorn-walk's simple() does support a generic Statement category visitor that fires for every node dispatched in a statement position. Replaced the hardcoded array with a single visitor.Statement handler and a small deny-set for BlockStatement/EmptyStatement.

This also picks up ClassDeclaration, FunctionDeclaration, and StaticBlock which were missing from the original list, and stays forward-compatible with any future ESTree statement types.

Simplified the double parse (module→script fallback) to a single sourceType: 'script' pass with permissive flags too, since script mode + allowImportExportEverywhere handles both ESM and legacy CJS.

- Replace hardcoded kStatementTypes array with acorn-walk's generic "Statement" category visitor, which automatically covers all current and future ESTree statement types (including ClassDeclaration, FunctionDeclaration, and StaticBlock that were previously missing). BlockStatement and EmptyStatement are excluded via a small deny-set. - Simplify AST parsing to a single pass using sourceType: 'script' with permissive flags (allowReturnOutsideFunction, allowImportExportEverywhere, allowAwaitOutsideFunction). Script mode is non-strict, so it handles both ESM and legacy CJS (e.g. `with` statements) without needing a module→script fallback. - Flatten V8 coverage ranges before the statement matching loop, reducing nesting from three levels to two. - Add coverage-class.js fixture and test for ClassDeclaration and StaticBlock statement coverage.

ljharb · 2026-03-20T01:39:17Z

Haven’t had a chance to review yet, but conceptually, this is awesome - without all 4 standard coverage metrics, a testing solution is incomplete. Will review soon :-)

- Add allowHashBang to acorn parse options for shebang support - Reorder requires to follow ASCII convention - Reuse existing doesRangeContainOtherRange helper - Add comments to empty catch blocks for consistency - Remove else after return in findLineForOffset - Break kColumnsKeys across multiple lines (max-len) - Document statement coverage fields in test:coverage event schema - Migrate threshold tests to data-driven loop - Remove unused tmpdir import from test file - Add fixture proving statement != line coverage - Add fixture testing shebang file parsing - Add fixture testing graceful degradation for unparseable files Refs: nodejs#62340

ljharb

For checking statement coverage thresholds this seems great! Does this also output coverage data that includes statement info?

pmarchini · 2026-03-20T08:25:02Z

test/parallel/test-runner-coverage-statements.js

+
+common.skipIfInspectorDisabled();
+
+const fixture = fixtures.path('test-runner', 'coverage.js');


Are we confident that this fixture covers statement edge cases well enough? I’m asking because it was built for the initial implementation

avivkeller · 2026-03-20T10:41:57Z

lib/internal/test_runner/coverage.js

+    // acorn-walk's simple() fires a generic "Statement" visitor for every
+    // node dispatched in a statement position (Program body, block bodies,
+    // if/for/while bodies, etc.). This automatically covers all current and
+    // future ESTree statement types without hardcoding a list.
+    const visitor = { __proto__: null };
+    visitor.Statement = (node) => {
+      if (kExcludedStatementTypes.has(node.type)) return;
+      ArrayPrototypePush(statements, {
+        __proto__: null,
+        startOffset: node.start,
+        endOffset: node.end,
+        count: 0,
+      });
+    };


You should create this object inline

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 19, 2026

avivkeller previously approved these changes Mar 19, 2026

View reviewed changes

avivkeller reviewed Mar 19, 2026

View reviewed changes

ljharb reviewed Mar 20, 2026

View reviewed changes

pmarchini reviewed Mar 20, 2026

View reviewed changes

avivkeller reviewed Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

test_runner: add statement coverage support#62340

test_runner: add statement coverage support#62340
Felipeness wants to merge 4 commits intonodejs:mainfrom
Felipeness:feat/test-runner-statement-coverage

Felipeness commented Mar 19, 2026

Uh oh!

nodejs-github-bot commented Mar 19, 2026

Uh oh!

avivkeller commented Mar 19, 2026

Uh oh!

Felipeness commented Mar 19, 2026

Uh oh!

avivkeller Mar 19, 2026

Uh oh!

Felipeness Mar 19, 2026

Uh oh!

ljharb commented Mar 20, 2026

Uh oh!

ljharb left a comment

Uh oh!

pmarchini Mar 20, 2026

Uh oh!

avivkeller Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		common.skipIfInspectorDisabled();

		const fixture = fixtures.path('test-runner', 'coverage.js');

Uh oh!

Conversation

Felipeness commented Mar 19, 2026

Summary

Implementation

Files changed

Test plan

Uh oh!

nodejs-github-bot commented Mar 19, 2026

Uh oh!

avivkeller commented Mar 19, 2026

Uh oh!

Felipeness commented Mar 19, 2026

Uh oh!

avivkeller Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Felipeness Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

ljharb commented Mar 20, 2026

Uh oh!

ljharb left a comment

Choose a reason for hiding this comment

Uh oh!

pmarchini Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants