@@ -368,6 +368,54 @@ Otherwise, the test is considered to be a failure. Test files must be
368368executable by Node.js, but are not required to use the ` node:test ` module
369369internally.
370370
371+ ## Collecting code coverage
372+
373+ When Node.js is started with the [ ` --test-coverage ` ] [ ] command-line flag, code
374+ coverage is collected and statistics are reported once all tests have completed.
375+ If the [ ` NODE_V8_COVERAGE ` ] [ ] environment variable is used to specify a
376+ code coverage directory, the generated V8 coverage files are written to that
377+ directory. Node.js core modules and files within ` node_modules/ ` directories
378+ are not included in the coverage report. If coverage is enabled, the coverage
379+ report is sent to any [ test reporters] [ ] via the ` 'test:coverage' ` event.
380+
381+ Coverage can be disabled on a series of lines using the following
382+ comment syntax:
383+
384+ ``` js
385+ /* node:coverage disable */
386+ if (anAlwaysFalseCondition) {
387+ // Code in this branch will never be executed, but the lines are ignored for
388+ // coverage purposes. All lines following the 'disable' comment are ignored
389+ // until a corresponding 'enable' comment is encountered.
390+ console .log (' this is never executed' );
391+ }
392+ /* node:coverage enable */
393+ ```
394+
395+ Coverage can also be disabled for a specified number of lines. After the
396+ specified number of lines, coverage will be automatically reenabled. If the
397+ number of lines is not explicitly provided, a single line is ignored.
398+
399+ ``` js
400+ /* node:coverage ignore next */
401+ if (anAlwaysFalseCondition) { console .log (' this is never executed' ); }
402+
403+ /* node:coverage ignore next 3 */
404+ if (anAlwaysFalseCondition) {
405+ console .log (' this is never executed' );
406+ }
407+ ```
408+
409+ The test runner's code coverage functionality has the following limitations,
410+ which will be addressed in a future Node.js release:
411+
412+ * Although coverage data is collected for child processes, this information is
413+ not included in the coverage report. Because the command line test runner uses
414+ child processes to execute test files, it cannot be used with ` --test-coverage ` .
415+ * Source maps are not supported.
416+ * Excluding specific files or directories from the coverage report is not
417+ supported.
418+
371419## Mocking
372420
373421The ` node:test ` module supports mocking during testing via a top-level ` mock `
@@ -1201,6 +1249,42 @@ A successful call to [`run()`][] method will return a new {TestsStream}
12011249object, streaming a series of events representing the execution of the tests.
12021250` TestsStream ` will emit events, in the order of the tests definition
12031251
1252+ ### Event: ` 'test:coverage' `
1253+
1254+ * ` data ` {Object}
1255+ * ` summary ` {Object} An object containing the coverage report.
1256+ * ` files ` {Array} An array of coverage reports for individual files. Each
1257+ report is an object with the following schema:
1258+ * ` path ` {string} The absolute path of the file.
1259+ * ` totalLineCount ` {number} The total number of lines.
1260+ * ` totalBranchCount ` {number} The total number of branches.
1261+ * ` totalFunctionCount ` {number} The total number of functions.
1262+ * ` coveredLineCount ` {number} The number of covered lines.
1263+ * ` coveredBranchCount ` {number} The number of covered branches.
1264+ * ` coveredFunctionCount ` {number} The number of covered functions.
1265+ * ` coveredLinePercent ` {number} The percentage of lines covered.
1266+ * ` coveredBranchPercent ` {number} The percentage of branches covered.
1267+ * ` coveredFunctionPercent ` {number} The percentage of functions covered.
1268+ * ` uncoveredLineNumbers ` {Array} An array of integers representing line
1269+ numbers that are uncovered.
1270+ * ` totals ` {Object} An object containing a summary of coverage for all
1271+ files.
1272+ * ` totalLineCount ` {number} The total number of lines.
1273+ * ` totalBranchCount ` {number} The total number of branches.
1274+ * ` totalFunctionCount ` {number} The total number of functions.
1275+ * ` coveredLineCount ` {number} The number of covered lines.
1276+ * ` coveredBranchCount ` {number} The number of covered branches.
1277+ * ` coveredFunctionCount ` {number} The number of covered functions.
1278+ * ` coveredLinePercent ` {number} The percentage of lines covered.
1279+ * ` coveredBranchPercent ` {number} The percentage of branches covered.
1280+ * ` coveredFunctionPercent ` {number} The percentage of functions covered.
1281+ * ` workingDirectory ` {string} The working directory when code coverage
1282+ began. This is useful for displaying relative path names in case the tests
1283+ changed the working directory of the Node.js process.
1284+ * ` nesting ` {number} The nesting level of the test.
1285+
1286+ Emitted when code coverage is enabled and all tests have completed.
1287+
12041288### Event: ` 'test:diagnostic' `
12051289
12061290* ` data ` {Object}
@@ -1550,6 +1634,7 @@ added: v18.7.0
15501634 aborted.
15511635
15521636[ TAP ] : https://testanything.org/
1637+ [ `--test-coverage` ] : cli.md#--test-coverage
15531638[ `--test-name-pattern` ] : cli.md#--test-name-pattern
15541639[ `--test-only` ] : cli.md#--test-only
15551640[ `--test-reporter-destination` ] : cli.md#--test-reporter-destination
@@ -1558,6 +1643,7 @@ added: v18.7.0
15581643[ `MockFunctionContext` ] : #class-mockfunctioncontext
15591644[ `MockTracker.method` ] : #mockmethodobject-methodname-implementation-options
15601645[ `MockTracker` ] : #class-mocktracker
1646+ [ `NODE_V8_COVERAGE` ] : cli.md#node_v8_coveragedir
15611647[ `SuiteContext` ] : #class-suitecontext
15621648[ `TestContext` ] : #class-testcontext
15631649[ `context.diagnostic` ] : #contextdiagnosticmessage
@@ -1568,4 +1654,5 @@ added: v18.7.0
15681654[ describe options ] : #describename-options-fn
15691655[ it options ] : #testname-options-fn
15701656[ stream.compose ] : stream.md#streamcomposestreams
1657+ [ test reporters ] : #test-reporters
15711658[ test runner execution model ] : #test-runner-execution-model
0 commit comments