monocart-coverage-reports 2.7.9 → 2.8.0

package/README.md

@@ -6,7 +6,9 @@
 ![](https://img.shields.io/github/license/cenfun/monocart-coverage-reports)
 ![](https://img.shields.io/github/actions/workflow/status/cenfun/monocart-coverage-reports/static.yml)
 
-> A code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
+🌐 English | [简体中文](README.zh-Hans.md)
+
+> A JavaScript code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
 
 * [Usage](#usage)
 * [Options](#options)
@@ -37,10 +39,11 @@
 * [Integration with Any Testing Framework](#integration-with-any-testing-framework)
 * [Integration Examples](#integration-examples)
     - [Playwright](#playwright)
+    - [CodeceptJS](#codeceptjs)
     - [Jest](#jest)
     - [Vitest](#vitest)
+    - [Puppeteer](#puppeteer)
     - [Cypress](#cypress)
-    - [CodeceptJS](#codeceptjs)
     - [WebdriverIO](#webdriverio)
     - [Storybook Test Runner](#storybook-test-runner)
     - [TestCafe](#testcafe)
@@ -202,6 +205,8 @@ const mcr = MCR(coverageOptions);
 ```
 
 ## Compare Reports
+> If the V8 data format is used for Istanbul reports, it will be automatically converted from V8 to Istanbul.
+
 | | Istanbul | V8 | V8 to Istanbul |
 | :--------------| :------ | :------ | :----------------------  |
 | Coverage data | [Istanbul](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) (Object) | [V8](#v8-coverage-data-format) (Array) | [V8](#v8-coverage-data-format) (Array) |
@@ -324,6 +329,8 @@ Possible solutions:
    - Taking coverage data and adding it to the report.
    - Example: 
    > node [./test/test-node-ins.js](./test/test-node-ins.js)
+   - vm Example (scriptOffset):
+   > node [./test/test-node-vm.js](./test/test-node-vm.js)
    
 - [CDP](https://chromedevtools.github.io/devtools-protocol/) API
     - Enabling [Node Debugging](https://nodejs.org/en/guides/debugging-getting-started/).
@@ -696,32 +703,7 @@ npx mcr node ./test/specs/node.test.js -r v8,console-details --lcov
 ```
 
 - CLI Options
-```sh
-Usage: mcr [options] [command]
-
-CLI to generate coverage reports
-
-Arguments:
-  command                      command to execute
-
-Options:
-  -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
-  -r, --reports <name[,name]>  coverage reports to use
-  -o, --outputDir <dir>        output dir for reports
-  -i, --inputDir <dir>         input dir for merging raw files
-  --entryFilter <pattern>      entry url filter
-  --sourceFilter <pattern>     source path filter
-  --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
-  --import <module>            preload module at startup
-  --require <module>           preload module at startup
-  -h, --help                   display help for command
-```
+see all options with running `mcr` or `mcr --help`
 
 - Use `--` to separate sub CLI args
 ```sh
@@ -744,24 +726,24 @@ Loading config file by priority:
 - `mcr.config.mjs`
 - `mcr.config.json` - json format
 - `mcr.config.ts` (requires preloading the ts execution module)
-- `.mcrrc.js`
-- `.mcrrc` - json format
 
 ## 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 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 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)
+- The `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)
+- Using `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.
+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, which is output to `./coverage-reports/unit/raw`
+- For example, we have `raw` coverage data from `unit test`, which is output to `./coverage-reports/unit/raw`. Unit test examples:
+    - `Jest` + [jest-monocart-coverage](https://github.com/cenfun/jest-monocart-coverage)
+    - `Vitest` + [vitest-monocart-coverage](https://github.com/cenfun/vitest-monocart-coverage)
 ```js
 const coverageOptions = {
     name: 'My Unit Test Coverage Report',
@@ -777,8 +759,13 @@ const coverageOptions = {
     ]
 };
 ```
-- 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`
+
+- We also have `raw` coverage data from `e2e test`, which is output to `./coverage-reports/e2e/raw`. E2E test examples:
+    - `Playwright` + [monocart-reporter](https://github.com/cenfun/monocart-reporter) with coverage API
+    - `Playwright` + `MCR`, see [playwright-coverage](https://github.com/cenfun/playwright-coverage)
+    - see more [Integration Examples](#integration-examples)
+
+- Then create a script `merge-coverage.js` to generate a merged report with option `inputDir`.
 ```js
 // merge-coverage.js
 const fs = require('fs');
@@ -828,7 +815,7 @@ const coverageOptions = {
 };
 await new CoverageReport(coverageOptions).generate();
 ```
-- All the command scripts are probably like following:
+- Running script `node path/to/merge-coverage.js` after all the tests are completed. All the command scripts are probably like following:
 ```json
 {
     "scripts": {
@@ -907,42 +894,46 @@ When `logging` is `debug`, the raw report data will be preserved in `[outputDir]
 ## Integration Examples
 
 ### [Playwright](https://github.com/microsoft/playwright)
-- [playwright-coverage](https://github.com/cenfun/playwright-coverage) - A Example for Playwright Coverage Reports
-- [monocart-reporter](https://github.com/cenfun/monocart-reporter) - A Playwright custom reporter, supports generating [Code Coverage Report](https://github.com/cenfun/monocart-reporter?#code-coverage-report)
-- Coverage for component testing:
+- [playwright-coverage](https://github.com/cenfun/playwright-coverage) - Example for Playwright coverage reports
+- [playwright-bdd-coverage](https://github.com/cenfun/playwright-bdd-coverage) - Example for Playwright BDD coverage reports
+- [monocart-reporter](https://github.com/cenfun/monocart-reporter) - Playwright custom reporter, supports generating [Code coverage report](https://github.com/cenfun/monocart-reporter?#code-coverage-report)
+- Coverage for component testing with `monocart-reporter`:
     - [playwright-ct-vue](https://github.com/cenfun/playwright-ct-vue)
     - [playwright-ct-react](https://github.com/cenfun/playwright-ct-react)
     - [playwright-ct-svelte](https://github.com/cenfun/playwright-ct-svelte)
 - Coverage for Next.js, both server side and client side:
     - [nextjs-with-playwright](https://github.com/cenfun/nextjs-with-playwright)
     - [nextjs-with-playwright-istanbul](https://github.com/cenfun/nextjs-with-playwright-istanbul)
+- see [Collecting V8 Coverage Data with Playwright](#collecting-v8-coverage-data-with-playwright)
+
+### [CodeceptJS](https://github.com/codeceptjs/CodeceptJS)
+- CodeceptJS is a [BDD](https://codecept.io/bdd/) + [AI](https://codecept.io/ai/) testing framework for e2e testing, it has integrated `MCR` since [v3.5.15](https://github.com/codeceptjs/CodeceptJS/releases/tag/3.5.15), see [plugins/coverage](https://codecept.io/plugins/#coverage). There's no need to use ~~[codeceptjs-monocart-coverage](https://github.com/cenfun/codeceptjs-monocart-coverage)~~ anymore.
 
 ### [Jest](https://github.com/jestjs/jest/)
-- [jest-monocart-coverage](https://github.com/cenfun/jest-monocart-coverage) - A Jest custom reporter for coverage reports
-- [jest-puppeteer-coverage](https://github.com/cenfun/jest-puppeteer-coverage) - A Jest Puppeteer Coverage Example
-- Example for Jest (unit) + Puppeteer (e2e) + Codecov: [maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js)
+- [jest-monocart-coverage](https://github.com/cenfun/jest-monocart-coverage) - Jest custom reporter for coverage reports
 
 ### [Vitest](https://github.com/vitest-dev/vitest)
-- [vitest-monocart-coverage](https://github.com/cenfun/vitest-monocart-coverage) - A Vitest custom provider module for coverage reports
+- [vitest-monocart-coverage](https://github.com/cenfun/vitest-monocart-coverage) - Vitest custom provider module for coverage reports
 
-### [Cypress](https://github.com/cypress-io/cypress)
-- [cypress-monocart-coverage](https://github.com/cenfun/cypress-monocart-coverage) - A Cypress plugin for coverage reports
+### [Puppeteer](https://github.com/puppeteer/puppeteer/)
+- [jest-puppeteer-coverage](https://github.com/cenfun/jest-puppeteer-coverage) - Example for Jest puppeteer coverage
+- [maplibre-gl-js](https://github.com/maplibre/maplibre-gl-js) - Example for Jest (unit) + Puppeteer (e2e) + Codecov
+- see [Collecting Raw V8 Coverage Data with Puppeteer](#collecting-raw-v8-coverage-data-with-puppeteer)
 
-### [CodeceptJS](https://github.com/codeceptjs/CodeceptJS)
-- CodeceptJS has integrated MCR from version [3.5.15](https://github.com/codeceptjs/CodeceptJS/releases/tag/3.5.15)
-- [codeceptjs-monocart-coverage](https://github.com/cenfun/codeceptjs-monocart-coverage) - A CodeceptJS plugin for coverage reports
+### [Cypress](https://github.com/cypress-io/cypress)
+- [cypress-monocart-coverage](https://github.com/cenfun/cypress-monocart-coverage) - Cypress plugin for coverage reports
 
 ### [WebdriverIO](https://github.com/webdriverio/webdriverio)
-- [wdio-monocart-service](https://github.com/cenfun/wdio-monocart-service) - A WebdriverIO service for coverage reports
+- [wdio-monocart-service](https://github.com/cenfun/wdio-monocart-service) - WebdriverIO service for coverage reports
 
 ### [Storybook Test Runner](https://github.com/storybookjs/test-runner)
-- [storybook-monocart-coverage](https://github.com/cenfun/storybook-monocart-coverage) - Storybook V8 Coverage Example
+- [storybook-monocart-coverage](https://github.com/cenfun/storybook-monocart-coverage) - Example for Storybook V8 coverage reports
 
 ### [TestCafe](https://github.com/DevExpress/testcafe)
-- [testcafe-reporter-coverage](https://github.com/cenfun/testcafe-reporter-coverage) - A TestCafe custom reporter for coverage reports
+- [testcafe-reporter-coverage](https://github.com/cenfun/testcafe-reporter-coverage) - TestCafe custom reporter for coverage reports
 
 ### [Selenium Webdriver](https://github.com/seleniumhq/selenium)
-- [selenium-webdriver-coverage](https://github.com/cenfun/selenium-webdriver-coverage) - Selenium Webdriver V8 Coverage Example
+- [selenium-webdriver-coverage](https://github.com/cenfun/selenium-webdriver-coverage) - Example for Selenium Webdriver V8 coverage reports
 
 ### [Mocha](https://github.com/mochajs/mocha)
 ```sh