monocart-coverage-reports
Advanced tools
Code coverage tool to generate native V8 reports or Istanbul reports.
entryFilter and sourceFilter to filter the results for V8 reportmcr CLIconst MCR = require('monocart-coverage-reports');
const options = {
outputDir: './coverage-reports',
reports: "v8"
}
const coverageReport = MCR(options);
await coverageReport.add(coverageData1);
await coverageReport.add(coverageData2);
const coverageResults = await coverageReport.generate();
console.log(coverageResults.summary);
v8 (V8 data only)
v8-json (V8 data only)
codecov (V8 data only)
Istanbul build-in reports
clovercoberturahtml
html-spa
jsonjson-summarylcovlcovonly
noneteamcitytexttext-lcovtext-summaryOther reports
console-summary shows coverage summary in console
raw only keep all original data, which can be used for other reports input with inputDir
Custom Reporter
{
reports: [
[path.resolve('./test/custom-istanbul-reporter.js'), {
type: 'istanbul',
file: 'custom-istanbul-coverage.text'
}],
[path.resolve('./test/custom-v8-reporter.js'), {
type: 'v8',
outputFile: 'custom-v8-coverage.json'
}],
[path.resolve('./test/custom-v8-reporter.mjs'), {
type: 'both'
}]
]
}
example: ./test/custom-istanbul-reporter.js, see istanbul built-in reporters' implementation for reference,
example: ./test/custom-v8-reporter.js
const MCR = require('monocart-coverage-reports');
const options = {
outputDir: './coverage-reports',
reports: [
// build-in reports
['console-summary'],
['v8'],
['html', {
subdir: 'istanbul'
}],
['json', {
file: 'my-json-file.json'
}],
'lcovonly',
// custom reports
// Specify reporter name with the NPM package
["custom-reporter-1"],
["custom-reporter-2", {
type: "istanbul",
option: "value"
}],
// Specify reporter name with local path
['/absolute/path/to/custom-reporter.js']
]
}
const coverageReport = MCR(options);
entryFilter and sourceFilter to filter the results for V8 reportWhen 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:
const coverageOptions = {
entryFilter: (entry) => entry.url.indexOf("main.js") !== -1,
sourceFilter: (sourcePath) => sourcePath.search(/src\//) !== -1
};
For example, checking thresholds:
const EC = require('eight-colors');
const coverageOptions = {
name: 'My Coverage Report',
outputDir: './coverage-reports',
onEnd: (coverageResults) => {
const thresholds = {
bytes: 80,
lines: 60
};
console.log('check thresholds ...', thresholds);
const errors = [];
const { summary } = coverageResults;
Object.keys(thresholds).forEach((k) => {
const pct = summary[k].pct;
if (pct < thresholds[k]) {
errors.push(`Coverage threshold for ${k} (${pct} %) not met: ${thresholds[k]} %`);
}
});
if (errors.length) {
const errMsg = errors.join('\n');
console.log(EC.red(errMsg));
// throw new Error(errMsg);
// process.exit(1);
}
}
}
mcr CLIThe CLI will run the program as a child process with
NODE_V8_COVERAGE=diruntil it exits gracefully, and generate the coverage report with the coverage data from thedir.
npm i monocart-coverage-reports -g
mcr "node ./test/test-node-env.js" -r v8,console-summary --lcov
npm i monocart-coverage-reports
npx mcr "node ./test/test-node-env.js" -r v8,console-summary --lcov
Usage: mcr [options] <command>
CLI to generate coverage reports
Arguments:
command command to execute
Options:
-V, --version output the version number
-c, --config <path> config path for options
-o, --outputDir <dir> output dir for reports
-r, --reports <name[,name]> coverage reports to use
-n, --name <name> report name for title
--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
-h, --help display help for command
mcr "node ./test/test-node-env.js" -c test/cli-options.js
| Istanbul | V8 | V8 to Istanbul | |
|---|---|---|---|
| Coverage data | Istanbul (Object) | V8 (Array) | V8 (Array) |
| Output | Istanbul reports | V8 reports | Istanbul reports |
| - Bytes | ❌ | ✅ | ❌ |
| - Statements | ✅ | ❌ | ☑️❔ |
| - Branches | ✅ | ☑️❔ | ☑️❔ |
| - Functions | ✅ | ✅ | ✅ |
| - Lines | ✅ | ✅ | ✅ |
| - Execution counts | ✅ | ✅ | ✅ |
| CSS coverage | ❌ | ✅ | ✅ |
| Minified code | ❌ | ✅ | ❌ |
❔ - Partial or conditional support
Istanbul Workflows
V8 Workflows
Before collecting Istanbul coverage data, It requires your source code is instrumented with Istanbul
window.__coverage__, example: test-istanbul.jsglobal.__coverage__sourcemap and do not compress/minify:
devtool: source-map and mode: development, example webpack.config-v8.jssourcemap: truesourcemap: true and minify: falsesourcemap: true and minify: falseCollecting coverage data with Chromium Coverage API:
If the
jsfile is loaded withaddScriptTagAPI, 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.
const jsCoverage = await page.coverage.stopJSCoverage();
jsCoverage.forEach((entry) => {
// read sourcemap for the my-dist.js manually
if (entry.url.endsWith('my-dist.js')) {
entry.sourceMap = JSON.parse(fs.readFileSync('dist/my-dist.js.map').toString('utf-8'));
}
});
await MCR(coverageOptions).add(jsCoverage);
Puppeteer does not provide raw v8 coverage data by default. A simple conversion is required, see example: ./test/test-puppeteer.js
await page.coverage.startJSCoverage({
// provide raw v8 coverage data
includeRawScriptCoverage: true
});
await page.goto(url);
const jsCoverage = await page.coverage.stopJSCoverage();
const rawV8CoverageData = jsCoverage.map((it) => {
// Convert to raw v8 coverage format
return {
source: it.text,
... it.rawScriptCoverage
};
}
Possible solutions:
NODE_V8_COVERAGE=dir
NODE_V8_COVERAGE=dir before the program running, the coverage data will be saved to the dir after the program exits gracefully.dir and generate coverage report.cross-env NODE_V8_COVERAGE=
.temp/v8-coverage-envnode ./test/test-node-env.js && node ./test/generate-node-report.js
V8 API + NODE_V8_COVERAGE
v8.takeCoverage(), it does not require waiting until the program exits gracefully.cross-env NODE_V8_COVERAGE=
.temp/v8-coverage-apinode ./test/test-node-api.js
Inspector API
CDP API
node --inspect=9229 ./test/test-node-cdp.js
Node Debugging + CDP + NODE_V8_COVERAGE + V8 API
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.Child Process + NODE_V8_COVERAGE
mcr CLIThe data will be added to [outputDir]/.cache, and the cache will be removed after reports generated.
const MCR = require('monocart-coverage-reports');
const options = require('path-to/same-options.js');
const coverageReport = MCR(options);
await coverageReport.add(coverageData1);
const MCR = require('monocart-coverage-reports');
const options = require('path-to/same-options.js');
const coverageReport = MCR(options);
await coverageReport.add(coverageData2);
// 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);
The following usage scenarios may require merging coverage reports:
First, using the raw report to export the original coverage data to the specified directory.
const coverageOptions = {
name: 'My Unit Test Coverage Report',
outputDir: "./coverage-reports/unit",
reports: [
['raw', {
// relative path will be "./coverage-reports/unit/raw"
outputDir: "raw"
}],
['v8'],
['console-summary']
]
};
Then, after all the tests are completed, generate a merged report with option inputDir:
import {CoverageReport} from 'monocart-coverage-reports';
const coverageOptions = {
name: 'My Merged Coverage Report',
inputDir: [
'./coverage-reports/unit/raw',
'./coverage-reports/e2e/raw'
],
outputDir: './coverage-reports/merged',
reports: [
['v8'],
['console-summary']
]
};
await new CoverageReport(coverageOptions).generate();
If the source file comes from the sourcemap, then its path is a virtual path. Using the sourcePath option to convert it.
const coverageOptions = {
sourcePath: (filePath) => {
// Remove the virtual prefix
const list = ['my-dist-file1/', 'my-dist-file2/'];
for (const str of list) {
if (filePath.startsWith(str)) {
return filePath.slice(str.length);
}
}
return filePath;
}
};
see example: ./test/test-merge.js
To ignore codes, use the special comment which starts with v8 ignore :
/* v8 ignore start */
function uncovered() {
}
/* v8 ignore stop */
/* v8 ignore next */
const os = platform === 'wind32' ? 'Windows' : 'Other';
const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
// v8 ignore next 3
if (platform === 'linux') {
console.info('hello linux');
}
// Coverage data for a source range.
export interface CoverageRange {
// JavaScript script source offset for the range start.
startOffset: integer;
// JavaScript script source offset for the range end.
endOffset: integer;
// Collected execution count of the source range.
count: integer;
}
// Coverage data for a JavaScript function.
/**
* @functionName can be an empty string.
* @ranges is always non-empty. The first range is called the "root range".
* @isBlockCoverage indicates if the function has block coverage information.
If this is false, it usually means that the functions was never called.
It seems to be equivalent to ranges.length === 1 && ranges[0].count === 0.
*/
export interface FunctionCoverage {
// JavaScript function name.
functionName: string;
// Source ranges inside the function with coverage data.
ranges: CoverageRange[];
// Whether coverage data for this function has block granularity.
isBlockCoverage: boolean;
}
// Coverage data for a JavaScript script.
export interface ScriptCoverage {
// JavaScript script id.
scriptId: Runtime.ScriptId;
// JavaScript script name or url.
url: string;
// Functions contained in the script that has coverage data.
functions: FunctionCoverage[];
}
export type V8CoverageData = ScriptCoverage[];
see devtools-protocol ScriptCoverage and v8-coverage
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, Vitest, but it has two major problems:
const a = tf ? 'true' : 'false';
^ ^ ^
m1 p m2
m1andm2are two consecutive mappings,pis the position we looking for. However, we can only get the position of them1orm2if we don't fix it top. 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.
// 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
We implemented new converter instead of v8-to-istanbul:
| AST | V8 |
|---|---|
| AssignmentPattern | 🛇 Not Support |
| ConditionalExpression | ✔ Not Perfect |
| IfStatement | ✔ Not Perfect |
| LogicalExpression | ✔ Not Perfect |
| SwitchStatement | ✔ Not Perfect |
FAQs
A code coverage tool to generate native V8 reports or Istanbul reports.
The npm package monocart-coverage-reports receives a total of 148,230 weekly downloads. As such, monocart-coverage-reports popularity was classified as popular.
We found that monocart-coverage-reports demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.