monocart-coverage-reports 2.2.0 → 2.2.1

package/README.md

@@ -11,7 +11,7 @@
 * [Usage](#usage)
 * [Default Options](#default-options)
 * [Available Reports](#available-reports)
-* [Multiprocessing Support](#multiprocessing-support)
+* [Using `entryFilter` and `sourceFilter` to filter the results for V8 report](#using-entryfilter-and-sourcefilter-to-filter-the-results-for-v8-report)
 * [onEnd Hook](#onend-hook)
 * [`mcr` CLI](#mcr-cli)
 * [Compare Reports](#compare-reports)
@@ -19,13 +19,14 @@
 * [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)
+* [Multiprocessing Support](#multiprocessing-support)
+* [Integration](#integration)
+* [Ignoring Uncovered Codes](#ignoring-uncovered-codes)
+* [Chromium Coverage API](#chromium-coverage-api)
+* [V8 Coverage Data Format](#v8-coverage-data-format)
 * [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)
-* [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)
 
@@ -54,6 +55,7 @@ console.log(coverageResults.summary);
         - 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/) 
+        - [anonymous](https://cenfun.github.io/monocart-coverage-reports/anonymous/) and [css](https://cenfun.github.io/monocart-coverage-reports/css/)
     - 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/)
@@ -105,37 +107,34 @@ const options = {
 const coverageReport = MCR(options);
 ```
 
-## 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
-
-
-## Multiprocessing Support
-The data will be added to `[outputDir]/.cache`, and the cache will be removed after reports generated.
-- sub process 1
-```js
-const MCR = require('monocart-coverage-reports');
-const options = require('path-to/same-options.js');
-const coverageReport = MCR(options);
-await coverageReport.add(coverageData1);
+## 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:
 ```
-
-- sub process 2
-```js
-const MCR = require('monocart-coverage-reports');
-const options = require('path-to/same-options.js');
-const coverageReport = MCR(options);
-await coverageReport.add(coverageData2);
+dist/main.js
+dist/vendor.js
+dist/something-else.js
 ```
-
-- main process
+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. 
+```
+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`.
+```
+> 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.
+```
+> src/index.js
+> src/components/app.js
+```
+Example:
 ```js
-// after all sub processes finished
-const MCR = require('monocart-coverage-reports');
-const options = require('path-to/same-options.js');
-const coverageReport = MCR(options);
-const coverageResults = await coverageReport.generate();
-console.log(coverageResults.summary);
+const coverageOptions = {
+    entryFilter: (entry) => entry.url.indexOf("main.js") !== -1,
+    sourceFilter: (sourcePath) => sourcePath.search(/src\//) !== -1
+};
 ```
 
 ## onEnd Hook
@@ -170,6 +169,7 @@ const coverageOptions = {
 ```
 
 ## `mcr` CLI
+> The CLI will run the program as a [child process](https://nodejs.org/docs/latest/api/child_process.html) with `NODE_V8_COVERAGE=dir` until it exits gracefully, and generate the coverage report with the coverage data from the `dir`.
 - Global mode
 ```sh
 npm i monocart-coverage-reports -g
@@ -201,7 +201,7 @@ Options:
   --lcov                       generate lcov.info file
   -h, --help                   display help for command
 ```
-- Using configuration file for more options
+- Using configuration file for more [options](#default-options)
 ```sh
 mcr "node ./test/test-node-env.js" -c test/cli-options.js
 ```
@@ -234,139 +234,103 @@ mcr "node ./test/test-node-env.js" -c test/cli-options.js
 ## 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)
+    - 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)
+    - 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 coverage data from `global.__coverage__`
 
 ## Collecting V8 Coverage Data
 - For source code: enable `sourcemap` and do not compress/minify:
-    - Webpack: build 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: 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` 
+    - [webpack](https://webpack.js.org/configuration/): `devtool: source-map` and `mode: development`, example [webpack.config-v8.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/test/webpack.config-v8.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`
 - Browser (Chromium Only)
-    > 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)
+    > 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)
 - Node.js
-    > see [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
+    - see following [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
 
 
 ## Node.js V8 Coverage Report for Server Side
 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:
+- [NODE_V8_COVERAGE](https://nodejs.org/docs/latest/api/cli.html#node_v8_coveragedir)=`dir`
+    - Sets Node.js env `NODE_V8_COVERAGE`=`dir` before the program running, the coverage data will be saved to the `dir` after the program exits gracefully.
+    - 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)
 
 - [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:
+    - Writing the coverage started by NODE_V8_COVERAGE to disk on demand with `v8.takeCoverage()`, it does not require waiting until the program exits gracefully.
+    - Example:
     > cross-env NODE_V8_COVERAGE=`.temp/v8-coverage-api` node [./test/test-node-api.js](./test/test-node-api.js)
 
-- [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
    - 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)
+   - Taking coverage data and adding it to the report.
+   - Example: 
+   > node [./test/test-node-ins.js](./test/test-node-ins.js)
    
 - [CDP](https://chromedevtools.github.io/devtools-protocol/) API
-    - Enabling [Node Debugging](https://nodejs.org/en/guides/debugging-getting-started/)
+    - 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)
+    - Example: 
+    > node --inspect=9229 [./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 Debugging](https://nodejs.org/en/guides/debugging-getting-started) + CDP + NODE_V8_COVERAGE + V8 API
+    - When the program starts a server, it will not exit on its own, thus requiring a manual invocation of the `v8.takeCoverage()` interface to manually collect coverage data. Remote invocation of the `v8.takeCoverage()` interface can be accomplished through the `Runtime.evaluate` of the CDP.
+    - Example for [koa](https://github.com/koajs/koa) web server:
     > 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:
-```
-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. 
-```
-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`.
-```
-> 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.
-```
-> src/index.js
-> src/components/app.js
-```
-Example:
+- [Child Process](https://nodejs.org/docs/latest/api/child_process.html) + NODE_V8_COVERAGE
+    - see [`mcr` CLI](#mcr-cli)
+
+## Multiprocessing Support
+The data will be added to `[outputDir]/.cache`, and the cache will be removed after reports generated.
+- sub process 1
 ```js
-const coverageOptions = {
-    entryFilter: (entry) => entry.url.indexOf("main.js") !== -1,
-    sourceFilter: (sourcePath) => sourcePath.search(/src\//) !== -1
-};
+const MCR = require('monocart-coverage-reports');
+const options = require('path-to/same-options.js');
+const coverageReport = MCR(options);
+await coverageReport.add(coverageData1);
 ```
 
-## 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: 
+- sub process 2
 ```js
-const a = tf ? 'true' : 'false';
-               ^     ^  ^
-              m1     p  m2
+const MCR = require('monocart-coverage-reports');
+const options = require('path-to/same-options.js');
+const coverageReport = MCR(options);
+await coverageReport.add(coverageData2);
 ```
-> `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:
+- main process
 ```js
-functions.forEach(block => {
-    block.ranges.forEach((range, i) => {
-        if (block.isBlockCoverage) {
-            // 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: new CovFunction()
-                // Problem: no anonymous function
-            }
-        } else if (block.functionName) {
-            // v8-to-istanbul: new CovFunction()
-            // Problem: no anonymous function
-        }
-    }
-});
-// Problem: When the function or parent-level function is uncovered, then its sub-level functions will never be counted.
+// after all sub processes finished
+const MCR = require('monocart-coverage-reports');
+const options = require('path-to/same-options.js');
+const coverageReport = MCR(options);
+const coverageResults = await coverageReport.generate();
+console.log(coverageResults.summary);
 ```
-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 | 
+## 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
 
 ## Ignoring Uncovered Codes
 To ignore codes, use the special comment which starts with `v8 ignore `:
-- ignoring all until told
+- Ignoring all until stop
 ```js
 /* v8 ignore start */
 function uncovered() {
 }
 /* v8 ignore stop */
 ```
-- ignoring the next line or next N lines
+- Ignoring the next line or next N lines
 ```js
 /* v8 ignore next */
 const os = platform === 'wind32' ? 'Windows' : 'Other';
@@ -448,6 +412,52 @@ const rawV8CoverageData = jsCoverage.map((it) => {
 ```
 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:
+- 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` 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.
+
+- 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
+// Problem: When the function or parent-level function is uncovered, then its sub-level functions will never be counted.
+functions.forEach(block => {
+    block.ranges.forEach((range, i) => {
+        if (block.isBlockCoverage) {
+            // v8-to-istanbul: new CovBranch() 
+            // Problem: not every block is branch, and the first block could be function.
+            if (block.functionName && i === 0) {
+                // v8-to-istanbul: new CovFunction()
+                // Problem: no anonymous function
+            }
+        } else if (block.functionName) {
+            // v8-to-istanbul: new CovFunction()
+            // Problem: no anonymous function
+        }
+    }
+});
+```
+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 implemented new converter instead of v8-to-istanbul:
+- 1, Trying to fix the middle position if not found the exact mapping for the position.
+- 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 but close to reality.
+
+| AST                   | V8             | 
+| :---------------------| :------------- | 
+| AssignmentPattern     | 🛇 Not Support | 
+| ConditionalExpression | ✔ Not Perfect | 
+| IfStatement           | ✔ Not Perfect | 
+| LogicalExpression     | ✔ Not Perfect | 
+| SwitchStatement       | ✔ Not Perfect | 
+
 ## 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/utils/source-path.js

@@ -1,5 +1,5 @@
 const path = require('path');
-const { fileURLToPath } = require('url');
+const { fileURLToPath, pathToFileURL } = require('url');
 const Util = require('./util.js');
 
 const resolveUrl = (input) => {
@@ -36,7 +36,7 @@ const getSourcePath = (url, index = '', type = '') => {
 
     if (!url) {
         // anonymous scripts will have __playwright_evaluation_script__ as their URL.
-        url = ['file://anonymous', index ? `-${index}` : '', type ? `.${type}` : ''].join('');
+        url = pathToFileURL(['anonymous', index ? `-${index}` : '', type ? `.${type}` : ''].join('')).toString();
     }
 
     if (url.startsWith('file:')) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monocart-coverage-reports",
-    "version": "2.2.0",
+    "version": "2.2.1",
     "description": "Monocart coverage reports",
     "main": "./lib/index.js",
     "bin": {