monocart-coverage-reports 2.2.1 → 2.3.0

package/README.md

@@ -18,8 +18,11 @@
 * [Compare Workflows](#compare-workflows)
 * [Collecting Istanbul Coverage Data](#collecting-istanbul-coverage-data)
 * [Collecting V8 Coverage Data](#collecting-v8-coverage-data)
+* [Manually Resolve the Sourcemap](#manually-resolve-the-sourcemap)
+* [Collecting Raw V8 Coverage Data with Puppeteer](#collecting-raw-v8-coverage-data-with-puppeteer)
 * [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
 * [Multiprocessing Support](#multiprocessing-support)
+* [Merge Coverage Reports](#merge-coverage-reports)
 * [Integration](#integration)
 * [Ignoring Uncovered Codes](#ignoring-uncovered-codes)
 * [Chromium Coverage API](#chromium-coverage-api)
@@ -64,11 +67,12 @@ console.log(coverageResults.summary);
 
 - `v8-json` (V8 data only)
     - [V8 coverage-report.json](https://cenfun.github.io/monocart-coverage-reports/v8-and-istanbul/coverage-report.json)
-- `console-summary` shows coverage summary in console
+- `codecov` (V8 data only)
+    - coverage data for [Codecov](https://docs.codecov.com/docs/codecov-custom-coverage-format), see [example](https://app.codecov.io/github/cenfun/monocart-coverage-reports) 
     
     ![](test/console-summary.png)
 
-> Following are [istanbul reports](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
+> Istanbul [build-in reports](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib)
 - `clover`
 - `cobertura`
 - `html`
@@ -88,11 +92,41 @@ console.log(coverageResults.summary);
 - `text-lcov`
 - `text-summary`
 
+> Other reports
+- `console-summary` shows coverage summary in console
+- `raw` only keep all original data, which can be used for other reports input with `inputDir`
+    - see [Merge Coverage Reports](#merge-coverage-reports)
+
+- Custom Reporter
+    ```js
+    {
+        reports: [
+            [path.resolve('./test/custom-istanbul-reporter.js'), {
+                type: 'istanbul',
+                file: 'custom-istanbul-coverage.text'
+            }],
+            [path.resolve('./test/custom-v8-reporter.js'), {
+                type: 'v8',
+                outputFile: 'custom-v8-coverage.json'
+            }],
+            [path.resolve('./test/custom-v8-reporter.mjs'), {
+                type: 'both'
+            }]
+        ]
+    }
+    ```
+    - istanbul custom reporter
+    > example: [./test/custom-istanbul-reporter.js](./test/custom-istanbul-reporter.js), see [istanbul built-in reporters' implementation](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib) for reference, 
+    - v8 custom reporter
+    > example: [./test/custom-v8-reporter.js](./test/custom-v8-reporter.js)
+
+### Multiple Reports:
 ```js
 const MCR = require('monocart-coverage-reports');
 const options = {
     outputDir: './coverage-reports',
     reports: [
+        // build-in reports
         ['console-summary'],
         ['v8'],
         ['html', {
@@ -101,7 +135,18 @@ const options = {
         ['json', {
             file: 'my-json-file.json'
         }],
-        'lcovonly'
+        'lcovonly',
+
+        // custom reports
+        // Specify reporter name with the NPM package
+        ["custom-reporter-1"],
+        ["custom-reporter-2", {
+            type: "istanbul",
+            option: "value"
+        }],
+        // Specify reporter name with local path
+        ['/absolute/path/to/custom-reporter.js']
+
     ]
 }
 const coverageReport = MCR(options);
@@ -248,13 +293,48 @@ mcr "node ./test/test-node-env.js" -c test/cli-options.js
     - [rollup](https://rollupjs.org/configuration-options/): `sourcemap: true`
     - [vite](https://vitejs.dev/config/build-options.html): `sourcemap: true` and `minify: false`
     - [esbuild](https://esbuild.github.io/api/): `sourcemap: true` and `minify: false`
+    - [Manually Resolve the Sourcemap](#manually-resolve-the-sourcemap)
 - Browser (Chromium Only)
     > Collecting coverage data with [Chromium Coverage API](#chromium-coverage-api):
     - [Playwright example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-v8.js), and [anonymous](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-anonymous.js), [css](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-css.js)
-    - [Puppeteer example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-puppeteer.js)
+    - see [Collecting Raw V8 Coverage Data with Puppeteer](#collecting-raw-v8-coverage-data-with-puppeteer)
 - Node.js
-    - see following [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
+    - see [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
 
+## Manually Resolve the Sourcemap
+> If the `js` file is loaded with `addScriptTag` [API](https://playwright.dev/docs/api/class-page#page-add-script-tag), then its sourcemap file may not work. You can try to manually read the sourcemap file before the coverage data is added to the report.
+```js
+const jsCoverage = await page.coverage.stopJSCoverage();
+jsCoverage.forEach((entry) => {
+    // read sourcemap for the my-dist.js manually
+    if (entry.url.endsWith('my-dist.js')) {
+        entry.sourceMap = JSON.parse(fs.readFileSync('dist/my-dist.js.map').toString('utf-8'));
+    }
+});
+
+await MCR(coverageOptions).add(jsCoverage);
+
+```
+
+## Collecting Raw V8 Coverage Data with Puppeteer
+> Puppeteer does not provide raw v8 coverage data by default. A simple conversion is required, see example: [./test/test-puppeteer.js](./test/test-puppeteer.js)
+```js
+await page.coverage.startJSCoverage({
+    // provide raw v8 coverage data
+    includeRawScriptCoverage: true
+});
+
+await page.goto(url);
+
+const jsCoverage = await page.coverage.stopJSCoverage();
+const rawV8CoverageData = jsCoverage.map((it) => {
+    // Convert to raw v8 coverage format
+    return {
+        source: it.text,
+        ... it.rawScriptCoverage
+    };
+}
+```
 
 ## Node.js V8 Coverage Report for Server Side
 Possible solutions:
@@ -317,9 +397,65 @@ const coverageResults = await coverageReport.generate();
 console.log(coverageResults.summary);
 ```
 
+## Merge Coverage Reports
+The following usage scenarios may require merging coverage reports:
+- When the code is executed in different environments, like Node.js Server Side and browser Client Side (Next.js for instance). Each environment may generate its own coverage report. Merging them can give a more comprehensive view of the test coverage.
+- When the code is subjected to different kinds of testing. For example, unit tests with Jest might cover certain parts of the code, while end-to-end tests with Playwright might cover other parts. Merging these different coverage reports can provide a holistic view of what code has been tested.
+- When tests are run on different machines or different shards, each might produce its own coverage report. Merging these can give a complete picture of the test coverage across all machines or shards.
+
+First, using the `raw` report to export the original coverage data to the specified directory.
+```js
+const coverageOptions = {
+    name: 'My Unit Test Coverage Report',
+    outputDir: "./coverage-reports/unit",
+    reports: [
+        ['raw', {
+            // relative path will be "./coverage-reports/unit/raw"
+            outputDir: "raw"
+        }],
+        ['v8'],
+        ['console-summary']
+    ]
+};
+```
+Then, after all the tests are completed, generate a merged report with option `inputDir`:
+```js
+import {CoverageReport} from 'monocart-coverage-reports';
+const coverageOptions = {
+    name: 'My Merged Coverage Report',
+    inputDir: [
+        './coverage-reports/unit/raw',
+        './coverage-reports/e2e/raw'
+    ],
+    outputDir: './coverage-reports/merged',
+    reports: [
+        ['v8'],
+        ['console-summary']
+    ]
+};
+await new CoverageReport(coverageOptions).generate();
+```
+If the source file comes from the sourcemap, then its path is a virtual path. Using the `sourcePath` option to convert it.
+```js
+const coverageOptions = {
+    sourcePath: (filePath) => {
+        // Remove the virtual prefix
+        const list = ['my-dist-file1/', 'my-dist-file2/'];
+        for (const str of list) {
+            if (filePath.startsWith(str)) {
+                return filePath.slice(str.length);
+            }
+        }
+        return filePath;
+    }
+};
+```
+see example: [./test/test-merge.js](./test/test-merge.js)
+
 ## Integration
 - [monocart-reporter](https://cenfun.github.io/monocart-reporter/) - Test reporter for [Playwright](https://github.com/microsoft/playwright)
-- [vitest-monocart-coverage](https://github.com/cenfun/vitest-monocart-coverage) - Integration with [Vitest](https://github.com/vitest-dev/vitest) coverage
+- [jest-monocart-coverage](https://github.com/cenfun/jest-monocart-coverage) - Integration with [Jest](https://github.com/jestjs/jest/) for coverage reports
+- [vitest-monocart-coverage](https://github.com/cenfun/vitest-monocart-coverage) - Integration with [Vitest](https://github.com/vitest-dev/vitest) for coverage reports
 
 ## Ignoring Uncovered Codes
 To ignore codes, use the special comment which starts with `v8 ignore `:
@@ -392,26 +528,6 @@ 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)
 
-### Collect raw v8 coverage data with Puppeteer
-```js
-await page.coverage.startJSCoverage({
-    // provide raw v8 coverage data
-    includeRawScriptCoverage: true
-});
-
-await page.goto(url);
-
-const jsCoverage = await page.coverage.stopJSCoverage();
-const rawV8CoverageData = jsCoverage.map((it) => {
-    // Convert to raw v8 coverage format
-    return {
-        source: it.text,
-        ... it.rawScriptCoverage
-    };
-}
-```
-see example: [./test/test-puppeteer.js](./test/test-puppeteer.js)
-
 ## 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:

package/lib/cli.js

@@ -36,12 +36,6 @@ const initOptions = (cliOptions) => {
         }
     }
 
-    // init reports to list with `,`
-    const reports = cliOptions.reports;
-    if (reports) {
-        cliOptions.reports = reports.split(',');
-    }
-
     // report options
     const options = {
         ... defaultOptions

package/lib/converter/ast.js

@@ -36,6 +36,17 @@ const collectAstInfo = (ast, state) => {
     const functions = [];
     const branchMap = new Map();
 
+    // root function branches
+    const functionRoot = state.functionRoot;
+    if (functionRoot) {
+        const rootFunctionInfo = {
+            count: functionRoot.count,
+            range: functionRoot
+        };
+        createBranches(ast, rootFunctionInfo, branchMap);
+    }
+
+    // functions branches
     Util.visitAst(ast, {
 
         VariableDeclarator(node, parents) {
@@ -101,15 +112,15 @@ const collectAstInfo = (ast, state) => {
 const generateCountState = (coverageList) => {
     const functionRanges = [];
     const functionNameMap = new Map();
+    let functionRoot;
     coverageList.forEach((block) => {
-        const { functionName, ranges } = block;
+        const {
+            functionName, ranges, root
+        } = block;
 
         // first one is function coverage info
         const functionRange = ranges[0];
         functionRange.functionName = functionName;
-        if (functionName) {
-            functionNameMap.set(functionRange.startOffset + functionName.length, functionRange);
-        }
 
         // blocks
         const len = ranges.length;
@@ -128,6 +139,15 @@ const generateCountState = (coverageList) => {
             functionRange.blockRanges = blockRanges;
         }
 
+        // root function
+        if (root) {
+            functionRoot = functionRange;
+            return;
+        }
+
+        if (functionName) {
+            functionNameMap.set(functionRange.startOffset + functionName.length, functionRange);
+        }
         functionRanges.push(functionRange);
 
     });
@@ -146,7 +166,8 @@ const generateCountState = (coverageList) => {
     return {
         functionMap,
         functionNameMap,
-        functionRanges
+        functionRanges,
+        functionRoot
     };
 
 };

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

@@ -81,6 +81,14 @@ const resolveSourceMap = (data) => {
 
 const saveSourceFile = async (filePath, data) => {
     await Util.writeFile(filePath, JSON.stringify(data));
+
+    // save source and sourcemap file for debug
+    // https://evanw.github.io/source-map-visualization
+    // if (data.sourceMap) {
+    //     await Util.writeFile(`${filePath}.js`, data.source);
+    //     await Util.writeFile(`${filePath}.js.map`, JSON.stringify(data.sourceMap));
+    // }
+
 };
 
 const collectSourceMaps = async (v8list, options) => {
@@ -105,15 +113,19 @@ const collectSourceMaps = async (v8list, options) => {
             continue;
         }
 
+        // save source and sourceMap to separated json file
         const sourceData = {
             url,
             id,
-            // source,
-            source: convertSourceMap.removeComments(source),
-            // could be existed
+            source,
             sourceMap
         };
 
+        // remove comments if not debug
+        if (Util.loggingType !== 'debug') {
+            sourceData.source = convertSourceMap.removeComments(source);
+        }
+
         // check sourceMap only for js
         if (type === 'js' && !sourceData.sourceMap) {
             // from inline sync