monocart-coverage-reports 2.7.8 → 2.7.9

package/README.md

@@ -28,6 +28,8 @@
 * [Command Line](#command-line)
 * [Config File](#config-file)
 * [Merge Coverage Reports](#merge-coverage-reports)
+    - [Automatic Merging](#automatic-merging)
+    - [Manual Merging](#manual-merging)
 * [Common issues](#common-issues)
     - [Unexpected coverage](#unexpected-coverage)
     - [Unparsable source](#unparsable-source)
@@ -56,6 +58,10 @@
 
 ## Usage
 > It's recommended to use [Node.js 20+](https://nodejs.org/).
+- Install
+```sh
+npm install monocart-coverage-reports
+```
 - API
 ```js
 const MCR = require('monocart-coverage-reports');
@@ -83,16 +89,8 @@ mcr node my-app.js -r v8,console-details
 For more information, see [Command Line](#command-line)
 
 ## Options
-- Default Options: [lib/default/options.js](./lib/default/options.js)
-    - `reports` [Available Reports](#available-reports)
-    - `entryFilter` and `sourceFilter` [Using `entryFilter` and `sourceFilter` to filter the results for V8 report](#using-entryfilter-and-sourcefilter-to-filter-the-results-for-v8-report)
-    - `sourcePath` [Resolve `sourcePath` for the Source Files](#resolve-sourcepath-for-the-source-files)
-    - `all` [Adding Empty Coverage for Untested Files](#adding-empty-coverage-for-untested-files)
-    - `inputDir` [Merge Coverage Reports](#merge-coverage-reports)
-    - `logging` [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
-    - `onEnd` [onEnd Hook](#onend-hook)
-
-- Declaration: [lib/index.d.ts](./lib/index.d.ts)
+- Default options: [lib/default/options.js](./lib/default/options.js)
+- Options declaration see `CoverageReportOptions` [lib/index.d.ts](./lib/index.d.ts)
 - [Config file](#config-file)
 
 ## Available Reports
@@ -255,9 +253,11 @@ const mcr = MCR(coverageOptions);
 ```js
 await Promise.all([
     page.coverage.startJSCoverage({
+        // reportAnonymousScripts: true,
         resetOnNavigation: false
     }),
     page.coverage.startCSSCoverage({
+        // Note, anonymous styles (without sourceURLs) are not supported, alternatively, you can use CDPClient
         resetOnNavigation: false
     })
 ]);
@@ -274,10 +274,12 @@ const coverageData = [... jsCoverage, ... cssCoverage];
 ```
 For more examples, see [./test/test-v8.js](./test/test-v8.js), and [anonymous](./test/test-anonymous.js), [css](./test/test-css.js)
 
+
 ### Collecting Raw V8 Coverage Data with Puppeteer
 ```js
 await Promise.all([
     page.coverage.startJSCoverage({
+        // reportAnonymousScripts: true,
         resetOnNavigation: false,
         // provide raw v8 coverage data
         includeRawScriptCoverage: true
@@ -487,23 +489,42 @@ const coverageOptions = {
     sourceFilter: (sourcePath) => sourcePath.search(/src\//) !== -1
 };
 ```
-Or using `minimatch` pattern:
+Or using [`minimatch`](https://github.com/isaacs/minimatch) pattern:
 ```js
 const coverageOptions = {
     entryFilter: "**/main.js",
     sourceFilter: "**/src/**"
 };
-// supports multiple patterns:
+```
+Supports multiple patterns:
+```js
 const coverageOptions = {
     entryFilter: {
+        '**/node_modules/**': false,
         '**/vendor.js': false,
-        '**/main.js': true
+        '**/src/**': true
     },
     sourceFilter: {
-        '**/src/**': true
+        '**/node_modules/**': false,
+        '**/**': true
     }
 };
 ```
+In fact, the `minimatch` patterns will be transformed to a function like:
+```js
+const coverageOptions = {
+    // '**/node_modules/**': false,
+    // '**/vendor.js': false,
+    // '**/src/**': true
+    entryFilter: (entry) => {
+        if (minimatch(entry.url, '**/node_modules/**')) { return false; }
+        if (minimatch(entry.url, '**/vendor.js')) { return false; }
+        if (minimatch(entry.url, '**/src/**')) { return true; }
+        return false; // else unmatched
+    }
+    // Note, the order of the patterns will impact the results
+};
+```
 
 ## Resolve `sourcePath` for the Source Files
 If the source file comes from the sourcemap, then its path is a virtual path. Using the `sourcePath` option to resolve a custom path.
@@ -544,7 +565,7 @@ const coverageOptions = {
     }
 };
 ```
-The filter also supports `minimatch` pattern:
+The filter also supports [`minimatch`](https://github.com/isaacs/minimatch) pattern:
 ```js
 const coverageOptions = {
     all: {
@@ -684,7 +705,7 @@ Arguments:
   command                      command to execute
 
 Options:
-  -V, --version                output the version number
+  -v, --version                output the current version
   -c, --config <path>          custom config file path
   -l, --logging <logging>      off, error, info, debug
   -n, --name <name>            report name for title
@@ -728,13 +749,19 @@ Loading config file by priority:
 
 ## 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. see example [nextjs-with-playwright](https://github.com/cenfun/nextjs-with-playwright) for automatic report merging.
+- 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.
+- When tests are run on different machines or containers, each might produce its own coverage report. Merging these can give a complete picture of the test coverage across all machines or shards.
 
+### Automatic Merging
+- `MCR` will automatically merge all the added coverage data when executing `generate()`. And it supports adding coverage data asynchronously across processes, see [Multiprocessing Support](#multiprocessing-support)
+- For Next.js, it can actually add coverage data including both server side and client side before executing `generate()`, see example [nextjs-with-playwright](https://github.com/cenfun/nextjs-with-playwright)
+- Use Codecov, a popular online code coverage service, which supports automatic merging of reports. Please use report `codecov`, it will generate report file `codecov.json`. If multiple `codecov.json` files are generated, upload all these files, they will be automatically merged. see [Codecov](#codecov) and [merging reports](https://docs.codecov.com/docs/merging-reports)
+
+### Manual Merging
 If the reports cannot be merged automatically, then here is how to manually merge the reports.
 First, using the `raw` report to export the original coverage data to the specified directory.
-For example, we have `raw` coverage data from unit tests:
+- For example, we have `raw` coverage data from unit tests, which is output to `./coverage-reports/unit/raw`
 ```js
 const coverageOptions = {
     name: 'My Unit Test Coverage Report',
@@ -750,8 +777,8 @@ const coverageOptions = {
     ]
 };
 ```
-We also have `raw` coverage data from e2e tests, which is output to `./coverage-reports/e2e/raw`.
-After all the tests are completed, generate a merged report with option `inputDir`:
+- We also have `raw` coverage data from e2e tests, which is output to `./coverage-reports/e2e/raw`
+- Create a script `merge-coverage.js` to generate a merged report with option `inputDir`. After all the tests are completed, running script `node path/to/merge-coverage.js`
 ```js
 // merge-coverage.js
 const fs = require('fs');
@@ -801,20 +828,32 @@ const coverageOptions = {
 };
 await new CoverageReport(coverageOptions).generate();
 ```
+- All the command scripts are probably like following:
+```json
+{
+    "scripts": {
+        "test:unit": "jest",
+        "test:e2e": "playwright test",
+        "merge-coverage": "node path/to/merge-coverage.js",
+        "test": "npm run test:unit && npm run test:e2e && npm run merge-coverage"
+    }
+}
+```
 
 ## Common issues
 ### Unexpected coverage
-In most cases, it happens when the coverage of the generated code is converted to the coverage of the original code through a sourcemap. In other words, it's an issue with the sourcemap. Most of the time, we can solve this by setting `minify` to `false` in the build tools configuration. Let's take a look at an example:
+In most cases, it happens when the coverage of the generated code is converted to the coverage of the original code through a sourcemap. In other words, it's an issue with the sourcemap. Most of the time, we can solve this by setting `minify` to `false` in the configuration of build tools. Let's take a look at an 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` or `m2` if we don't fix it to `p`. Especially the generated code is different from the original code, such as the code was minified, compressed or converted, it is difficult to find the exact position. You can try [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
+In the generated code, there is a position `p`, and we need to find out its corresponding position in the original code. Unfortunately, there is no matched mapping for the position `p`. Instead, it has two adjacent upstream and downstream mappings `m1` and `m2`, so, the original position of `p` that we are looking for, might not be able to be precisely located. Especially, the generated code is different from the original code, such as the code was minified, compressed or converted, it is difficult to find the exact original position without matched mapping. 
+- Further understanding of sourcemap, try [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
 
 How `MCR` Works:
-- 1, Trying to fix the middle original position with string comparison and [`diff-sequences`](https://github.com/jestjs/jest/tree/main/packages/diff-sequences). However, for non-JS code, such as Vue template, JSX, etc., it might be hard to find a perfect solution.
-- 2, Finding all functions, statements and branches by parsing the source code [AST](https://github.com/acornjs/acorn). However, there's a small issue, which is the V8 cannot provide effective branch coverage information for `AssignmentPattern`.
+- 1, Trying to fix the original position with string comparison and [`diff-sequences`](https://github.com/jestjs/jest/tree/main/packages/diff-sequences). However, for non-JS code, such as Vue template, JSX, etc., it might be hard to find a perfect solution.
+- 2, Finding all functions, statements and branches by parsing the source code [AST](https://github.com/acornjs/acorn). (There is a small issue is the V8 cannot provide effective branch coverage information for `AssignmentPattern`)
 
 
 ### Unparsable source

package/lib/cli.js

@@ -21,53 +21,78 @@ const getRegisterPath = (filename) => {
     return `./${rel}`;
 };
 
-const initNodeOptions = async (cliOptions) => {
-
-    // module register added in Node.js: v20.6.0
-    const nv = process.versions.node;
-    if (Util.cmpVersion(nv, '20.6.0') < 0) {
-        Util.logInfo(`The current Node.js version "${nv}" does NOT support "module.register", it requires "20.6.0" or higher.`);
-        return;
-    }
-
+const getInitNodeOptions = async (cliOptions) => {
     const nodeOptions = [];
     if (process.env.NODE_OPTIONS) {
         nodeOptions.push(process.env.NODE_OPTIONS);
     }
 
     if (cliOptions.import) {
-        nodeOptions.push('--import');
-        nodeOptions.push(cliOptions.import);
+        nodeOptions.push(`--import ${cliOptions.import}`);
+        // for load mcr.config.ts
         await import(cliOptions.import);
     } else if (cliOptions.require) {
-        nodeOptions.push('--require');
-        nodeOptions.push(cliOptions.require);
+        nodeOptions.push(`--require ${cliOptions.require}`);
+        // for load mcr.config.ts
         await import(cliOptions.require);
     }
 
+    return nodeOptions;
+};
+
+const getPreloadType = (nodeOptions) => {
+    const hasImport = nodeOptions.find((it) => it.includes('--import'));
+    if (hasImport) {
+        return '--import';
+    }
+    return '--require';
+};
+
+const checkRegisterFeature = () => {
+    const nv = process.versions.node;
+
+    // "module.register" added in Node.js: v20.6.0
+    // if (Util.cmpVersion(nv, '20.6.0') >= 0) {
+    //     return true;
+    // }
+    // but also added in: v18.19.0
+    const requiredNV = '18.19.0';
+    if (Util.cmpVersion(nv, requiredNV) < 0) {
+        Util.logInfo(`The current Node.js version "${nv}" does NOT support "module.register", it requires "${requiredNV}" or higher.`);
+        return false;
+    }
+
+    // could be < 20.6.0 but just ignore it, please using latest minor version
+
+    return true;
+};
+
+const initNodeOptions = async (cliOptions) => {
+
+    const supportRegister = checkRegisterFeature();
+    if (!supportRegister) {
+        return;
+    }
+
+    const nodeOptions = await getInitNodeOptions(cliOptions);
     // console.log(nodeOptions);
 
+    const preloadType = getPreloadType(nodeOptions);
+
     // export source after
-    const hasImport = nodeOptions.find((it) => typeof it === 'string' && it.includes('--import'));
-    if (hasImport) {
+    if (preloadType === '--import') {
         const importPath = getRegisterPath('register.mjs');
-        const hasImportPath = nodeOptions.find((it) => typeof it === 'string' && it.includes(importPath));
-        if (!hasImportPath) {
-            nodeOptions.push('--import');
-            nodeOptions.push(importPath);
-        }
+        nodeOptions.push(`--import ${importPath}`);
     } else {
         const requirePath = getRegisterPath('register.js');
-        const hasRequirePath = nodeOptions.find((it) => typeof it === 'string' && it.includes(requirePath));
-        if (!hasRequirePath) {
-            nodeOptions.push('--require');
-            nodeOptions.push(requirePath);
-        }
+        nodeOptions.push(`--require ${requirePath}`);
     }
 
     // console.log(nodeOptions);
+    const nodeOptionsStr = nodeOptions.join(' ');
+    Util.logDebug(`node options: ${EC.cyan(nodeOptionsStr)}`);
 
-    process.env.NODE_OPTIONS = nodeOptions.join(' ');
+    process.env.NODE_OPTIONS = nodeOptionsStr;
 
 };
 
@@ -86,6 +111,7 @@ const executeCommand = async (command, cliOptions) => {
 
     Util.logInfo(`Execute: ${EC.cyan(command)}`);
 
+    // before load config
     await initNodeOptions(cliOptions);
 
     // console.log(options);
@@ -133,7 +159,8 @@ const executeCommand = async (command, cliOptions) => {
 };
 
 process.on('uncaughtException', function(err) {
-    Util.logError(`Process uncaughtException: ${err.message || err}`);
+    Util.logError(`Process uncaughtException: ${err.message}`);
+    console.log(err.stack);
 });
 
 // the -- separator
@@ -154,7 +181,7 @@ process.argv.forEach((it) => {
 program
     .name('mcr')
     .description('CLI to generate coverage reports')
-    .version(version)
+    .version(version, '-v, --version', 'output the current version')
     .argument('[command]', 'command to execute')
     .allowUnknownOption()
     .option('-c, --config <path>', 'custom config file path')

package/lib/register/hooks.js

@@ -1,58 +1,58 @@
-const fs = require('fs');
-const path = require('path');
-const Util = require('../utils/util.js');
-const { convertSourceMap } = require('../packages/monocart-coverage-vendor.js');
-
-function saveFile(url, source, dir) {
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, {
-            recursive: true
-        });
-    }
-
-    const id = Util.calculateSha1(url + source);
-    const filePath = path.resolve(dir, `source-${id}.json`);
-    if (!fs.existsSync(filePath)) {
-        fs.writeFileSync(filePath, JSON.stringify({
-            url,
-            source
-        }));
-    }
-
-}
-
-function saveSource(url, loaded, dir) {
-
-    // filter node modules
-    if (url.startsWith('node:')) {
-        return;
-    }
-
-    const { source, format } = loaded;
-    if (typeof source !== 'string' || !['module', 'commonjs'].includes(format)) {
-        // no source or wrong format
-        return;
-    }
-
-    if (!convertSourceMap.mapFileCommentRegex.test(source)) {
-        // no sourcemap
-        return;
-    }
-
-    saveFile(url, source, dir);
-
-}
-
-async function load(url, context, nextLoad) {
-    const loaded = await nextLoad(url, context);
-    const dir = process.env.NODE_V8_COVERAGE;
-    if (dir) {
-        // only for coverage enabled
-        saveSource(url, loaded, dir);
-    }
-    return loaded;
-}
-
-module.exports = {
-    load
-};
+const fs = require('fs');
+const path = require('path');
+const Util = require('../utils/util.js');
+const { convertSourceMap } = require('../packages/monocart-coverage-vendor.js');
+
+function saveFile(url, source, dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, {
+            recursive: true
+        });
+    }
+
+    const id = Util.calculateSha1(url + source);
+    const filePath = path.resolve(dir, `source-${id}.json`);
+    if (!fs.existsSync(filePath)) {
+        fs.writeFileSync(filePath, JSON.stringify({
+            url,
+            source
+        }));
+    }
+
+}
+
+function saveSource(url, loaded, dir) {
+
+    // filter node modules
+    if (url.startsWith('node:')) {
+        return;
+    }
+
+    const { source, format } = loaded;
+    if (typeof source !== 'string' || !['module', 'commonjs'].includes(format)) {
+        // no source or wrong format
+        return;
+    }
+
+    if (!convertSourceMap.mapFileCommentRegex.test(source)) {
+        // no sourcemap
+        return;
+    }
+
+    saveFile(url, source, dir);
+
+}
+
+async function load(url, context, nextLoad) {
+    const loaded = await nextLoad(url, context);
+    const dir = process.env.NODE_V8_COVERAGE;
+    if (dir) {
+        // only for coverage enabled
+        saveSource(url, loaded, dir);
+    }
+    return loaded;
+}
+
+module.exports = {
+    load
+};

package/lib/register/hooks.mjs

@@ -1,3 +1,3 @@
-import { load } from './hooks.js';
-
-export { load };
+import { load } from './hooks.js';
+
+export { load };

package/lib/utils/util.js

@@ -128,8 +128,15 @@ const Util = {
         return htmlPathHandler();
     },
 
-    resolveNodeModule: (p) => {
+    resolveNodeModule: (id) => {
 
+        // for deno npm module
+        const mp = require.resolve(id);
+        if (fs.existsSync(mp)) {
+            return mp;
+        }
+
+        const p = `${it}/dist/${it}.js`;
         // root
         const cwd = path.resolve('node_modules', p);
         if (fs.existsSync(cwd)) {

package/lib/v8/v8.js

@@ -317,8 +317,8 @@ const handleV8HtmlReport = async (reportData, reportOptions, options) => {
     const htmlFile = path.basename(reportPath);
 
     // deps
-    const jsFiles = ['monocart-code-viewer', 'monocart-formatter', 'turbogrid'].map((it) => {
-        return Util.resolveNodeModule(`${it}/dist/${it}.js`);
+    const jsFiles = ['monocart-code-viewer', 'monocart-formatter', 'turbogrid'].map((id) => {
+        return Util.resolveNodeModule(id);
     });
 
     // package v8 ui

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monocart-coverage-reports",
-    "version": "2.7.8",
+    "version": "2.7.9",
     "description": "A code coverage tool to generate native V8 reports or Istanbul reports.",
     "main": "./lib/index.js",
     "bin": {
@@ -86,15 +86,15 @@
     "devDependencies": {
         "commander": "^12.0.0",
         "esbuild": "^0.20.2",
-        "eslint": "^8.57.0",
+        "eslint": "~8.57.0",
         "eslint-config-plus": "^1.0.6",
-        "eslint-plugin-html": "^8.0.0",
-        "eslint-plugin-vue": "^9.24.0",
+        "eslint-plugin-html": "^8.1.0",
+        "eslint-plugin-vue": "^9.24.1",
         "minimatch": "^9.0.4",
         "stylelint": "^16.3.1",
         "stylelint-config-plus": "^1.1.0",
         "supports-color": "^9.4.0",
-        "tsx": "^4.7.1",
+        "tsx": "^4.7.2",
         "ws": "^8.16.0"
     }
 }