Monocart Coverage Reports

V8 coverage is structured as an array of ScriptCoverage objects. Monocart Coverage Reports extends the standard V8 entries with additional metadata to make reporting easier.

Standard V8 Types:

• CoverageRange: Defines a startOffset, endOffset, and count for a specific code segment.
• FunctionCoverage: Contains a functionName, an array of ranges, and isBlockCoverage status.
• ScriptCoverage: Contains a scriptId, url, and an array of functions.

Monocart Extensions (added to each entry):

• url: Script URL or file path.
• type: Either "js" or "css".
• source: (JS) The actual source code text.
• sourceMap: (JS) The parsed sourcemap object.
• scriptOffset: (JS) Byte offset for the script wrapper (useful for vm modules).
• distFile: (JS) The distribution bundle file this source was unpacked from.
• empty: boolean - true if the entry was added via the all option (0% coverage).
• fake: boolean - true if the source is not original (e.g. compiled from .ts).

The CLI runs your program as a child process with NODE_V8_COVERAGE=dir until it exits gracefully, then generates reports from that directory.

Global Installation:

npm i monocart-coverage-reports -g
mcr node ./test/specs/node.test.js -r v8,console-details --lcov

Local Installation:

npm i monocart-coverage-reports
npx mcr node ./test/specs/node.test.js -r v8,console-details --lcov

Key CLI Features:

• Preloading Modules: Use --import <module> (for ESM, requires Node.js >= 18.19) or --require <module> (for CJS) to support TypeScript/JSX runtimes like tsx or ts-node.
• Environment Variables: Use --env [path] to load a .env file before the child process starts (requires Node.js >= 20.6).
• Argument Separation: Use -- to separate CLI arguments for mcr from arguments intended for the sub-command.
• Merging: Use the merge command to combine raw coverage data from multiple inputDirs without running a new process.

To collect coverage across multiple processes (e.g., different test stages), use the monocart-coverage-reports API to manage a shared cache. Data is stored in [outputDir]/.cache during the process and removed after report generation.

Workflow:

1. Main Process (Start): Initialize MCR and call mcr.cleanCache() to clear previous runs.
2. Sub-processes: In each testing stage, initialize MCR with the same options and call await mcr.add(coverageData) to append data to the cache.
3. Main Process (End): After all tests finish, call await mcr.generate() to produce the final report.

const MCR = require('monocart-coverage-reports');
const coverageOptions = require('path-to/same-options.js');

// 1. Main Process: Setup
const mcr = MCR(coverageOptions);
mcr.cleanCache();

// 2. Sub-process: Add data
// (In your test runner/worker)
const workerMcr = MCR(coverageOptions);
await workerMcr.add(coverageData);

// 3. Main Process: Finalize
await mcr.generate();

When coverage is generated in different environments (e.g., Node.js server vs. Browser client) or different test types (e.g., Jest unit tests vs. Playwright E2E tests), you may need to merge them.

Manual Merging Workflow:

1. Export raw coverage data from your test runners to specific directories using the raw report type.
2. Create a script using CoverageReport from monocart-coverage-reports.
3. Provide inputDir containing the paths to the raw data.
4. Use sourcePath to unify file paths if the same file has different relative paths in different environments.
5. Use entryFilter and sourceFilter to include/exclude specific files (e.g., node_modules).

CLI Merge Command:

mcr merge -r v8,console-details --inputDir ./coverage-reports/unit/raw,./coverage-reports/e2e/raw --outputDir ./coverage-reports/merged

const fs = require('fs');
const { CoverageReport } = require('monocart-coverage-reports');
const inputDir = [
    './coverage-reports/unit/raw',
    './coverage-reports/e2e/raw'
];
const coverageOptions = {
    name: 'My Merged Coverage Report',
    inputDir,
    outputDir: './coverage-reports/merged',

    // filter for both unit and e2e
    entryFilter: {
        '**/node_modules/**': false,
        '**/*': true
    },
    sourceFilter: {
        '**/node_modules/**': false,
        '**/src/**': true
    },
    
    sourcePath: (filePath, info) => {
        // Unify the file path for the same files
        return filePath.replace("unit-dist/", "").replace("e2e-dist/", "");
    },

    reports: [
        ['v8'],
        ['console-details']
    ]
};
await new CoverageReport(coverageOptions).generate();

By default, untested files are omitted from reports. To include them with 0% coverage, use the all option.

all can be:

• A string or array of strings representing directories.
• An object containing a dir (directory) and a filter (to specify file types like js or css).
• An object containing a transformer function to compile files (e.g., .ts or .vue) using tools like @swc/core so they can be analyzed by the AST parser.

// Simple directory inclusion
const coverageOptions = {
    all: './src',
};

// Advanced configuration with filtering and transformation
const coverageOptions = {
    all: {
        dir: ['./src'],
        filter: {
            '**/ignored-*.js': false,
            '**/*.html': false,
            '**/*.scss': "css",
            '**/*': true
        },
        transformer: async (entry) => {
            // Example using SWC to transform TypeScript
            const { code, map } = await swc.transform(entry.source, {
                filename: path.basename(entry.url),
                sourceMaps: true,
                isModule: true,
                jsc: { parser: { syntax: "typescript", jsx: true } }
            });
            entry.source = code;
            entry.sourceMap = JSON.parse(map);
        }
    }
};