monocart-coverage-reports 2.0.8 → 2.0.10

package/README.md

@@ -3,6 +3,8 @@
 [![](https://img.shields.io/npm/v/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
 [![](https://badgen.net/npm/dw/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
 ![](https://img.shields.io/github/license/cenfun/monocart-coverage-reports)
+![](https://img.shields.io/github/actions/workflow/status/cenfun/monocart-coverage-reports/static.yml)
+
 
 > Code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
 
@@ -10,6 +12,7 @@
 * [Default Options](#default-options)
 * [Available Reports](#available-reports)
 * [Multiprocessing Support](#multiprocessing-support)
+* [onEnd Hook](#onend-hook)
 * [Compare Reports](#compare-reports)
 * [Compare Workflows](#compare-workflows)
 * [Collecting Istanbul Coverage Data](#collecting-istanbul-coverage-data)
@@ -21,6 +24,7 @@
     - [How Monocart Works](#how-monocart-works)
 * [Ignoring Uncovered Lines](#ignoring-uncovered-lines)
 * [Chromium Coverage API](#chromium-coverage-api)
+* [V8 Coverage Data Format](#v8-coverage-data-format)
 * [Istanbul Introduction](#istanbul-introduction)
 * [Thanks](#thanks)
 
@@ -129,11 +133,42 @@ const coverageResults = await coverageReport.generate();
 console.log(coverageResults.summary);
 ```
 
+## onEnd Hook
+For example, checking thresholds:
+```js
+const EC = require('eight-colors');
+const coverageOptions = {
+    name: 'My Coverage Report',
+    outputDir: './coverage-reports',
+    onEnd: (coverageResults) => {
+        const thresholds = {
+            bytes: 80,
+            lines: 60
+        };
+        console.log('check thresholds ...', thresholds);
+        const errors = [];
+        const { summary } = coverageResults;
+        Object.keys(thresholds).forEach((k) => {
+            const pct = summary[k].pct;
+            if (pct < thresholds[k]) {
+                errors.push(`Coverage threshold for ${k} (${pct} %) not met: ${thresholds[k]} %`);
+            }
+        });
+        if (errors.length) {
+            const errMsg = errors.join('\n');
+            console.log(EC.red(errMsg));
+            // throw new Error(errMsg);
+            // process.exit(1);
+        }
+    }
+}
+```
+
 ## Compare Reports
 | | Istanbul | V8 | V8 to Istanbul |
 | :--------------| :------ | :------ | :----------------------  |
-| Coverage data | Istanbul (Object) | V8 (Array) | V8 (Array) |
-| Output | [Istanbul reports](#istanbul-reports) | [V8 reports](#v8-reports)  | [Istanbul reports](#istanbul-reports) |
+| Coverage data | [Istanbul](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) (Object) | [V8](#v8-coverage-data-format) (Array) | [V8](#v8-coverage-data-format) (Array) |
+| Output | [Istanbul reports](#available-reports) | [V8 reports](#available-reports)  | [Istanbul reports](#available-reports) |
 | - Bytes | ❌ | ✅ | ❌ |
 | - Statements | ✅ | ❌ | ☑️❔ |
 | - Branches | ✅ | ☑️❔ | ☑️❔ |
@@ -181,12 +216,12 @@ console.log(coverageResults.summary);
     - Before running your Node.js application, set env `NODE_V8_COVERAGE`=`dir`. After the application runs and exits, the coverage data will be saved to the `dir` directory in JSON file format
     - Read the json file(s) from the `dir` and generate coverage report
     - example:
-    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage` node [./test/test-node-env.js](./test/test-node-env.js) && node [./test/generate-node-report.js](./test/generate-node-report.js)
+    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage-env` node [./test/test-node-env.js](./test/test-node-env.js) && node [./test/generate-node-report.js](./test/generate-node-report.js)
 
-- Using [V8](https://nodejs.org/docs/latest/api/v8.html#v8takecoverage) API
+- Using [V8](https://nodejs.org/docs/latest/api/v8.html#v8takecoverage) API + NODE_V8_COVERAGE
     - Writing the coverage started by NODE_V8_COVERAGE to disk on demand with `v8.takeCoverage()` and stopping with `v8.stopCoverage()`. 
     - example:
-    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage` node [./test/test-node-api.js](./test/test-node-api.js)
+    > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage-api` node [./test/test-node-api.js](./test/test-node-api.js)
 
 - Using [Inspector](https://nodejs.org/docs/latest/api/inspector.html) API (or module [collect-v8-coverage](https://github.com/SimenB/collect-v8-coverage))
    - Connecting to the V8 inspector and enable V8 coverage.
@@ -201,24 +236,24 @@ console.log(coverageResults.summary);
 ## Using `entryFilter` and `sourceFilter` to filter the results for V8 report
 When V8 coverage data collected, it actually contains the data of all entry files, for example:
 ```
-1, dist/main.js
-2, dist/vendor.js
-3, dist/something-else.js
+dist/main.js
+dist/vendor.js
+dist/something-else.js
 ```
 We can use `entryFilter` to filter the entry files. For example, we should remove `vendor.js` and `something-else.js` if they are not in our coverage scope. 
 ```
-1, dist/main.js
+dist/main.js
 ```
 When inline or linked sourcemap exists to the entry file, the source files will be extracted from the sourcemap for the entry file, and the entry file will be removed if `logging` is not `debug`.
 ```
-1, src/index.js
-2, src/components/app.js
-3, node_modules/dependency/dist/dependency.js
+> src/index.js
+> src/components/app.js
+> node_modules/dependency/dist/dependency.js
 ```
 We can use `sourceFilter` to filter the source files. For example, we should remove `dependency.js` if it is not in our coverage scope.
 ```
-1, src/index.js
-2, src/components/app.js
+> src/index.js
+> src/components/app.js
 ```
 Example:
 ```js
@@ -245,13 +280,15 @@ And also there are some problems about counting the functions and branches:
 functions.forEach(block => {
     block.ranges.forEach((range, i) => {
         if (block.isBlockCoverage) {
-            // v8-to-istanbul: count range as branch here. 
+            // v8-to-istanbul: new CovBranch() 
             // Problem: not every block is branch, and the first block is actually function.
             if (block.functionName && i === 0) {
-                // v8-to-istanbul: count range as function here. 
+                // v8-to-istanbul: new CovFunction()
+                // Problem: no anonymous function
             }
         } else if (block.functionName) {
-            // v8-to-istanbul: count range as function here. 
+            // v8-to-istanbul: new CovFunction()
+            // Problem: no anonymous function
         }
     }
 });
@@ -288,7 +325,7 @@ const os = platform === 'wind32' ? 'Windows' : 'Other';
 
 const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
 
-/* v8 ignore next 3 */
+// v8 ignore next 3
 if (platform === 'linux') {
     console.info('hello linux');
 }
@@ -300,6 +337,50 @@ if (platform === 'linux') {
 - [Playwright Coverage Class](https://playwright.dev/docs/api/class-coverage)
 - [DevTools Protocol for Coverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage)
 
+## V8 Coverage Data Format
+```js
+// Coverage data for a source range.
+export interface CoverageRange {
+    // JavaScript script source offset for the range start.
+    startOffset: integer;
+    // JavaScript script source offset for the range end.
+    endOffset: integer;
+    // Collected execution count of the source range.
+    count: integer;
+}
+
+// Coverage data for a JavaScript function.
+/**
+ * @functionName can be an empty string.
+ * @ranges is always non-empty. The first range is called the "root range".
+ * @isBlockCoverage indicates if the function has block coverage information.
+    If this is false, it usually means that the functions was never called.
+    It seems to be equivalent to ranges.length === 1 && ranges[0].count === 0.
+*/
+export interface FunctionCoverage {
+    // JavaScript function name.
+    functionName: string;
+    // Source ranges inside the function with coverage data.
+    ranges: CoverageRange[];
+    // Whether coverage data for this function has block granularity.
+    isBlockCoverage: boolean;
+}
+
+// Coverage data for a JavaScript script.
+export interface ScriptCoverage {
+    // JavaScript script id.
+    scriptId: Runtime.ScriptId;
+    // JavaScript script name or url.
+    url: string;
+    // Functions contained in the script that has coverage data.
+    functions: FunctionCoverage[];
+}
+
+export type V8CoverageData = ScriptCoverage[];
+```
+see devtools-protocol [ScriptCoverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#type-ScriptCoverage) and [v8-coverage](https://github.com/bcoe/v8-coverage)
+
+
 ## Istanbul Introduction
 - [Istanbul coverage report](https://istanbul.js.org/) - Instrumenting source codes and generating coverage reports
 - [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul)

package/lib/converter/branches.js

@@ -30,11 +30,11 @@ const createBranchGroup = (type, branchStart, parents, branchMap, functionInfo)
     const reverseParents = [].concat(parents).reverse();
     const group = {
         type,
-        loc: {
-            start: branchStart,
-            // could be updated if multiple locations
-            end: branchStart
-        },
+
+        start: branchStart,
+        // could be updated if multiple locations
+        end: branchStart,
+
         locations: [],
         reverseParents,
         functionInfo
@@ -46,7 +46,7 @@ const createBranchGroup = (type, branchStart, parents, branchMap, functionInfo)
 const addBranch = (group, node, locationMap, functionInfo) => {
     const { start, end } = node;
 
-    const branchStart = group.loc.start;
+    const branchStart = group.start;
 
     // the block is not exact correct, if there is a block wrapped
     // [x8]{ var a = b || [x4]c }, b is no block, but it can be found in x8 block
@@ -66,7 +66,7 @@ const addBranch = (group, node, locationMap, functionInfo) => {
     group.locations.push(branchInfo);
 
     // update group end
-    group.loc.end = end;
+    group.end = end;
 
     locationMap.set(start, branchInfo);
 
@@ -224,12 +224,12 @@ const createBranches = (ast, functionInfo, branchMap) => {
             // first, left a and right c
             // then, left a and right b
             if (prevLocation) {
-                const { loc, locations } = group;
+                const { locations } = group;
                 locations.sort((a, b) => {
                     return a.start - b.start;
                 });
                 // update group end after sorted
-                loc.end = locations[locations.length - 1].end;
+                group.end = locations[locations.length - 1].end;
             }
         },
 
@@ -272,7 +272,7 @@ const IfStatement = (group, parentCount, noBlockList, blockCount) => {
     if (!noBlockList.length) {
         return;
     }
-    // console.log(parentCount, 'uncovered list', noBlockList.length, group.loc.start);
+    // console.log(parentCount, 'uncovered list', noBlockList.length, group.start);
     let count = parentCount - blockCount;
     noBlockList.forEach((item) => {
         item.count = count;
@@ -291,7 +291,7 @@ const LogicalExpression = (group, parentCount, noBlockList, blockCount) => {
         item.count = count;
     });
 
-    // const start = group.loc.start;
+    // const start = group.start;
     // if (start > 7874 && start < 7922) {
     //     console.log(group.type, parentCount, 'locations', group.locations);
     // }
@@ -381,16 +381,26 @@ const collectBranches = (branchMap) => {
     // init branches
     const branches = [];
     branchMap.forEach((group) => {
+
+        // add start/end for none with group start/end
+        group.locations.forEach((item) => {
+            if (item.none) {
+                item.start = group.start;
+                item.end = group.end;
+            }
+        });
+
         branches.push({
             type: group.type,
-            loc: group.loc,
+            start: group.start,
+            end: group.end,
             locations: group.locations
         });
     });
 
     // sort branches
     branches.sort((a, b) => {
-        return a.loc.start - b.loc.start;
+        return a.start - b.start;
     });
 
     return branches;