monocart-coverage-reports 2.0.3 → 2.0.5

package/README.md

@@ -4,15 +4,31 @@
 [![](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)
 
-> Code coverage tool to generate [V8](https://v8.dev/blog/javascript-code-coverage) or [Istanbul](https://istanbul.js.org/) coverage reports.
+> Code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
+
+* [Preview Reports](#preview-reports)
+* [Usage](#usage)
+* [Default Options](#default-options)
+* [Multiple Reports](#multiple-reports)
+    - [V8 reports](#v8-reports)
+    - [Istanbul reports](#istanbul-reports)
+* [Multiprocessing Support](#multiprocessing-support)
+* [Compare Reports](#compare-reports)
+* [Compare Workflows](#compare-workflows)
+* [Collecting Istanbul Coverage Data](#collecting-istanbul-coverage-data)
+* [Collecting V8 Coverage Data](#collecting-v8-coverage-data)
+* [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
+* [Using `entryFilter` and `sourceFilter` to filter the results for V8 report](#using-entryfilter-and-sourcefilter-to-filter-the-results-for-v8-report)
+* [How to convert V8 to Istanbul](#how-to-convert-v8-to-istanbul)
+    - [Using `v8-to-istanbul`](#using-v8-to-istanbul)
+    - [How Monocart Works](#how-monocart-works)
+* [Chromium Coverage API](#chromium-coverage-api)
+* [Istanbul Introduction](#istanbul-introduction)
+* [Thanks](#thanks)
 
 ## Preview Reports
-- [V8](https://cenfun.github.io/monocart-coverage-reports/v8)
-- [V8 Esbuild](https://cenfun.github.io/monocart-coverage-reports/v8-esbuild)
-- [V8 Rollup](https://cenfun.github.io/monocart-coverage-reports/v8-rollup)
-- [V8 lcov.info](https://cenfun.github.io/monocart-coverage-reports/v8/lcov.info)
-- [V8 Node env](https://cenfun.github.io/monocart-coverage-reports/v8-node-env)
-- [V8 Node Inspector](https://cenfun.github.io/monocart-coverage-reports/v8-node-ins)
+- [V8](https://cenfun.github.io/monocart-coverage-reports/v8) - Example for browser, build with webpack, and also [Rollup](https://cenfun.github.io/monocart-coverage-reports/v8-rollup) and [Esbuild](https://cenfun.github.io/monocart-coverage-reports/v8-esbuild)
+- [V8 Node](https://cenfun.github.io/monocart-coverage-reports/v8-node-env) - Example for Node.js using env, and also [V8 API](https://cenfun.github.io/monocart-coverage-reports/v8-node-api), [Inspector](https://cenfun.github.io/monocart-coverage-reports/v8-node-ins) and [CDP](https://cenfun.github.io/monocart-coverage-reports/v8-node-cdp)
 - [V8 Minify](https://cenfun.github.io/monocart-coverage-reports/v8-minify)
 - [V8 to Istanbul](https://cenfun.github.io/monocart-coverage-reports/v8-and-istanbul/istanbul)
 - [Istanbul](https://cenfun.github.io/monocart-coverage-reports/istanbul/)
@@ -105,7 +121,6 @@ console.log(coverageResults.summary);
 ## Compare Reports
 | | Istanbul | V8 | V8 to Istanbul |
 | :--------------| :------ | :------ | :----------------------  |
-| Instrumenting code | Required | No | No |
 | Coverage data | Istanbul (Object) | V8 (Array) | V8 (Array) |
 | Output | [Istanbul reports](#istanbul-reports) | [V8 reports](#v8-reports)  | [Istanbul reports](#istanbul-reports) |
 | - Bytes | ❌ | ✅ | ❌ |
@@ -121,70 +136,58 @@ console.log(coverageResults.summary);
 
 ## Compare Workflows
 - Istanbul Workflows
-    - 1, Only for source code: instrumenting code with [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul)，see [webpack.config-istanbul.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-istanbul.js), or using [nyc](https://github.com/istanbuljs/nyc).
-    - 2, Collecting coverage data from browser `window.__coverage__` or from node `global.__coverage__`, see [example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-istanbul.js).
-    - 3, Generating coverage report.
+    - 1, [Collecting Istanbul coverage data](#collecting-istanbul-coverage-data)
+    - 2, Adding coverage data and generating coverage report
 
 - V8 Workflows
-    - 1, For any runtime code: nothing to do. For source code: building code with `development` [mode](https://webpack.js.org/configuration/mode/) and [sourcemap](https://webpack.js.org/configuration/devtool/) support, see [webpack.config-v8.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-v8.js).
-    - 2, Collecting coverage data with [Chromium Coverage API](#chromium-coverage-api), see [example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-v8.js).
-    - 3, Generating coverage report.
+    - 1, [Collecting V8 coverage data](#collecting-v8-coverage-data)
+    - 3, Adding coverage data and generating coverage report
 
-## Chromium Coverage API
-- [V8 coverage report](https://v8.dev/blog/javascript-code-coverage) - Native support for JavaScript code coverage to V8. (Chromium only)
-- [Puppeteer Coverage Class](https://pptr.dev/api/puppeteer.coverage)
-- [Playwright Coverage Class](https://playwright.dev/docs/api/class-coverage)
-- [DevTools Protocol for Coverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage)
+## Collecting Istanbul Coverage Data
+- Instrumenting source code
+    > Before collecting Istanbul coverage data, It requires your source code is instrumented with Istanbul
+    - Webpack: [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul), example: [webpack.config-istanbul.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-istanbul.js)
+    - Rollup: [rollup-plugin-istanbul](https://github.com/artberri/rollup-plugin-istanbul)
+    - Vite: [vite-plugin-istanbul](https://github.com/ifaxity/vite-plugin-istanbul)
+- Browser
+    > Collecting coverage data from `window.__coverage__`, example: [test-istanbul.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-istanbul.js)
+- Node.js
+    > Collecting coverage data from `global.__coverage__`
+
+## Collecting V8 Coverage Data
+- For source code: enable `sourcemap` and do not compress/minify:
+    - Webpack: with `source-map` [devtool](https://webpack.js.org/configuration/devtool/) and `development` [mode](https://webpack.js.org/configuration/mode/), example [webpack.config-v8.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-v8.js)
+    - Rollup: [options](https://rollupjs.org/configuration-options/) `sourcemap: true`
+- Browser (Chromium Only)
+    > Collecting coverage data with [Chromium Coverage API](#chromium-coverage-api), see [example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-v8.js)
+- Node.js
+    > see [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
 
 
 ## Node.js V8 Coverage Report for Server Side
-There are two ways to collect native V8 coverage data and generate coverage report:
 - Using Node.js env [NODE_V8_COVERAGE](https://nodejs.org/docs/latest/api/cli.html#node_v8_coveragedir)=`dir`
-    - 1, 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.
-    - 2, Read the json file(s) from the `dir` and generate coverage report. see example:
+    - 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)
-    
-- Using [Inspector](https://nodejs.org/docs/latest/api/inspector.html) API
-   - 1, Connecting to the V8 inspector and enable V8 coverage.
-   ```js
-    const inspector = require('inspector');
-    const startV8Coverage = async () => {
-        const session = new inspector.Session();
-        session.connect();
-        await session.post('Profiler.enable');
-        await session.post('Profiler.startPreciseCoverage', {
-            callCount: true,
-            detailed: true
-        });
-        return session;
-    };
-   ```
-   - 2, Taking coverage data and adding to the report after your application runs.
-   ```js
-    const takeV8Coverage = (session) => {
-        return new Promise((resolve) => {
-            session.post('Profiler.takePreciseCoverage', (error, coverage) => {
-                if (error) {
-                    console.log(error);
-                    resolve();
-                    return;
-                }
-                resolve(coverage.result);
-            });
-        });
-    };
-    const coverageList = await takeV8Coverage(session);
-    // filter node internal files
-    coverageList = coverageList.filter((entry) => entry.url && !entry.url.startsWith('node:'));
-    await new CoverageReport(coverageOptions).add(coverageList);
-   ```
-   - 3, Generating coverage report. see example: [./test/test-node-ins.js](./test/test-node-ins.js)
-   ```js
-    await new CoverageReport(coverageOptions).generate();
-   ```
+
+- Using [V8](https://nodejs.org/docs/latest/api/v8.html#v8takecoverage) API
+    - 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)
+
+- 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.
+   - Taking coverage data and adding to the report after your application runs.
+   - example: [./test/test-node-ins.js](./test/test-node-ins.js)
+   
+- Using [CDP](https://chromedevtools.github.io/devtools-protocol/) API
+    - Enabling [Node Debugging](https://nodejs.org/en/guides/debugging-getting-started/)
+    - Collecting coverage data with CDP API.
+    - example: [./test/test-node-cdp.js](./test/test-node-cdp.js)
 
 ## Using `entryFilter` and `sourceFilter` to filter the results for V8 report
-When you add coverage data with [Chromium Coverage API](#chromium-coverage-api), it actually contains the data of all entry files, for example:
+When V8 coverage data collected, it actually contains the data of all entry files, for example:
 ```
 1, dist/main.js
 2, dist/vendor.js
@@ -213,12 +216,63 @@ const coverageOptions = {
 };
 ```
 
-## Istanbul Coverage
+## How to convert V8 to Istanbul
+### Using [v8-to-istanbul](https://github.com/istanbuljs/v8-to-istanbul)
+It is a popular library which is used to convert V8 coverage format to istanbul's coverage format. Most test frameworks are using it, such as [Jest](https://github.com/jestjs/jest/), [Vitest](https://github.com/vitest-dev/vitest), but it has two major problems:
+- 1, The source mapping does not work well if the position is between the two consecutive mappings. for example: 
+```js
+const a = tf ? 'true' : 'false';
+               ^     ^  ^
+              m1     p  m2
+```
+> `m1` and `m2` are two consecutive mappings, `p` is the position we looking for. However, we can only get the position of the `m1` if we don't fix it to `p`. Especially the generated code is different from the original code, such as minified, compressed or converted, then it becomes very difficult to find the middle position between two mappings.
+
+- 2, The coverage of functions and branches is incorrect. V8 only provided coverage at functions and it's blocks. But if a function is uncovered (count = 0), there is no information for it's blocks and sub-level functions.
+And also there are some problems about counting the functions and branches:
+```js
+functions.forEach(block => {
+    block.ranges.forEach((range, i) => {
+        if (block.isBlockCoverage) {
+            // v8-to-istanbul: count range as branch here. 
+            // 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. 
+                // Problem: there is no function name if the function is anonymous or expression.
+            }
+        } else if (block.functionName) {
+            // v8-to-istanbul: count range as function here. 
+            // Problem: same as above function.
+        }
+    }
+});
+// Problem: When the function or parent-level function is uncovered, then its sub-level functions will never be counted.
+```
+see source code [v8-to-istanbul.js](https://github.com/istanbuljs/v8-to-istanbul/blob/master/lib/v8-to-istanbul.js)
+
+### How Monocart Works
+We have removed `v8-to-istanbul` because of the two major problems and implemented new converter:
+- 1, Trying to fix the middle position if not found the exact mapping.
+- 2, Finding all functions and branches by parsing the source code [AST](https://github.com/acornjs/acorn), however the V8 cannot provide effective branch coverage information, so the branches is still not perfect.
+
+| AST | V8 | 
+| :--------------| :------ | 
+| AssignmentPattern | 🛇 Not Support | 
+| ConditionalExpression | ✔ Not Perfect | 
+| IfStatement | ✔ Not Perfect | 
+| LogicalExpression | ✔ Not Perfect | 
+| SwitchStatement | ✔ Not Perfect | 
+
+## Chromium Coverage API
+- [V8 coverage report](https://v8.dev/blog/javascript-code-coverage) - Native support for JavaScript code coverage to V8. (Chromium only)
+- [Puppeteer Coverage Class](https://pptr.dev/api/puppeteer.coverage)
+- [Playwright Coverage Class](https://playwright.dev/docs/api/class-coverage)
+- [DevTools Protocol for Coverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage)
+
+## 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)
 - [istanbul-reports](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 - [Code Coverage Introduction](https://docs.cypress.io/guides/tooling/code-coverage)
 
-
 ## Thanks
 - Special thanks to [@edumserrano](https://github.com/edumserrano)

package/lib/converter/ast.js

@@ -162,6 +162,7 @@ const getJsAstInfo = (item, coverageList) => {
         allowReturnOutsideFunction: true,
         allowImportExportEverywhere: true,
         allowSuperOutsideMethod: true,
+        allowAwaitOutsideFunction: true,
         // first line: #!/usr/bin/env node
         allowHashBang: true
     };

package/lib/converter/collect-source-maps.js

@@ -79,56 +79,27 @@ const resolveSourceMap = (data) => {
     }
 };
 
-const collectInlineSourceMaps = async (v8list) => {
-    let count = 0;
-    const concurrency = new Concurrency();
-    for (const item of v8list) {
-
-        const { type, source } = item;
-
-        // only for js
-        if (type === 'js') {
-            const converter = convertSourceMap.fromSource(source);
-            if (converter) {
-                item.sourceMap = resolveSourceMap(converter.sourcemap);
-                count += 1;
-                // source map comments is inline source map, remove it because it is big
-                item.source = convertSourceMap.removeComments(source);
-
-                continue;
-            }
-            const sourceMapUrl = getSourceMapUrl(source, item.url);
-            if (sourceMapUrl) {
-                // console.log('========================', sourceMapUrl);
-                item.sourceMapUrl = sourceMapUrl;
-                concurrency.addItem(item);
-            }
-        }
-    }
-    await concurrency.start(async (item) => {
-        const data = await loadSourceMap(item.sourceMapUrl);
-        if (data) {
-            item.sourceMap = resolveSourceMap(data);
-            count += 1;
-            // source map comments is a link, no need remove
-        }
-    });
-
-    return count;
+const saveSourceFile = async (filePath, data) => {
+    await Util.writeFile(filePath, JSON.stringify(data));
 };
 
-const collectFileSourceMaps = async (v8list, options) => {
+const collectSourceMaps = async (v8list, options) => {
+
     let count = 0;
     const concurrency = new Concurrency();
     for (const item of v8list) {
 
         const {
-            type, url, source, id
+            type, url, id, source, sourceMap
         } = item;
 
-        // remove source just keep functions to reduce artifacts size
+        // source and sourceMap will be saved as separated file (could be cached)
+        // just keep functions coverage ( could be multiple times, will be merged )
+        // so remove source and sourceMap
         delete item.source;
+        delete item.sourceMap;
 
+        // source and sourceMap already saved
         const sourcePath = Util.resolveCacheSourcePath(options.cacheDir, id);
         if (fs.existsSync(sourcePath)) {
             continue;
@@ -137,18 +108,23 @@ const collectFileSourceMaps = async (v8list, options) => {
         const sourceData = {
             url,
             id,
-            source: convertSourceMap.removeComments(source)
+            // source,
+            source: convertSourceMap.removeComments(source),
+            // could be existed
+            sourceMap
         };
 
-        // only for js
-        if (type === 'js') {
-            const converter = convertSourceMap.fromSource(source);
-            if (converter) {
-                sourceData.sourceMap = resolveSourceMap(converter.sourcemap);
+        // check sourceMap only for js
+        if (type === 'js' && !sourceData.sourceMap) {
+            // from inline sync
+            const smc = convertSourceMap.fromSource(source);
+            if (smc) {
+                sourceData.sourceMap = resolveSourceMap(smc.sourcemap);
                 count += 1;
                 await saveSourceFile(sourcePath, sourceData);
                 continue;
             }
+            // from url async
             const sourceMapUrl = getSourceMapUrl(source, item.url);
             if (sourceMapUrl) {
                 concurrency.addItem({
@@ -160,10 +136,12 @@ const collectFileSourceMaps = async (v8list, options) => {
             }
         }
 
+        // no need check sourceMap
         await saveSourceFile(sourcePath, sourceData);
 
     }
 
+    // from url concurrency
     await concurrency.start(async (item) => {
         const sourceData = item.sourceData;
         const data = await loadSourceMap(item.sourceMapUrl);
@@ -175,19 +153,6 @@ const collectFileSourceMaps = async (v8list, options) => {
     });
 
     return count;
-};
-
-const saveSourceFile = async (filePath, data) => {
-    await Util.writeFile(filePath, JSON.stringify(data));
-};
-
-const collectSourceMaps = (v8list, options, inlineSourceMap) => {
-
-    if (inlineSourceMap) {
-        return collectInlineSourceMaps(v8list);
-    }
-
-    return collectFileSourceMaps(v8list, options);
 
 };
 

package/lib/converter/converter.js

@@ -475,7 +475,7 @@ const generateCoverageForDist = (item, state) => {
 
 // ========================================================================================================
 
-const decodeSourceMappings = async (item, state, originalDecodedMap) => {
+const decodeSourceMappings = async (state, originalDecodedMap) => {
 
     const generatedLocator = state.locator;
 
@@ -566,7 +566,7 @@ const getOriginalDecodedMappings = (originalDecodedMap, sourceIndex, locator) =>
     return decodedMappings;
 };
 
-const initOriginalList = (item, state, originalDecodedMap, options) => {
+const initOriginalList = (state, originalDecodedMap, options) => {
 
     // source filter
     let sourceFilter = options.sourceFilter;
@@ -580,6 +580,7 @@ const initOriginalList = (item, state, originalDecodedMap, options) => {
     const originalMap = new Map();
 
     const { sources, sourcesContent } = state.sourceMap;
+
     sources.forEach((sourcePath, sourceIndex) => {
 
         // filter
@@ -860,12 +861,12 @@ const unpackSourceMap = async (item, state, options) => {
     const time_start_decode = Date.now();
     const originalDecodedMap = new Map();
     // for find-original-range
-    state.decodedMappings = await decodeSourceMappings(item, state, originalDecodedMap);
+    state.decodedMappings = await decodeSourceMappings(state, originalDecodedMap);
     // only debug level
     Util.logTime(`decode source mappings: ${sourcePath}`, time_start_decode);
 
     // filter original list and init list
-    const originalMap = initOriginalList(item, state, originalDecodedMap, options);
+    const originalMap = initOriginalList(state, originalDecodedMap, options);
 
     originalDecodedMap.clear();
 

package/lib/converter/find-original-range.js

@@ -227,11 +227,15 @@ const getOriginalStartPosition = (originalText, generatedText, generatedPos) =>
     }
 
     // ============================
-    // no case for right
-    // const generatedRight = generatedText.slice(generatedPos);
-    // if (originalText.endsWith(generatedRight)) {
-    //     return originalText.length - generatedRight.length;
-    // }
+    // right matched
+
+    // originalText: "'true' : ",
+    // generatedText: '"true" : '
+
+    const generatedRight = generatedText.slice(generatedPos);
+    if (originalText.endsWith(generatedRight)) {
+        return originalText.length - generatedRight.length;
+    }
 
     // ============================
     // starts with original text (few case possible useless)
@@ -350,7 +354,7 @@ const fixStartColumn = (startMapping, range, state, originalState) => {
 
     const originalPos = getOriginalStartPosition(originalText, generatedText, generatedPos);
 
-    // if (originalState.sourcePath.endsWith('src/components/report.vue')) {
+    // if (originalState.sourcePath.endsWith('conditional.js') && range.startOffset === 2153) {
     //     console.log('====================================================================');
     //     console.log('fix startMapping', originalState.sourcePath);
     //     console.log(startMapping);
@@ -481,12 +485,6 @@ const findStartMapping = (range, state, originalMap) => {
             };
         }
 
-        // if (startMapping.sourceIndex === 1) {
-        //     console.log('=========================================================');
-        //     console.log('find next start');
-        //     console.log(startMapping, nextMapping, range);
-        // }
-
         // exact and column
         Object.assign(startMapping, nextMapping, {
             exact: true,
@@ -559,13 +557,10 @@ const findOriginalRange = (range, state, originalMap) => {
     const { startMapping, originalState } = startResult;
 
     // ==================================================================================
-    // if (originalState.sourcePath.endsWith('app/app.module.ts')) {
-    //     originalState.showLog = true;
-    //     console.log('============================================================');
-    //     console.log(originalState.sourcePath);
+    // if (originalState.sourcePath.endsWith('conditional.js') && range.startOffset === 2153) {
+    //     console.log('============================================================', originalState.sourcePath);
     //     console.log(range);
-    // } else {
-    //     originalState.showLog = false;
+    //     console.log(startMapping);
     // }
     // ==================================================================================
 

package/lib/index.js

@@ -63,9 +63,7 @@ class CoverageReport {
 
         if (Array.isArray(data)) {
             results.type = 'v8';
-            // init v8list and unpack sourcemap
-            const inlineSourceMap = false;
-            results.data = await initV8ListAndSourcemap(data, this.options, inlineSourceMap);
+            results.data = await initV8ListAndSourcemap(data, this.options);
         } else {
             results.type = 'istanbul';
             results.data = data;