monocart-coverage-reports 2.0.10 → 2.2.0

package/README.md

@@ -13,6 +13,7 @@
 * [Available Reports](#available-reports)
 * [Multiprocessing Support](#multiprocessing-support)
 * [onEnd Hook](#onend-hook)
+* [`mcr` CLI](#mcr-cli)
 * [Compare Reports](#compare-reports)
 * [Compare Workflows](#compare-workflows)
 * [Collecting Istanbul Coverage Data](#collecting-istanbul-coverage-data)
@@ -30,12 +31,12 @@
 
 ## Usage
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = {
     outputDir: './coverage-reports',
     reports: "v8"
 }
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData1);
 await coverageReport.add(coverageData2);
 const coverageResults = await coverageReport.generate();
@@ -49,9 +50,13 @@ console.log(coverageResults.summary);
 
 ## Available Reports
 - `v8` (V8 data only)
-    - [V8 html](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)
+    - Test in browser
+        - Build with webpack: [V8](https://cenfun.github.io/monocart-coverage-reports/v8) and [V8 Minify](https://cenfun.github.io/monocart-coverage-reports/v8-minify)
+        - Build with [Rollup](https://cenfun.github.io/monocart-coverage-reports/v8-rollup) and [Esbuild](https://cenfun.github.io/monocart-coverage-reports/v8-esbuild)
+        - Collect with [puppeteer](https://cenfun.github.io/monocart-coverage-reports/puppeteer/) 
+    - Test in Node.js
+        - Collect with [env](https://cenfun.github.io/monocart-coverage-reports/v8-node-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)
+        - Web server example: [koa](https://cenfun.github.io/monocart-coverage-reports/v8-node-koa/)
 
 ![](test/v8.gif)
 
@@ -82,7 +87,7 @@ console.log(coverageResults.summary);
 - `text-summary`
 
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = {
     outputDir: './coverage-reports',
     reports: [
@@ -97,7 +102,7 @@ const options = {
         'lcovonly'
     ]
 }
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 ```
 
 ## Integration
@@ -109,26 +114,26 @@ const coverageReport = new CoverageReport(options);
 The data will be added to `[outputDir]/.cache`, and the cache will be removed after reports generated.
 - sub process 1
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData1);
 ```
 
 - sub process 2
 ```js
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 await coverageReport.add(coverageData2);
 ```
 
 - main process
 ```js
 // after all sub processes finished
-const CoverageReport = require('monocart-coverage-reports');
+const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = new CoverageReport(options);
+const coverageReport = MCR(options);
 const coverageResults = await coverageReport.generate();
 console.log(coverageResults.summary);
 ```
@@ -164,6 +169,43 @@ const coverageOptions = {
 }
 ```
 
+## `mcr` CLI
+- Global mode
+```sh
+npm i monocart-coverage-reports -g
+mcr "node ./test/test-node-env.js" -r v8,console-summary --lcov
+```
+- Current working directory mode
+```sh
+npm i monocart-coverage-reports
+npx mcr "node ./test/test-node-env.js" -r v8,console-summary --lcov
+```
+- CLI Options
+```sh
+Usage: mcr [options] <command>
+
+CLI to generate coverage reports
+
+Arguments:
+  command                      command to execute
+
+Options:
+  -V, --version                output the version number
+  -c, --config <path>          config path for options
+  -o, --outputDir <dir>        output dir for reports
+  -r, --reports <name[,name]>  coverage reports to use
+  -n, --name <name>            report name for title
+  --outputFile <path>          output file for v8 report
+  --inline                     inline html for v8 report
+  --assetsPath <path>          assets path if not inline
+  --lcov                       generate lcov.info file
+  -h, --help                   display help for command
+```
+- Using configuration file for more options
+```sh
+mcr "node ./test/test-node-env.js" -c test/cli-options.js
+```
+
 ## Compare Reports
 | | Istanbul | V8 | V8 to Istanbul |
 | :--------------| :------ | :------ | :----------------------  |
@@ -206,33 +248,39 @@ const coverageOptions = {
     - Rollup: build with [options](https://rollupjs.org/configuration-options/) `sourcemap: true`
     - Vite: build with [options](https://vitejs.dev/config/build-options.html) `sourcemap: true` and `minify: false` 
 - 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)
+    > Collecting coverage data with [Chromium Coverage API](#chromium-coverage-api), see [playwright example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-v8.js) or [puppeteer example](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/test-puppeteer.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
-- Using Node.js env [NODE_V8_COVERAGE](https://nodejs.org/docs/latest/api/cli.html#node_v8_coveragedir)=`dir`
+Possible solutions:
+- Node.js env [NODE_V8_COVERAGE](https://nodejs.org/docs/latest/api/cli.html#node_v8_coveragedir)=`dir`
     - 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-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 + NODE_V8_COVERAGE
+- [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-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))
+- [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
+- [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)
 
+- [Debugger](https://nodejs.org/en/guides/debugging-getting-started) + NODE_V8_COVERAGE + CDP + V8 API
+    > cross-env NODE_V8_COVERAGE=.temp/v8-coverage-koa node --inspect=9229 [./test/koa.js](./test/koa.js)
+    - example:
+    > node [./test/test-node-koa.js](./test/test-node-koa.js)
+
 ## 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:
 ```
@@ -333,8 +381,8 @@ if (platform === 'linux') {
 
 ## 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)
+- [Puppeteer Coverage class](https://pptr.dev/api/puppeteer.coverage)
 - [DevTools Protocol for Coverage](https://chromedevtools.github.io/devtools-protocol/tot/Profiler/#method-startPreciseCoverage)
 
 ## V8 Coverage Data Format
@@ -380,6 +428,25 @@ 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)
 
 ## Istanbul Introduction
 - [Istanbul coverage report](https://istanbul.js.org/) - Instrumenting source codes and generating coverage reports

package/lib/cli.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const EC = require('eight-colors');
+const { fileURLToPath } = require('url');
+
+const {
+    foregroundChild,
+    program
+} = require('./packages/monocart-coverage-vendor.js');
+
+const MCR = require('./index.js');
+const Util = require('./utils/util.js');
+const defaultOptions = require('./default/options.js');
+const version = require('../package.json').version;
+
+const cleanDir = (dir) => {
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, {
+            recursive: true,
+            force: true
+        });
+    }
+};
+
+const initOptions = (cliOptions) => {
+    // merge all cli options
+    const configPath = cliOptions.config;
+    if (configPath) {
+        if (fs.existsSync(configPath)) {
+            const config = require(path.resolve(configPath));
+            Object.assign(cliOptions, config);
+        } else {
+            EC.logRed(`Not found config: ${configPath}`);
+        }
+    }
+
+    // init reports to list with `,`
+    const reports = cliOptions.reports;
+    if (reports) {
+        cliOptions.reports = reports.split(',');
+    }
+
+    // report options
+    const options = {
+        ... defaultOptions
+    };
+    Object.keys(cliOptions).forEach((k) => {
+        if (Util.hasOwn(options, k)) {
+            options[k] = cliOptions[k];
+        }
+    });
+
+    return options;
+};
+
+const executeCommand = async (command, cliOptions) => {
+
+    const options = initOptions(cliOptions);
+
+    console.log('Execute:', EC.cyan(command));
+    // console.log(options);
+
+    const nodeV8CoverageDir = path.resolve(options.outputDir, '.v8-coverage');
+    process.env.NODE_V8_COVERAGE = nodeV8CoverageDir;
+
+    cleanDir(nodeV8CoverageDir);
+
+    // console.log('nodeV8CoverageDir', nodeV8CoverageDir);
+
+    const coverageReport = MCR(options);
+    coverageReport.cleanCache();
+
+    // on start hook
+    const onStart = cliOptions.onStart;
+    if (typeof onStart === 'function') {
+        await onStart(coverageReport);
+    }
+
+    foregroundChild(command, {
+        shell: true
+    }, async () => {
+
+        if (!fs.existsSync(nodeV8CoverageDir)) {
+            EC.logRed(`Not found coverage data: ${Util.relativePath(nodeV8CoverageDir)}`);
+            return 1;
+        }
+
+        const files = fs.readdirSync(nodeV8CoverageDir);
+        for (const filename of files) {
+            const content = fs.readFileSync(path.resolve(nodeV8CoverageDir, filename)).toString('utf-8');
+            const json = JSON.parse(content);
+            let coverageList = json.result;
+
+            // filter node internal files
+            coverageList = coverageList.filter((entry) => entry.url && entry.url.startsWith('file:'));
+
+            if (!coverageList.length) {
+                continue;
+            }
+            // attached source content
+            coverageList.forEach((entry) => {
+                const filePath = fileURLToPath(entry.url);
+                if (fs.existsSync(filePath)) {
+                    entry.source = fs.readFileSync(filePath).toString('utf8');
+                } else {
+                    EC.logRed('not found file', Util.relativePath(filePath));
+                }
+            });
+
+            await coverageReport.add(coverageList);
+        }
+
+        await coverageReport.generate();
+
+        // remove nodeV8CoverageDir
+        if (options.logging !== 'debug') {
+            cleanDir(nodeV8CoverageDir);
+        }
+
+        return process.exitCode;
+    });
+
+};
+
+program
+    .name('mcr')
+    .description('CLI to generate coverage reports')
+    .version(version)
+    .argument('<command>', 'command to execute')
+    .option('-c, --config <path>', 'config path for options')
+    .option('-o, --outputDir <dir>', 'output dir for reports')
+    .option('-r, --reports <name[,name]>', 'coverage reports to use')
+    .option('-n, --name <name>', 'report name for title')
+
+    .option('--outputFile <path>', 'output file for v8 report')
+    .option('--inline', 'inline html for v8 report')
+    .option('--assetsPath <path>', 'assets path if not inline')
+
+    .option('--lcov', 'generate lcov.info file')
+
+    .action((command, cliOptions) => {
+        executeCommand(command, cliOptions);
+    });
+
+program.parse();

package/lib/converter/ast.js

@@ -170,7 +170,7 @@ const getJsAstInfo = (item, coverageList) => {
     try {
         ast = acorn.parse(source, options);
     } catch (e) {
-        Util.logError(`failed to parse source file and fall back to loose: ${item.sourcePath} ${e.message}`);
+        Util.logInfo(`failed to parse source file: ${item.sourcePath} ${e.message}`);
         // https://github.com/acornjs/acorn/tree/master/acorn-loose
         // It is recommended to always try a parse with the regular acorn parser first,
         // and only fall back to this parser when that one finds syntax errors.

package/lib/converter/converter.js

@@ -774,8 +774,9 @@ const collectOriginalList = (item, state, originalMap, options) => {
 
         // add file item
         const url = fileUrls[sourcePath] || sourcePath;
+
         // add dist for id
-        const id = Util.calculateSha1(distFile + url + source);
+        const id = Util.calculateSha1(distFile + sourcePath + source);
 
         const sourceItem = {
             url,
@@ -975,22 +976,30 @@ const convertV8List = async (v8list, options) => {
         // merge state
         Object.assign(fileSources, state.fileSources);
         Object.assign(coverageData, state.coverageData);
-        if (state.sourceList) {
+
+        if (Util.isList(state.sourceList)) {
             sourceList = sourceList.concat(state.sourceList);
         }
 
     }
 
-    // dedupe
-    dedupeV8List(v8list);
-
     // add all sources
     if (sourceList.length) {
         sourceList.forEach((item) => {
+
+            // exists same id, mark previous item as dedupe
+            const prevItem = v8list.find((it) => it.id === item.id);
+            if (prevItem) {
+                prevItem.dedupe = true;
+            }
+
             v8list.push(item);
         });
     }
 
+    // dedupe
+    dedupeV8List(v8list);
+
     return {
         fileSources,
         coverageData

package/lib/default/options.js

@@ -1,13 +1,13 @@
 module.exports = {
 
-    // (String) logging levels: off, error, info, debug
+    // {string} logging levels: off, error, info, debug
     logging: 'info',
 
-    // (String) output dir
+    // {string} output dir
     outputDir: './coverage-reports',
 
-    // (String) v8 or html for istanbul by default
-    // (Array) multiple reports with options
+    // {string} v8 or html for istanbul by default
+    // {array} multiple reports with options
     // v8 report or istanbul supported reports
     // reports: [
     //     ['v8'],
@@ -18,19 +18,19 @@ module.exports = {
     // ],
     reports: '',
 
-    // (String) Report name. Defaults to "Coverage Report".
+    // {string} Report name. Defaults to "Coverage Report".
     name: 'Coverage Report',
 
-    // [V8 only](String) Output [sub dir/]filename. Defaults to "index.html"
+    // (V8 only) {string} Output [sub dir/]filename. Defaults to "index.html"
     outputFile: 'index.html',
 
-    // [V8 only](Boolean) Inline all scripts to the single HTML file. Defaults to false.
+    // (V8 only) {boolean} Inline all scripts to the single HTML file. Defaults to false.
     inline: false,
 
-    // [V8 only](String) Assets path if not inline. Defaults to "./assets"
+    // (V8 only) {string} Assets path if not inline. Defaults to "./assets"
     assetsPath: './assets',
 
-    // [V8 only](Function) A filter function to execute for each element in the V8 list.
+    // (V8 only) {function} A filter function to execute for each element in the V8 list.
     // entryFilter: (entry) => {
     //     if (entry.url.indexOf('googleapis.com') !== -1) {
     //         return false;
@@ -39,30 +39,30 @@ module.exports = {
     // },
     entryFilter: null,
 
-    // [V8 only](Function) A filter function to execute for each element in the sources which unpacked from the source map.
+    // (V8 only) {function} A filter function to execute for each element in the sources which unpacked from the source map.
     // sourceFilter: (sourcePath) => sourcePath.search(/src\/.+/) !== -1,
     sourceFilter: null,
 
-    // [V8 only](Boolean) Enable/Disable ignoring uncovered codes with the special comments: /* v8 ignore next/next N/start/stop */
+    // (V8 only) {boolean} Enable/Disable ignoring uncovered codes with the special comments: v8 ignore next/next N/start/stop
     v8Ignore: true,
 
-    // [Istanbul only] defaultSummarizer, sourceFinder
+    // (Istanbul only) defaultSummarizer, sourceFinder
 
-    // (Boolean) Generate lcov.info file, same as lcovonly report. Defaults to false.
+    // {boolean} Generate lcov.info file, same as lcovonly report. Defaults to false.
     lcov: false,
 
-    // (Function) Source path handler.
+    // {function} Source path handler.
     // sourcePath: (filePath) => `wwwroot/${filePath}`,
     sourcePath: null,
 
-    // (String|Function) Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html.
+    // {string|function} Specify the report path, especially when there are multiple reports. Defaults to outputDir/index.html.
     reportPath: null,
 
-    // (Array) watermarks for low/medium/high. Defaults to [50, 80]
-    // (Object) Istanbul: { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] }.
+    // {array} watermarks for low/medium/high. Defaults to [50, 80]
+    // {object} Istanbul: { statements:[50,80], functions:[50,80], branches:[50,80], lines:[50,80] }, V8: { bytes:[50,80] }.
     watermarks: [50, 80],
 
-    // (Function) onEnd hook
+    // {function} onEnd hook
     // onEnd: async (reportData) => {}
     onEnd: null
 };