monocart-coverage-reports 2.6.4 → 2.7.0

package/README.md

@@ -7,7 +7,7 @@
 ![](https://img.shields.io/github/actions/workflow/status/cenfun/monocart-coverage-reports/static.yml)
 
 
-> Code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
+> A code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports. As early as 2017, V8 started offering native support for coverage data. However, we have essentially only been able to see coverage reports from Istanbul. Nowadays, we can directly generate V8 coverage reports with `monocart-coverage-reports`.
 
 * [Usage](#usage)
 * [Default Options](#default-options)
@@ -22,6 +22,7 @@
 * [Manually Resolve the Sourcemap](#manually-resolve-the-sourcemap)
 * [Collecting Raw V8 Coverage Data with Puppeteer](#collecting-raw-v8-coverage-data-with-puppeteer)
 * [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
+* [Collecting V8 Coverage Data with `CDPClient` API](#collecting-v8-coverage-data-with-cdpclient-api)
 * [Multiprocessing Support](#multiprocessing-support)
 * [Merge Coverage Reports](#merge-coverage-reports)
 * [Resolve `sourcePath` for the Source Files](#resolve-sourcepath-for-the-source-files)
@@ -38,6 +39,7 @@
     - [Playwright](#playwright)
     - [Jest](#jest)
     - [Vitest](#vitest)
+    - [Cypress](#cypress)
     - [CodeceptJS](#codeceptjs)
     - [WebdriverIO](#webdriverio)
     - [Storybook Test Runner](#storybook-test-runner)
@@ -72,14 +74,30 @@ await coverageReport.generate();
 
 ## Default Options
 - [lib/default/options.js](https://github.com/cenfun/monocart-coverage-reports/blob/main/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](https://github.com/cenfun/monocart-coverage-reports/blob/main/lib/index.d.ts)
 
 ## Available Reports
 
 > V8 build-in reports (V8 data only):
 
 - `v8`
-    - Browser: Build with webpack [V8](https://cenfun.github.io/monocart-coverage-reports/v8) and [Minify](https://cenfun.github.io/monocart-coverage-reports/minify); Build with [Rollup](https://cenfun.github.io/monocart-coverage-reports/rollup) and [Esbuild](https://cenfun.github.io/monocart-coverage-reports/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/)
-    - Node.js: Collect with [env](https://cenfun.github.io/monocart-coverage-reports/node-env), and also V8 [API](https://cenfun.github.io/monocart-coverage-reports/node-api), [Inspector](https://cenfun.github.io/monocart-coverage-reports/node-ins) and [CDP](https://cenfun.github.io/monocart-coverage-reports/node-cdp); Web server example: [koa](https://cenfun.github.io/monocart-coverage-reports/node-koa/)
+    - Features: 
+        - A Brand-New V8 Coverage Report User Interface
+        - Support for Native Byte Statistics
+        - Coverage for Any Runtime Code
+        - CSS Coverage Support
+        - Better Support for Sourcemap Conversion
+    - Demos:
+        - Browser: Build with webpack [V8](https://cenfun.github.io/monocart-coverage-reports/v8) and [Minify](https://cenfun.github.io/monocart-coverage-reports/minify); Build with [Rollup](https://cenfun.github.io/monocart-coverage-reports/rollup) and [Esbuild](https://cenfun.github.io/monocart-coverage-reports/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/)
+        - Node.js: Collect with [env](https://cenfun.github.io/monocart-coverage-reports/node-env), and also V8 [API](https://cenfun.github.io/monocart-coverage-reports/node-api), [Inspector](https://cenfun.github.io/monocart-coverage-reports/node-ins) and [CDP](https://cenfun.github.io/monocart-coverage-reports/node-cdp); Web server example: [koa](https://cenfun.github.io/monocart-coverage-reports/node-koa/)
 
 ![](./assets/v8.gif)
 
@@ -357,6 +375,8 @@ Options:
     - see [Collecting Raw V8 Coverage Data with Puppeteer](#collecting-raw-v8-coverage-data-with-puppeteer)
 - Node.js
     - see [Node.js V8 Coverage Report for Server Side](#nodejs-v8-coverage-report-for-server-side)
+- CDP
+    - see [Collecting V8 Coverage Data with `CDPClient` API](#collecting-v8-coverage-data-with-cdpclient-api)
 
 ## Manually Resolve the Sourcemap
 > 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.
@@ -436,6 +456,50 @@ Possible solutions:
 - [Child Process](https://nodejs.org/docs/latest/api/child_process.html) + NODE_V8_COVERAGE
     - see [`mcr` CLI](#mcr-cli)
 
+## Collecting V8 Coverage Data with `CDPClient` API
+- Work with node debugger `--inspect=9229`
+```js
+const MCR = require('monocart-coverage-reports');
+const client = await MCR.CDPClient({
+    port: 9229
+});
+await client.startJSCoverage();
+// run your test here
+const coverageData = await client.stopJSCoverage();
+```
+- Work with [Playwright CDPSession](https://playwright.dev/docs/api/class-cdpsession)
+```js
+const { chromium } = require('playwright');
+const MCR = require('monocart-coverage-reports');
+const browser = await chromium.launch();
+const page = await browser.newPage();
+const session = await page.context().newCDPSession(page);
+const client = await MCR.CDPClient({
+    session
+});
+// both js and css coverage
+await client.startCoverage();
+// run your test page here
+await page.goto("your page url");
+const coverageData = await client.stopCoverage();
+```
+- Work with [Puppeteer CDPSession](https://pptr.dev/api/puppeteer.cdpsession)
+```js
+const puppeteer = require('puppeteer');
+const MCR = require('monocart-coverage-reports');
+const browser = await puppeteer.launch({});
+const page = await browser.newPage();
+const session = await page.target().createCDPSession();
+const client = await MCR.CDPClient({
+    session
+});
+// both js and css coverage
+await client.startCoverage();
+// run your test page here
+await page.goto("your page url");
+const coverageData = await client.stopCoverage();
+```
+
 ## Multiprocessing Support
 > 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
@@ -746,6 +810,9 @@ const coverageOptions = {
 ### [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
 
+### [Cypress](https://github.com/cypress-io/cypress)
+- [cypress-monocart-coverage](https://github.com/cenfun/cypress-monocart-coverage) - A Cypress plugin for coverage reports
+
 ### [CodeceptJS](https://github.com/codeceptjs/CodeceptJS)
 - [codeceptjs-monocart-coverage](https://github.com/cenfun/codeceptjs-monocart-coverage) - A CodeceptJS plugin for coverage reports
 

package/lib/client/cdp-client.js

@@ -0,0 +1,146 @@
+
+const EC = require('eight-colors');
+
+const { WebSocket } = require('../packages/monocart-coverage-vendor.js');
+const Util = require('../utils/util.js');
+
+const CDPSession = require('./cdp-session.js');
+const CoverageClient = require('./coverage-client.js');
+
+const getDebuggerUrl = async (options) => {
+
+    const protocol = options.secure ? 'https' : 'http';
+
+    const url = `${protocol}://${options.host}:${options.port}/json/list`;
+    const [err, res] = await Util.request({
+        url,
+        timeout: options.timeout
+    });
+    if (err) {
+        return [err];
+    }
+
+    const targets = res.data;
+    if (!Util.isList(targets)) {
+        return [new Error(`Invalid response data: ${url}`)];
+    }
+
+    // console.log(targets);
+    const target = options.target(targets);
+    if (!target) {
+        return [new Error(`Not found target: ${url}`)];
+    }
+
+    return [null, target.webSocketDebuggerUrl];
+};
+
+const getCDPUrl = async (options) => {
+    if (options.url) {
+        return [null, options.url];
+    }
+
+    // get debugger url
+    const [err, debuggerUrl] = await getDebuggerUrl(options);
+    if (err) {
+        return [err];
+    }
+
+    return [null, debuggerUrl];
+
+};
+
+const getCDPSession = async (options) => {
+
+    if (options.session) {
+        return [null, options.session];
+    }
+
+    // create session
+    const [err, url] = await getCDPUrl(options);
+
+    return new Promise((resolve) => {
+
+        if (err) {
+            resolve([err]);
+            return;
+        }
+
+        const timeoutId = setTimeout(() => {
+            resolve([new Error(`Timeout to connect: ${url}`)]);
+        }, options.timeout);
+
+        Util.logDebug(`Connect to ${url}`);
+        const ws = new WebSocket(url, [], {
+            maxPayload: 256 * 1024 * 1024,
+            perMessageDeflate: false,
+            followRedirects: true,
+            ... options.ws
+        });
+
+        ws.once('error', (wsErr) => {
+            clearTimeout(timeoutId);
+            resolve([wsErr]);
+        });
+
+        ws.once('open', () => {
+            clearTimeout(timeoutId);
+            Util.logDebug(`${EC.green('Connected')} ${url}`);
+            const session = new CDPSession(ws);
+            resolve([null, session]);
+        });
+
+    });
+
+
+};
+
+
+const CDPClient = async (cdpOptions) => {
+
+    const defaultOptions = {
+        session: null,
+        url: null,
+        port: 9222,
+        host: 'localhost',
+        secure: false,
+        target: (targets) => {
+            // defaults to first page
+            const page = targets.find((it) => it.webSocketDebuggerUrl && it.type === 'page');
+            if (page) {
+                return page;
+            }
+            return targets.find((it) => it.webSocketDebuggerUrl);
+        },
+        ws: {},
+        timeout: 10 * 1000
+    };
+
+    if (typeof cdpOptions === 'string') {
+        cdpOptions = {
+            url: cdpOptions
+        };
+    }
+
+    const options = {
+        ... defaultOptions,
+        ... cdpOptions
+    };
+
+    const [err, session] = await getCDPSession(options);
+
+    return new Promise((resolve) => {
+
+        if (err) {
+            Util.logError(err);
+            resolve();
+            return;
+        }
+
+        const helper = new CoverageClient(session);
+        resolve(helper);
+
+    });
+
+};
+
+module.exports = CDPClient;

package/lib/client/cdp-session.js

@@ -0,0 +1,63 @@
+const { EventEmitter } = require('events');
+
+class CDPSession extends EventEmitter {
+    constructor(ws) {
+        super();
+        this.ws = ws;
+        this.requestId = 1;
+        this.requestCache = new Map();
+        ws.on('message', (data, isBinary) => {
+
+            const message = JSON.parse(data);
+            // console.log(message);
+
+            const { id, method } = message;
+            if (id) {
+                const request = this.requestCache.get(id);
+                this.requestCache.delete(id);
+                if (request) {
+                    request.resolve(message.result);
+                }
+                return;
+            }
+
+            if (method) {
+                this.emit(method, message.params, message.sessionId);
+            }
+
+        });
+    }
+
+    send(method, params) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws) {
+                reject(new Error('Invalid websocket'));
+                return;
+            }
+            const id = this.requestId++;
+            const message = {
+                id,
+                method,
+                params: params || {}
+            };
+            this.ws.send(JSON.stringify(message), (err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                this.requestCache.set(id, {
+                    resolve
+                });
+            });
+        });
+    }
+
+    detach() {
+        if (this.ws) {
+            this.ws.terminate();
+            this.ws = null;
+        }
+    }
+}
+
+module.exports = CDPSession;

package/lib/client/coverage-client.js

@@ -0,0 +1,280 @@
+const Util = require('../utils/util.js');
+
+const bindEvents = (target, events) => {
+    Object.keys(events).forEach((eventType) => {
+        target.on(eventType, events[eventType]);
+    });
+};
+
+const unbindEvents = (target, events) => {
+    Object.keys(events).forEach((eventType) => {
+        target.off(eventType, events[eventType]);
+    });
+};
+
+// keep same ranges with playwright
+// eslint-disable-next-line complexity
+const convertToDisjointRanges = (nestedRanges) => {
+    const points = [];
+    for (const range of nestedRanges) {
+        points.push({
+            offset: range.start,
+            type: 0,
+            range
+        });
+        points.push({
+            offset: range.end,
+            type: 1,
+            range
+        });
+    }
+    // Sort points to form a valid parenthesis sequence.
+    points.sort((a, b) => {
+        // Sort with increasing offsets.
+        if (a.offset !== b.offset) {
+            return a.offset - b.offset;
+        }
+        // All "end" points should go before "start" points.
+        if (a.type !== b.type) {
+            return b.type - a.type;
+        }
+        const aLength = a.range.end - a.range.start;
+        const bLength = b.range.end - b.range.start;
+        // For two "start" points, the one with longer range goes first.
+        if (a.type === 0) {
+            return bLength - aLength;
+        }
+        // For two "end" points, the one with shorter range goes first.
+        return aLength - bLength;
+    });
+
+    const hitCountStack = [];
+    const results = [];
+    let lastOffset = 0;
+    // Run scanning line to intersect all ranges.
+    for (const point of points) {
+        if (hitCountStack.length && lastOffset < point.offset && hitCountStack[hitCountStack.length - 1] > 0) {
+            const lastResult = results.length ? results[results.length - 1] : null;
+            if (lastResult && lastResult.end === lastOffset) {
+                lastResult.end = point.offset;
+            } else {
+                results.push({
+                    start: lastOffset,
+                    end: point.offset
+                });
+            }
+        }
+        lastOffset = point.offset;
+        if (point.type === 0) {
+            hitCountStack.push(point.range.count);
+        } else {
+            hitCountStack.pop();
+        }
+    }
+    // Filter out empty ranges.
+    return results.filter((range) => range.end - range.start > 1);
+};
+
+class CoverageClient {
+    constructor(session) {
+        this.session = session;
+    }
+
+    // =================================================================================================
+    async startJSCoverage() {
+        if (!this.session || this.enabledJS) {
+            return;
+        }
+        this.enabledJS = true;
+        this.scriptSources = new Map();
+        this.jsEvents = {
+            'Debugger.scriptParsed': (params) => {
+                const { scriptId } = params;
+                this.session.send('Debugger.getScriptSource', {
+                    scriptId
+                }).then((res) => {
+                    this.scriptSources.set(scriptId, res && res.scriptSource);
+                });
+            },
+            'Debugger.paused': () => {
+                this.send('Debugger.resume');
+            }
+        };
+
+        bindEvents(this.session, this.jsEvents);
+
+        await this.session.send('Debugger.enable');
+        await this.session.send('Debugger.setSkipAllPauses', {
+            skip: true
+        });
+
+        await this.session.send('Profiler.enable');
+        await this.session.send('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: true
+        });
+
+        // Util.logDebug('startJSCoverage');
+
+    }
+
+    async stopJSCoverage() {
+        if (!this.session || !this.enabledJS) {
+            return;
+        }
+
+        const profileResponse = await this.session.send('Profiler.takePreciseCoverage');
+        await this.session.send('Profiler.stopPreciseCoverage');
+        await this.session.send('Profiler.disable');
+        // await this.session.send('Debugger.disable');
+
+        unbindEvents(this.session, this.jsEvents);
+        this.jsEvents = null;
+
+        const jsCoverage = profileResponse.result;
+        // console.log('coverageList', coverageList);
+
+        jsCoverage.forEach((entry) => {
+            // anonymous url
+            entry.url = entry.url || '';
+            // add source
+            const source = this.scriptSources.get(entry.scriptId);
+            if (!source) {
+                Util.logDebug(`Not found js source: ${entry.url}`);
+            }
+            entry.source = source || '';
+        });
+
+        this.scriptSources.clear();
+        this.enabledJS = false;
+
+        return jsCoverage;
+    }
+
+    // =================================================================================================
+
+    async startCSSCoverage() {
+        if (!this.session || this.enabledCSS) {
+            return;
+        }
+        this.enabledCSS = true;
+        this.styleEntries = new Map();
+
+        this.cssEvents = {
+            'CSS.styleSheetAdded': (e) => {
+                const { sourceURL, styleSheetId } = e.header;
+
+                // anonymous url
+                const url = sourceURL || '';
+                this.session.send('CSS.getStyleSheetText', {
+                    styleSheetId
+                }).then((res) => {
+                    // add source
+                    const text = res && res.text;
+                    if (!text) {
+                        Util.logDebug(`Not found css source: ${url}`);
+                    }
+                    this.styleEntries.set(styleSheetId, {
+                        url,
+                        text: text || '',
+                        ranges: []
+                    });
+                });
+            }
+        };
+
+        bindEvents(this.session, this.cssEvents);
+
+        await this.session.send('DOM.enable');
+        await this.session.send('CSS.enable');
+        await this.session.send('CSS.startRuleUsageTracking');
+
+        // Util.logDebug('startCSSCoverage');
+    }
+
+    async stopCSSCoverage() {
+        if (!this.session || !this.enabledCSS) {
+            return;
+        }
+
+        const ruleTrackingResponse = await this.session.send('CSS.stopRuleUsageTracking');
+        await this.session.send('CSS.disable');
+        await this.session.send('DOM.disable');
+
+        unbindEvents(this.session, this.cssEvents);
+        this.cssEvents = null;
+
+        const cssCoverage = [];
+
+        if (ruleTrackingResponse) {
+            for (const usage of ruleTrackingResponse.ruleUsage) {
+                const entry = this.styleEntries.get(usage.styleSheetId);
+                if (entry) {
+                    entry.ranges.push({
+                        start: usage.startOffset,
+                        end: usage.endOffset,
+                        count: usage.used ? 1 : 0
+                    });
+                }
+            }
+            this.styleEntries.forEach((entry) => {
+                entry.ranges = convertToDisjointRanges(entry.ranges);
+                cssCoverage.push(entry);
+            });
+        }
+
+        this.styleEntries.clear();
+        this.enabledCSS = false;
+
+        return cssCoverage;
+    }
+
+    // =================================================================================================
+
+    async startCoverage() {
+        await Promise.all([
+            this.startJSCoverage(),
+            this.startCSSCoverage()
+        ]);
+    }
+
+    async stopCoverage() {
+        const [jsCoverage, cssCoverage] = await Promise.all([
+            this.stopJSCoverage(),
+            this.stopCSSCoverage()
+        ]);
+        return [... jsCoverage, ... cssCoverage];
+    }
+
+    // =================================================================================================
+    // write the coverage started by NODE_V8_COVERAGE to disk on demand
+    async writeCoverage() {
+        // // enable and start v8 coverage
+        await this.session.send('Runtime.enable');
+
+        //  write the coverage started by NODE_V8_COVERAGE to disk on demand
+        const res = await this.session.send('Runtime.evaluate', {
+            expression: 'new Promise(resolve=>{ require("v8").takeCoverage(); resolve(process.env.NODE_V8_COVERAGE); })',
+            includeCommandLineAPI: true,
+            returnByValue: true,
+            awaitPromise: true
+        });
+
+        await this.session.send('Runtime.disable');
+
+        return res.result.value;
+    }
+
+    // =================================================================================================
+    async close() {
+        if (!this.session) {
+            return;
+        }
+
+        await this.session.detach();
+        this.session = null;
+
+    }
+}
+
+module.exports = CoverageClient;