monocart-coverage-reports 2.3.3 → 2.4.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![](https://img.shields.io/npm/v/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
 [![](https://badgen.net/npm/dw/monocart-coverage-reports)](https://www.npmjs.com/package/monocart-coverage-reports)
+![](https://img.shields.io/librariesio/github/cenfun/monocart-coverage-reports)
 ![](https://img.shields.io/github/license/cenfun/monocart-coverage-reports)
 ![](https://img.shields.io/github/actions/workflow/status/cenfun/monocart-coverage-reports/static.yml)
 
@@ -29,8 +30,8 @@
 * [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)
+* [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
 * [Integration](#integration) - Playwright, Jest, Vitest, Codecov, Coveralls, Sonar Cloud
-* [Istanbul Introduction](#istanbul-introduction)
 * [Thanks](#thanks)
 
 ## Usage
@@ -302,7 +303,7 @@ mcr "node ./test/test-node-env.js" -c test/cli-options.js
     - 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.
+> Sometimes, the sourcemap file cannot be successfully loaded with the `sourceMappingURL`, 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) => {
@@ -370,26 +371,32 @@ Possible solutions:
     - 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
+> The data will be added to `[outputDir]/.cache`, After the generation of the report, this data will be removed unless debugging has been enabled or a raw report has been used, see [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
+- Main process, before the start of testing
 ```js
+// clean previous cache before the start of testing (option)
 const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = MCR(options);
-await coverageReport.add(coverageData1);
+MCR(options).cleanCache();
 ```
 
-- sub process 2
+- Sub process 1, testing stage 1
 ```js
 const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
-const coverageReport = MCR(options);
-await coverageReport.add(coverageData2);
+await MCR(options).add(coverageData1);
+```
+
+- Sub process 2, testing stage 2
+```js
+const MCR = require('monocart-coverage-reports');
+const options = require('path-to/same-options.js');
+await MCR(options).add(coverageData2);
 ```
 
-- main process
+- Main process, after the completion of testing
 ```js
-// after all sub processes finished
+// generate coverage reports after the completion of testing
 const MCR = require('monocart-coverage-reports');
 const options = require('path-to/same-options.js');
 const coverageReport = MCR(options);
@@ -399,10 +406,11 @@ 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 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 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.
 
+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.
 ```js
 const coverageOptions = {
@@ -478,7 +486,7 @@ const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
 
 // v8 ignore next 3
 if (platform === 'linux') {
-    console.info('hello linux');
+    console.log('hello linux');
 }
 ```
 
@@ -577,6 +585,25 @@ We implemented new converter instead of v8-to-istanbul:
 | LogicalExpression     | ✔ Not Perfect | 
 | SwitchStatement       | ✔ Not Perfect | 
 
+## Debug for Coverage and Sourcemap
+> Sometimes, the coverage is not what we expect. The next step is to figure out why, and we can easily find out the answer step by step through debugging.
+- Start debugging for v8 report with option `logging: 'debug'`
+```js
+const coverageOptions = {
+    logging: 'debug',
+    reports: [
+        ['v8'],
+        ['console-summary']
+    ]
+};
+```
+When `logging` is `debug`, the raw report data will be preserved in `[outputDir]/.cache` or `[outputDir]/raw` if `raw` report is used. And the dist file will be preserved in the V8 list, and by opening the browser's devtool, it makes data verification visualization effortless.
+![](./test/debug-coverage.png)
+
+- Check sourcemap with [Source Map Visualization](https://evanw.github.io/source-map-visualization/)
+
+![](./test/debug-sourcemap.png)
+
 ## Integration
 - [monocart-reporter](https://github.com/cenfun/monocart-reporter) - A [Playwright](https://github.com/microsoft/playwright) custom reporter, supports generating [Code Coverage Report](https://github.com/cenfun/monocart-reporter?#code-coverage-report)
 - [jest-monocart-coverage](https://github.com/cenfun/jest-monocart-coverage) - A [Jest](https://github.com/jestjs/jest/) custom reporter for coverage reports
@@ -601,6 +628,12 @@ We implemented new converter instead of v8-to-istanbul:
     ```
 - [Coveralls](https://coveralls.io/)
     - [![Coverage Status](https://coveralls.io/repos/github/cenfun/monocart-coverage-reports/badge.svg?branch=main)](https://coveralls.io/github/cenfun/monocart-coverage-reports?branch=main)
+    ```js
+    const coverageOptions = {
+        outputDir: "./coverage-reports",
+        lcov: true
+    };
+    ```
     - Github Actions example:
     ```yml
     - name: Coveralls
@@ -627,13 +660,10 @@ We implemented new converter instead of v8-to-istanbul:
             -Dsonar.tests=test
             -Dsonar.exclusions=dist/*,packages/*
     ```
-
-
-## 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)
+- Integration with any testing framework
+    - First, you need to collect coverage data when any stage of the test is completed. Then, add the coverage data to the coverage report.
+    - Upon the completion of all tests, generate the coverage report. 
+    - see [Multiprocessing Support](#multiprocessing-support)
 
 ## Thanks
 - Special thanks to [@edumserrano](https://github.com/edumserrano)