test_runner: adds built in lcov reporter

Fixes#49626
PR-URL: #50018
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: philnash

doc/api/test.md

@@ -426,6 +426,18 @@ if (anAlwaysFalseCondition) {
 }
 ```
 
+### Coverage reporters
+
+The tap and spec reporters will print a summary of the coverage statistics.
+There is also an lcov reporter that will generate an lcov file which can be
+used as an in depth coverage report.
+
+```bash
+node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info
+```
+
+### Limitations
+
 The test runner's code coverage functionality has the following limitations,
 which will be addressed in a future Node.js release:
 
@@ -871,6 +883,10 @@ The following built-reporters are supported:
 *`junit`
  The junit reporter outputs test results in a jUnit XML format
 
+*`lcov`
+ The `lcov` reporter outputs test coverage when used with the
+[`--experimental-test-coverage`][] flag.
+
 When `stdout` is a [TTY][], the `spec` reporter is used by default.
 Otherwise, the `tap` reporter is used by default.
 
@@ -882,11 +898,11 @@ to the test runner's output is required, use the events emitted by the
 The reporters are available via the `node:test/reporters` module:
 
 ```mjs
-import { tap, spec, dot, junit } from'node:test/reporters';
+import { tap, spec, dot, junit, lcov } from'node:test/reporters';
 ```
 
 ```cjs
-const { tap, spec, dot, junit } =require('node:test/reporters');
+const { tap, spec, dot, junit, lcov } =require('node:test/reporters');
 ```
 
 ### Custom reporters

lib/internal/test_runner/reporter/lcov.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const{ relative }=require('path');
+constTransform=require('internal/streams/transform');
+
+// This reporter is based on the LCOV format, as described here:
+// https://ltp.sourceforge.net/coverage/lcov/geninfo.1.php
+// Excerpts from this documentation are included in the comments that make up
+// the _transform function below.
+classLcovReporterextendsTransform{
+constructor(options){
+super({ ...options,writableObjectMode: true,__proto__: null});
+}
+
+_transform(event,_encoding,callback){
+if(event.type!=='test:coverage'){
+returncallback(null);
+}
+letlcov='';
+// A tracefile is made up of several human-readable lines of text, divided
+// into sections. If available, a tracefile begins with the testname which
+// is stored in the following format:
+// ## TN:\<test name\>
+lcov+='TN:\n';
+const{
+data: {
+summary: { workingDirectory },
+},
+}=event;
+try{
+for(leti=0;i<event.data.summary.files.length;i++){
+constfile=event.data.summary.files[i];
+// For each source file referenced in the .da file, there is a section
+// containing filename and coverage data:
+// ## SF:\<path to the source file\>
+lcov+=`SF:${relative(workingDirectory,file.path)}\n`;
+
+// Following is a list of line numbers for each function name found in
+// the source file:
+// ## FN:\<line number of function start\>,\<function name\>
+//
+// After, there is a list of execution counts for each instrumented
+// function:
+// ## FNDA:\<execution count\>,\<function name\>
+//
+// This loop adds the FN lines to the lcov variable as it goes and
+// gathers the FNDA lines to be added later. This way we only loop
+// through the list of functions once.
+letfnda='';
+for(letj=0;j<file.functions.length;j++){
+constfunc=file.functions[j];
+constname=func.name||`anonymous_${j}`;
+lcov+=`FN:${func.line},${name}\n`;
+fnda+=`FNDA:${func.count},${name}\n`;
+}
+lcov+=fnda;
+
+// This list is followed by two lines containing the number of
+// functions found and hit:
+// ## FNF:\<number of functions found\>
+// ## FNH:\<number of function hit\>
+lcov+=`FNF:${file.totalFunctionCount}\n`;
+lcov+=`FNH:${file.coveredFunctionCount}\n`;
+
+// Branch coverage information is stored which one line per branch:
+// ## BRDA:\<line number\>,\<block number\>,\<branch number\>,\<taken\>
+// Block number and branch number are gcc internal IDs for the branch.
+// Taken is either '-' if the basic block containing the branch was
+// never executed or a number indicating how often that branch was
+// taken.
+for(letj=0;j<file.branches.length;j++){
+lcov+=`BRDA:${file.branches[j].line},${j},0,${file.branches[j].count}\n`;
+}
+
+// Branch coverage summaries are stored in two lines:
+// ## BRF:\<number of branches found\>
+// ## BRH:\<number of branches hit\>
+lcov+=`BRF:${file.totalBranchCount}\n`;
+lcov+=`BRH:${file.coveredBranchCount}\n`;
+
+// Then there is a list of execution counts for each instrumented line
+// (i.e. a line which resulted in executable code):
+// ## DA:\<line number\>,\<execution count\>[,\<checksum\>]
+constsortedLines=file.lines.toSorted((a,b)=>a.line-b.line);
+for(letj=0;j<sortedLines.length;j++){
+lcov+=`DA:${sortedLines[j].line},${sortedLines[j].count}\n`;
+}
+
+// At the end of a section, there is a summary about how many lines
+// were found and how many were actually instrumented:
+// ## LH:\<number of lines with a non-zero execution count\>
+// ## LF:\<number of instrumented lines\>
+lcov+=`LH:${file.coveredLineCount}\n`;
+lcov+=`LF:${file.totalLineCount}\n`;
+
+// Each sections ends with:
+// end_of_record
+lcov+='end_of_record\n';
+}
+}catch(error){
+returncallback(error);
+}
+returncallback(null,lcov);
+}
+}
+
+module.exports=LcovReporter;

lib/internal/test_runner/utils.js

@@ -118,6 +118,7 @@ const kBuiltinReporters = new SafeMap([
 ['dot','internal/test_runner/reporter/dot'],
 ['tap','internal/test_runner/reporter/tap'],
 ['junit','internal/test_runner/reporter/junit'],
+['lcov','internal/test_runner/reporter/lcov'],
 ]);
 
 constkDefaultReporter=process.stdout.isTTY ? 'spec' : 'tap';

lib/test/reporters.js

@@ -6,6 +6,7 @@ let dot;
 letjunit;
 letspec;
 lettap;
+letlcov;
 
 ObjectDefineProperties(module.exports,{
 __proto__: null,
@@ -45,4 +46,13 @@ ObjectDefineProperties(module.exports, {
 returntap;
 },
 },
+lcov: {
+__proto__: null,
+configurable: true,
+enumerable: true,
+get(){
+lcov??=require('internal/test_runner/reporter/lcov');
+returnReflectConstruct(lcov,arguments);
+},
+},
 });

test/fixtures/test-runner/output/lcov_reporter.js

@@ -0,0 +1,7 @@
+'use strict';
+require('../../../common');
+constfixtures=require('../../../common/fixtures');
+constspawn=require('node:child_process').spawn;
+
+spawn(process.execPath,
+['--no-warnings','--experimental-test-coverage','--test-reporter','lcov',fixtures.path('test-runner/output/output.js')],{stdio: 'inherit'});