test_runner: Add option to exclude empty lines from coverage report

从 Node.js 测试运行器的覆盖率报告器入手，查看相关 issue #54753、#55228 和 #55339，包括已回滚的方法。使用 issue 中的命令重现空行报告，然后定义测试，证明新的 CLI 选项能够排除不可执行行，同时不会降低覆盖率的准确性。

Feature Request: Add --test-coverage-exclude-empty-lines option to test runner

Summary

The Node.js test runner's coverage reporter (--experimental-test-coverage) reports empty lines and certain non-executable lines as "uncovered", leading to inaccurate coverage percentages. Other V8-based coverage tools like Vitest have solved this with an ignoreEmptyLines / excludeEmptyLines option.

Problem

When running tests with coverage using the native test runner:

node --test --experimental-test-coverage tests/**/*.test.ts

Empty lines between statements are reported as uncovered:

# file             | line % | branch % | funcs % | uncovered lines
#   parse.ts       |  99.18 |    78.49 |  100.00 | 118 183-184

Looking at line 118:

116:  // Find the element declaration for this root
117:  const elementEntry = findElementByName(schema, rootLocalName);
118:  
119:  if (!elementEntry) {

Line 118 is empty - it contains no executable code, yet it's reported as uncovered.

Expected Behavior

Empty lines, comments, and TypeScript type-only lines should be excluded from coverage calculations, or there should be an option to exclude them.

How Other Tools Solve This

Vitest (@vitest/coverage-v8)

Vitest uses v8-to-istanbul with the excludeEmptyLines option:

• Issue: https://github.com/vitest-dev/vitest/issues/5423
• Implementation uses @jridgewell/trace-mapping to determine which lines contain runtime code

v8-to-istanbul

PR implementing this feature: https://github.com/istanbuljs/v8-to-istanbul/pull/244

The approach:

When source maps are available, use @jridgewell/trace-mapping to figure out which lines contain runtime code. If a line is not present in source maps, consider it as empty line. This will exclude TypeScript typings, comments, empty lines and any other special syntax that transpiled languages exclude from source maps.

c8

c8 also uses v8-to-istanbul and can leverage the same excludeEmptyLines option.

Previous Attempts

• PR #55228 attempted to add "ignore unmapped lines for coverage"
• PR #55339 reverted it due to test accuracy issues
• Issue #54753 tracks this feature request

Proposed Solution

Add a CLI flag --test-coverage-exclude-empty-lines (or similar) that:

1. Uses source map information to identify non-executable lines
2. Excludes empty lines from coverage calculations
3. Optionally excludes comments (when source maps indicate they're not runtime code)

This could be implemented by:

1. Integrating v8-to-istanbul's excludeEmptyLines logic
2. Or using @jridgewell/trace-mapping directly to filter coverage data

Reproduction

# Create a simple TypeScript file with empty lines
cat > test.ts << 'EOF'
export function add(a: number, b: number): number {
  const result = a + b;
  
  return result;
}
EOF

cat > test.test.ts << 'EOF'
import { describe, it } from 'node:test';
import assert from 'node:assert';
import { add } from './test.ts';

describe('add', () => {
  it('should add numbers', () => {
    assert.equal(add(1, 2), 3);
  });
});
EOF

# Run with coverage (using tsx for TypeScript)
npx tsx --test --experimental-test-coverage test.test.ts

The empty line (line 3) will show as uncovered despite 100% of executable code being tested.

Environment

• Node.js: v24.10.0
• OS: Linux

Related Issues

• #54753 - Original feature request
• #55228 - Previous implementation attempt
• #55339 - Revert of #55228