monocart-coverage-reports 3.0.0 → 3.2.0

package/lib/test/test-runner.js

@@ -0,0 +1,115 @@
+import path from 'node:path';
+import { Util } from '../utils/util.js';
+import { createTestResultsCollector, getRunnerOptions } from './test-results.js';
+
+// Also recognize `mcr -c config -- test targets -- runner-options` without
+// falling through to the shell's unrelated `test` command. Only MCR options
+// before the first separator are parsed in that form.
+const getTestCommand = (args, subArgs) => {
+    if (args[0] === 'test') {
+        return {
+            targets: args.slice(1), runnerArgs: subArgs.slice(1)
+        };
+    }
+    if (args.length || subArgs[1] !== 'test') {
+        return;
+    }
+    const remaining = subArgs.slice(2);
+    const index = remaining.indexOf('--');
+    if (index === -1) {
+        return {
+            targets: remaining, runnerArgs: []
+        };
+    }
+    return {
+        targets: remaining.slice(0, index), runnerArgs: remaining.slice(index + 1)
+    };
+};
+
+// Node owns target parsing, discovery and validation. Preserve each argument.
+const getTestTargets = (test) => {
+    if (!test || (Array.isArray(test) && !test.length)) {
+        Util.logInfo('No test targets configured; skipping tests.');
+        return;
+    }
+    return Array.isArray(test) ? test : [test];
+};
+
+const initTestResultsCollector = (coverageOptions, runnerArgs, childArgs) => {
+    // Read results before coverage generation, which may remove the cache.
+    const testResultsCollector = createTestResultsCollector(runnerArgs, coverageOptions.cacheDir);
+    // Internal options must stay before Node's end-of-options marker.
+    childArgs.splice(1 + getRunnerOptions(runnerArgs).length, 0, ... testResultsCollector.args);
+    return testResultsCollector;
+};
+
+const runTestEnd = async (testResultsCollector, onTestEnd) => {
+    if (!testResultsCollector) {
+        return 0;
+    }
+    try {
+        const metadata = testResultsCollector.readMetadata();
+        const failed = !metadata.complete;
+        if (failed) {
+            Util.logError('Node test report is incomplete');
+        }
+        let testResults;
+        if (typeof onTestEnd === 'function') {
+            testResults = testResultsCollector.read();
+            await onTestEnd(testResults);
+        }
+        // Publish only after a successful hook, so redaction reaches raw/debug
+        // artifacts. Never fall back to unredacted data if the hook throws.
+        testResultsCollector.publish(testResults);
+        return process.exitCode || (failed ? 1 : 0);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        Util.logError(`Node test report collection or onTestEnd failed: ${message}`);
+        return 1;
+    } finally {
+        // Do not export unfinished reporter output through coverage raw reports.
+        testResultsCollector.dispose();
+    }
+};
+
+const createTestRunner = (coverageOptions, runnerArgs = []) => {
+    const targets = getTestTargets(coverageOptions.test);
+    if (!targets) {
+        return;
+    }
+    const childArgs = ['--test', ... runnerArgs, ... targets];
+    let testResultsCollector;
+    let onTestEnd;
+    return {
+        initCoverageDir: (nodeV8CoverageDir) => {
+            // Tests may spawn children with a different working directory.
+            process.env.NODE_V8_COVERAGE = path.resolve(nodeV8CoverageDir);
+        },
+        onClose: async (generateCoverage) => {
+            const testExitCode = await runTestEnd(testResultsCollector, onTestEnd);
+            try {
+                const report = await generateCoverage();
+                if (!report) {
+                    throw new Error('No coverage report was generated');
+                }
+            } finally {
+                // A later coverage hook must not mask a test hook/collection failure.
+                if (testExitCode) {
+                    process.exitCode = process.exitCode || testExitCode;
+                }
+            }
+        },
+        execute: async (executeSubprocess, onClose) => {
+            // Always collect results; onStart may still configure the optional hook.
+            onTestEnd = coverageOptions.onTestEnd;
+            testResultsCollector = initTestResultsCollector(coverageOptions, runnerArgs, childArgs);
+            try {
+                return await executeSubprocess(process.execPath, childArgs, onClose);
+            } finally {
+                testResultsCollector?.dispose();
+            }
+        }
+    };
+};
+
+export { getTestCommand, createTestRunner };

package/lib/utils/source-path.js

@@ -31,8 +31,13 @@ const resolveAnonymousUrl = (url, index, type) => {
 
 const normalizePathDir = (sourcePath) => {
 
-    // decodeURI("%20") to space
-    let str = decodeURI(`${sourcePath}`);
+    let str = `${sourcePath}`;
+    try {
+        // decodeURI("%20") to space
+        str = decodeURI(str);
+    } catch {
+        // Preserve unresolvable URI text instead of aborting the report.
+    }
     str = str.replace(/\\/g, '/');
 
     // remove / of start, end or double, ./ ../
@@ -55,15 +60,21 @@ const betterFileURLToPath = (url) => {
     try {
         url = fileURLToPath(url);
     } catch (e) {
-        url = decodeURIComponent(url);
-        url = fileURLToPath(url);
+        try {
+            url = decodeURIComponent(url);
+            url = fileURLToPath(url);
+        } catch {
+            // in case that it cannot be safely resolved, we pass it verbatim.
+            return url;
+        }
     }
     return url;
 };
 
 const normalizeSourcePath = (sourceUrl, baseDir) => {
 
-    // includes anonymous and everything
+    // Best-effort report paths, not filesystem lookup paths. Leave special cases
+    // to sourcePath, which can use the original URL instead of guessing here.
 
     // file url
     if (sourceUrl.startsWith('file:')) {
@@ -120,11 +131,14 @@ const normalizeSourcePath = (sourceUrl, baseDir) => {
     return normalizePathDir(relPath);
 };
 
+const cssTypes = new Set(['css', 'less', 'sass', 'scss', 'styl', 'stylus', 'postcss', 'pcss', 'sss']);
+
 const getSourceType = (sourcePath) => {
     let ext = path.extname(sourcePath);
     let type = 'js';
     if (ext) {
-        ext = ext.slice(1);
+        // extensions are case-insensitive, e.g. `.CSS` or `.SCSS`
+        ext = ext.slice(1).toLowerCase();
         const reg = /^[a-z0-9]+$/;
         if (reg.test(ext)) {
             type = ext;
@@ -245,6 +259,7 @@ export {
     resolveAnonymousUrl,
     normalizeSourcePath,
     getSourceType,
+    cssTypes,
     getSourcePathReplacer,
     initIstanbulSourcePath,
     initSourceMapSourcesPath

package/lib/utils/util.js

@@ -226,7 +226,12 @@ const Util = {
         }
 
         // after decode url
-        str = decodeURIComponent(str);
+        try {
+            str = decodeURIComponent(str);
+        } catch {
+            // The raw path did not match and cannot be decoded. Let later rules run.
+            return false;
+        }
 
         if (str.includes(pattern)) {
             return true;

package/migrate-to-3.md

@@ -158,6 +158,10 @@ Custom reporter interfaces are unchanged: Istanbul reporters implement `execute(
 - `mcr test` is a new **optional** command; you do not have to replace your existing test runner.
 - `outputFilter` is a new **optional** filter, disabled by default. You do not have to replace `entryFilter` / `sourceFilter` with it.
 
+### Review test-result artifacts when upgrading to 3.2.0+
+
+Starting in 3.2.0, `mcr test` always collects structured test results, even without `onTestEnd`. Raw exports (including ZIP) and debug caches can now include `test-results-<id>.json`, containing test names, paths and error strings that may be sensitive. Review existing automatic artifact uploads and retention policies. Use [`onTestEnd`](README.md#ontestend--mcr-test-only) to redact persisted results before publication; terminal output and temporary files already written are not redacted. Raw imports still merge coverage only, not test results. Other commands and API calls do not collect these test results.
+
 ## Migration checklist
 
 - [ ] Upgrade Node.js in local, CI, container and relevant child-process environments.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "monocart-coverage-reports",
-    "version": "3.0.0",
+    "version": "3.2.0",
     "description": "A code coverage tool to generate native V8 reports or Istanbul reports.",
     "type": "module",
     "main": "./lib/index.js",
@@ -40,6 +40,7 @@
         "test-v8": "node ./test/test-v8.js",
         "test-puppeteer": "node ./test/test-puppeteer.js",
         "test-css": "node ./test/test-css.js",
+        "test-css-min": "node ./test/test-css-min.js",
         "test-minify": "node ./test/test-minify.js",
         "test-esbuild": "node ./test/test-esbuild.js",
         "test-rollup": "node ./test/test-rollup.js",
@@ -47,17 +48,17 @@
         "test-swc": "node ./test/test-swc.js",
         "test-v8-and-istanbul": "node ./test/test-v8-and-istanbul.js",
         "test-browser": "node ./test/test.js --browser",
-        "test-cli": "npx mcr node ./test/specs/node.test.js -c test/mcr.config.cli.js",
+        "test-cli": "node ./lib/cli.js node ./test/specs/node.test.js -c test/mcr.config.cli.js",
         "test-demo": "node ./test/test-demo.js",
         "test-merge": "node ./test/test-merge.js",
         "test-merge-istanbul": "node ./test/test-merge-istanbul.js",
         "test-merge-v8": "node ./test/test-merge-v8.js",
-        "test-merge-cli": "npx mcr merge -r console-details,v8 --inputDir .temp/code-coverage/raw --outputDir .temp/merge-cli",
+        "test-merge-cli": "node ./lib/cli.js merge -r console-details,v8 --inputDir .temp/code-coverage/raw --outputDir .temp/merge-cli",
         "test-client": "node ./test/test-client.js",
-        "test-cp": "npx mcr node test/test-cp.mjs --outputDir .temp/test-cp",
+        "test-cp": "node ./lib/cli.js node test/test-cp.mjs --outputDir .temp/test-cp",
         "test-all": "node ./test/test.js",
         "test-pr": "node --inspect=9230 ./test/test-pr.js",
-        "test": "npm run test-unit && npm run test-types && npx mcr npm run test-all -c test/mcr.config.mcr.js && node ./scripts/docs.js",
+        "test": "npm run test-unit && npm run test-types && node ./lib/cli.js npm run test-all -c test/mcr.config.mcr.js && node ./scripts/docs.js",
         "test:snap": "cross-env TEST_SNAPSHOT=true npm run test",
         "open": "node ./scripts/open.js",
         "eol": "git rm -rf --cached . && git reset --hard HEAD",
@@ -86,7 +87,7 @@
         "console-grid": "^2.2.4",
         "convert-source-map": "^2.0.0",
         "eight-colors": "^1.3.3",
-        "execa": "^10.2.0",
+        "execa": "^10.2.1",
         "istanbul-lib-coverage": "^3.2.2",
         "istanbul-lib-report": "^3.0.1",
         "istanbul-reports": "^3.2.0",
@@ -101,12 +102,12 @@
         "@actions/github": "^9.1.1",
         "@jsdevtools/coverage-istanbul-loader": "^3.0.5",
         "@rollup/plugin-commonjs": "^29.0.3",
-        "@rollup/plugin-typescript": "^12.3.0",
-        "@swc/core": "^1.16.18",
+        "@rollup/plugin-typescript": "^12.3.1",
+        "@swc/core": "^1.16.20",
         "@types/node": "^26.6.5",
         "@vitejs/plugin-vue": "^6.0.10",
         "async-tick": "^1.0.2",
-        "axios": "^1.20.0",
+        "axios": "^1.21.0",
         "babel-loader": "^10.1.1",
         "babel-plugin-istanbul": "^8.0.0",
         "cross-env": "^10.1.0",
@@ -116,20 +117,20 @@
         "eslint": "^10.13.0",
         "eslint-config-plus": "^2.1.0",
         "eslint-plugin-html": "^8.2.1",
-        "eslint-plugin-vue": "^10.11.1",
+        "eslint-plugin-vue": "^10.12.0",
         "find-up": "^8.0.0",
         "koa": "^3.2.1",
-        "koa-static-resolver": "^1.0.7",
-        "minimatch": "^10.2.6",
+        "koa-static-resolver": "^1.1.0",
+        "minimatch": "^11.0.2",
         "monocart-code-viewer": "^1.2.0",
         "monocart-formatter": "^3.0.1",
         "open": "^11.0.4",
         "playwright": "^1.64.1",
-        "postcss": "^8.5.30",
-        "puppeteer": "^25.14.0",
-        "rollup": "^4.64.9",
+        "postcss": "^8.5.32",
+        "puppeteer": "^25.16.0",
+        "rollup": "^4.65.1",
         "rollup-plugin-visualizer": "^7.1.1",
-        "sass": "^1.105.2",
+        "sass": "^1.106.1",
         "stylelint": "^17.16.0",
         "stylelint-config-plus": "^1.2.0",
         "supports-color": "^11.0.0",
@@ -140,14 +141,21 @@
         "turbogrid": "^3.4.2",
         "typescript": "^6.0.3",
         "vine-ui": "^4.2.0",
-        "vite": "^8.3.4",
-        "vite-plugin-css-injected-by-js": "^5.0.2",
-        "webpack": "^5.112.0"
+        "vite": "^8.3.5",
+        "vite-plugin-css-injected-by-js": "^5.0.3",
+        "webpack": "^5.112.2"
     },
     "engines": {
         "node": ">=22.15.0"
     },
-    "allowScripts": {
-        "puppeteer@25.8.0": true
+    "puppeteer": {
+        "skipDownload": true
+    },
+    "starfall": {
+        "outdate": {
+            "exclude": [
+                "typescript"
+            ]
+        }
     }
 }

package/skills/monocart-coverage-reports/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: monocart-coverage-reports
-description: Collect, generate, merge, and debug JavaScript, TypeScript, and CSS code coverage with monocart-coverage-reports (MCR) 3.x. Use for Node.js tests and mcr test, native V8 or Istanbul coverage, Playwright/Puppeteer Chromium coverage, CLI/configuration, sourcemaps, filters, untested files, CI reports and thresholds, and shard merging. Also applies to Chinese requests about Monocart、代码覆盖率、覆盖率报告、覆盖率合并、覆盖率过滤和源码映射.
+description: Collect, generate, merge, and debug JavaScript, TypeScript, and CSS code coverage with monocart-coverage-reports (MCR) 3.x. Use for Node.js tests and mcr test, native V8 or Istanbul coverage, Playwright/Puppeteer Chromium coverage, CLI/configuration, sourcemaps, filters, untested files, CI reports and thresholds, shard merging, and testing best practices. Also applies to Chinese requests about Monocart、MCR 最佳实践、代码覆盖率、覆盖率报告、覆盖率合并、覆盖率过滤和源码映射.
 ---
 
 # Coverage with Monocart Coverage Reports 3.x
@@ -23,7 +23,7 @@ Read the manifest for version, engines, exports, and types. Resolve bundled link
 ## Workflow and reference routing
 
 1. Inspect the host's scripts, runtime, MCR version, module format, and CI. Identify the desired source scope, reports, and parallel/sharded runs.
-2. Choose **one collection path**. Reuse the existing runner (`mcr -c mcr.config.mjs -- npm run test:unit`); use the quick start below only when a small Node task lacks a setup. Read [collection.md](references/collection.md) for browser/CDP, manual Node capture, or Istanbul data.
+2. Choose **one collection path**. For a new Node.js test setup, prefer **`node:test` + `mcr test`**; for browser tests, prefer **Playwright Test + MCR**, or **Playwright Test + monocart-reporter** (already integrates MCR). Read [MCR best practices](references/best-practices.md) when choosing a setup or implementing browser test fixtures. Reuse an existing runner (`mcr -c mcr.config.mjs -- npm run test:unit`) rather than forcing migration. Read [collection.md](references/collection.md) for browser/CDP, manual Node capture, or Istanbul data.
 3. Confirm sources/maps match the **exact tested build**. Choose input filtering (`entryFilter` + `sourceFilter`, or `filter`) for early exclusion/performance, or `outputFilter` for simpler final-path selection at the cost of processing unwanted inputs. Do not stack strategies automatically; output filtering cannot restore discarded inputs. Read [filtering-and-sourcemaps.md](references/filtering-and-sourcemaps.md) for examples, untested files, ignores, and debugging.
 4. Read [cli.md](references/cli.md) for config, argument boundaries, Node runner options, and hooks.
 5. Read [reports-and-ci.md](references/reports-and-ci.md) for thresholds, stale-result prevention, raw exports, validated shard merging, and snapshots.

package/skills/monocart-coverage-reports/references/best-practices.md

@@ -0,0 +1,218 @@
+# MCR best practices: test code and get useful coverage
+
+Use this module to choose a test setup and implement coverage collection. These recipes target **MCR 3.x and Node.js >= 22.15.0**. Reuse the host package manager, module format, test server, and installed tools. Do not upgrade dependencies or migrate an existing runner without approval.
+
+## 1. Choose the simplest collection path
+
+| Target | Default recommendation | Why |
+| --- | --- | --- |
+| New Node.js tests | **Node.js native test runner + `mcr test`** | Built-in assertions/tests, automatic native V8 JS coverage, no instrumentation or custom collector. |
+| Browser tests | **Playwright Test + MCR** | Runner-managed lifecycle and assertions; direct control over JS/CSS coverage reports. |
+| Browser tests with integrated reporting | **Playwright Test + monocart-reporter** | Already integrates MCR; combines test results and coverage reporting. |
+| Existing Jest/Vitest/Mocha/etc. | Keep the existing runner and its compatible collection integration | Adding coverage should not require rewriting working tests. |
+
+MCR collects/processes coverage and generates reports; the test runner executes assertions. Prefer native V8 collection where supported. Choose **one owner** for collection and final generation, rather than collecting the same execution through multiple integrations.
+
+## 2. Node.js: prefer `mcr test <targets>`
+
+Write tests with `node:test` and `node:assert/strict`. Cover meaningful outputs, errors, boundaries, and asynchronous behavior; use the real module rather than duplicating its implementation in a test. See the [complete module and test example](../SKILL.md#quick-start-test-your-code-and-get-coverage-3x).
+
+Install only if needed, using the host package manager:
+
+```sh
+npm install --save-dev monocart-coverage-reports@^3
+npx mcr test "./test/**/*.test.mjs" -r v8,console-summary
+```
+
+Replace the glob with actual test targets. For a repeatable project command, put `mcr test -c mcr.config.mjs` in an npm script such as `test:coverage`, with this config:
+
+```js
+// mcr.config.mjs
+export default {
+    test: ['./test/**/*.test.mjs'],
+    outputDir: './coverage-reports/node',
+    reports: ['v8', 'console-summary'],
+    outputFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    }
+};
+```
+
+This example selects final `src/` paths. Adapt it to the host's real source layout and verify the resulting file list; do not copy a filter that excludes the code under test. See [filtering and sourcemaps](filtering-and-sourcemaps.md) for early input filtering, transpiled sources, and `all` for files never loaded by tests.
+
+- `mcr test` invokes Node's native `--test`, automatically collects V8 JS coverage, and generates the selected reports. No manual `NODE_V8_COVERAGE`, coverage instrumentation, or API collector is needed.
+- Quote target globs. Forward Node runner flags after `--`, for example `npx mcr test "./test/**/*.test.mjs" -- --test-reporter=spec`.
+- Supply actual targets or config `test`; an empty target list skips testing and reporting.
+- Open `coverage-reports/index.html` for the first command, or `coverage-reports/node/index.html` for the config above. Verify expected sources and use uncovered branches to choose the next tests.
+- Failed tests still attempt report generation and remain failures. Do not suppress the exit status because an HTML file exists.
+- Existing runners may use `mcr -c mcr.config.mjs -- npm run test:unit` for Node V8 collection where compatible; avoid duplicate coverage providers. TypeScript needs the host's supported loader/build and matching sourcemaps, not an assumption that every TS syntax runs directly.
+
+See [CLI details](cli.md) for target overrides, configuration discovery, and argument boundaries.
+
+## 3. Browser: Playwright Test + MCR
+
+Run tests with **`playwright test`**, not `mcr test`. Wrapping Playwright's Node runner with the MCR CLI does **not** collect JavaScript executing inside browser pages.
+
+Use an automatic test-scoped fixture: start coverage before navigation, run real assertions, then stop and persist coverage before Playwright closes the page. This includes normal assertion failures. Generate once in the coordinator after every worker has finished writing.
+
+### Complete project example
+
+[playwright-coverage](https://github.com/cenfun/playwright-coverage) is a minimal **Playwright Test + MCR 3.x** example using plain JavaScript ESM. It tests browser-side application code, not the Playwright test scripts or a Node.js backend. Its [quick start](https://github.com/cenfun/playwright-coverage#quick-start-for-your-own-project) explains how to adapt these five files to your application:
+
+| File | Purpose |
+| --- | --- |
+| [fixtures.js](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.js) | Automatically start/stop page JS/CSS coverage and persist it with `add()`, including ordinary assertion failures. |
+| [mcr.config.js](https://github.com/cenfun/playwright-coverage/blob/main/mcr.config.js) | Share output/report options and keep `cleanCache: false` for workers. |
+| [global.setup.js](https://github.com/cenfun/playwright-coverage/blob/main/global.setup.js) | Clear the dedicated output directory before workers start. |
+| [global-teardown.js](https://github.com/cenfun/playwright-coverage/blob/main/global-teardown.js) | Generate once after all workers finish; reject missing/empty results. |
+| [playwright.config.js](https://github.com/cenfun/playwright-coverage/blob/main/playwright.config.js) | Select Chromium, register hooks, and configure the test runner. |
+
+For an existing application, merge these settings, configure its actual `baseURL` and server lifecycle, and import the extended `test` from the fixture. Do not change the application's module system just for coverage; use `.mjs` as below when appropriate. Browser dependencies and binaries must already be installed or their installation approved.
+
+The example's [Todo tests](https://github.com/cenfun/playwright-coverage/blob/main/tests/demo-todo-app.spec.js) serve real local HTML/JS/CSS through Playwright routes so the tests need no server or external website. They assert item creation, input clearing, whitespace handling, and text rendering. The routes and Todo assets are only an offline demo, not extra infrastructure to copy into your application.
+
+Run `npm test` in the example project. Inspect `coverage-reports/index.html` for code coverage, `coverage-reports/lcov.info` for CI, and `playwright-report/index.html` for test results. These are different artifacts: a passing test report alone does not validate coverage. For JS-only coverage, omit CSS collection; retain sourcemaps and select your real application source scope for bundled code.
+
+### Minimal parallel-safe integration
+
+This example assumes `@playwright/test` and MCR 3.x are installed, an approved Chromium binary is available, and the application server is already running. Reuse the host's server lifecycle/readiness checks (such as Playwright `webServer`); do not silently download browsers. Save these files at the host project root except the spec under `e2e/`. Merge the settings into an existing Playwright config rather than replacing its projects or hooks.
+
+```js
+// coverage-options.mjs
+export default {
+    outputDir: './coverage-reports/browser',
+    reports: ['v8', 'console-summary'],
+    // Workers share this cache. Only the coordinator may clean it.
+    cleanCache: false
+};
+```
+
+```js
+// coverage-setup.mjs
+import fs from 'node:fs';
+import options from './coverage-options.mjs';
+
+export default function globalSetup() {
+    // Dedicated to this run: never share with another active Playwright invocation.
+    // Remove old reports as well as cache, so missing collection cannot leave stale artifacts.
+    fs.rmSync(options.outputDir, { recursive: true, force: true });
+}
+```
+
+```js
+// coverage-fixtures.mjs
+import { test as base, expect } from '@playwright/test';
+import { MCR } from 'monocart-coverage-reports';
+import options from './coverage-options.mjs';
+
+export const test = base.extend({
+    coverage: [async ({ page, browserName }, use) => {
+        if (browserName !== 'chromium') {
+            // Other browser projects still run tests, but do not provide native coverage.
+            await use();
+            return;
+        }
+        await Promise.all([
+            page.coverage.startJSCoverage({ resetOnNavigation: false }),
+            page.coverage.startCSSCoverage({ resetOnNavigation: false })
+        ]);
+        try {
+            await use();
+        } finally {
+            const [js, css] = await Promise.all([
+                page.coverage.stopJSCoverage(),
+                page.coverage.stopCSSCoverage()
+            ]);
+            await MCR(options).add([...js, ...css]);
+        }
+    }, { auto: true }]
+});
+export { expect };
+```
+
+```js
+// coverage-teardown.mjs
+import { MCR } from 'monocart-coverage-reports';
+import options from './coverage-options.mjs';
+
+export default async function globalTeardown() {
+    const results = await MCR(options).generate();
+    if (!results || !results.files.length) {
+        throw new Error('No browser coverage generated: check fixtures and source scope');
+    }
+}
+```
+
+```js
+// playwright.config.mjs
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './e2e',
+    globalSetup: './coverage-setup.mjs',
+    globalTeardown: './coverage-teardown.mjs',
+    use: {
+        browserName: 'chromium',
+        baseURL: process.env.APP_URL || 'http://localhost:3000'
+    }
+});
+```
+
+```js
+// e2e/counter.spec.mjs
+import { test, expect } from '../coverage-fixtures.mjs';
+
+// Assumes a counter starting at 0; replace with your application's actual behavior.
+test('increments the counter when clicked', async ({ page }) => {
+    await page.goto('/');
+    const counter = page.getByTestId('counter');
+    await expect(counter).toHaveText('0');
+    await page.getByRole('button', { name: 'Increment', exact: true }).click();
+    await expect(counter).toHaveText('1');
+});
+```
+
+```sh
+npx playwright test
+```
+
+All covered specs must import the extended `test` from the fixture, not directly from `@playwright/test`. Inspect `coverage-reports/browser/index.html`. The example deliberately starts without a source filter: inspect actual bundle URLs and mapped paths, then select application sources using [filtering and sourcemaps](filtering-and-sourcemaps.md). Leaving vendor/runtime code in the report is not an accurate application coverage scope.
+
+### Lifecycle and scope limitations
+
+- Native `page.coverage` JS/CSS collection is **Chromium-only**. Firefox/WebKit require a separate instrumentation-based approach, such as collecting an Istanbul map; changing the reporter does not remove this limitation.
+- `resetOnNavigation: false` preserves coverage across navigations in the same page. The fixture covers only its `page`; extra pages/popups, workers, and the Node.js backend require explicit collection strategies. Tests must not close the covered page before fixture teardown.
+- Assertion failures normally run fixture teardown; crashes, forced termination, or timeouts may prevent collection. Retain the original failure and report collection failures rather than claiming coverage is complete.
+- Only the coordinator removes the dedicated output directory before workers start. Clearing only `.cache` would leave old HTML reports available for upload if collection fails. Never point `outputDir` at source code, merge inputs, or another run's output.
+- Do not call `generate()` or `cleanCache()` in each test/worker. `add()` persists data; the coordinator merges it during final generation. `cleanCache: true` in a shared worker would erase other tests' inputs.
+- Give independent CI runs/shards separate output directories. Export `raw` per shard and merge only after validating every expected shard; do not let independent global teardowns race on shared cache. See [reports and CI](reports-and-ci.md).
+
+## 4. Browser alternative: Playwright Test + monocart-reporter
+
+Choose this when you also want Monocart's Playwright test report, rather than maintaining a separate MCR reporting lifecycle. **monocart-reporter already integrates MCR**; do not add another MCR generator for the same data.
+
+1. Check the installed reporter's version, runtime requirements, bundled MCR version, and [official code coverage integration](https://github.com/cenfun/monocart-reporter#code-coverage-report). Do not assume its bundled MCR major matches a separate top-level installation or pass unsupported MCR 3.x options.
+2. Add `monocart-reporter` to the host's Playwright `reporter` configuration and configure its `coverage` options according to that release's documentation.
+3. Use an automatic Playwright fixture to start/stop page coverage around each test, as above, but submit the data through the reporter's documented coverage API with the current `testInfo`, instead of `MCR(options).add()`.
+4. Let the reporter own aggregation, cleanup, and final report generation. Do **not** also install the direct-MCR global setup/teardown above. Follow the reporter's own merge workflow for parallel jobs/shards.
+5. Run `npx playwright test` and verify both the test report and its coverage report contain current, intended data. Enabling a reporter alone does not start browser coverage collection.
+
+Use the version-matched official fixture rather than guessing reporter API signatures. Direct MCR is preferable when you need independent coverage lifecycle/options; the reporter is preferable when you want unified test and coverage reporting. Both use the same browser coverage limitations.
+
+## 5. Make coverage trustworthy
+
+- **Test behavior, not a percentage.** Add assertions for normal, boundary, error, and async paths. Use uncovered branches to find missing cases; do not weaken assertions or add unjustified ignores to satisfy a threshold.
+- **Match the exact build.** Keep tested source, bundle, and sourcemaps together. For TS/bundlers, verify mapped source and line positions; do not rebuild different artifacts before generating/merging coverage.
+- **Define the denominator.** Exclude only justified out-of-scope dependencies/generated assets, and use `all` when untouched application files must count as uncovered. A high percentage of loaded files alone does not prove the whole application is tested.
+- **Choose useful artifacts.** Start with `v8` and `console-summary`; add `lcovonly` for compatible CI services, `v8-json` for machine validation, or `raw` for later merging. Do not merge HTML, summaries, or percentages.
+- **Fail honestly.** Test, collection, report, and threshold failures must remain nonzero. `watermarks` only colors results; enforce thresholds explicitly. API callers must reject missing/empty results; CI must reject stale artifacts, not just check whether an old HTML file exists. See [strict CI and threshold recipes](reports-and-ci.md).
+- **Keep artifacts safe.** Use dedicated per-run output directories and retain useful reports on failures without masking status. Reports and raw/debug data may contain source code, private paths, and URLs; publish only with approval.
+
+### Delivery checklist
+
+- [ ] The chosen runner executes real assertions; collection starts before application execution/navigation.
+- [ ] The report contains the intended current sources, accurate mappings, and any required untested files.
+- [ ] Parallel tests do not clear one another's data; every required shard contributes to the merge.
+- [ ] Reports are fresh and nonempty, and test/report/threshold failure paths fail CI.
+- [ ] The user receives the run command, report location, source scope, and any collection limitations.

package/skills/monocart-coverage-reports/references/cli.md

@@ -76,17 +76,22 @@ export default {
 - `test` is CLI-only and ignored by ordinary commands/API. Existing runners remain supported through `mcr npm run ...`.
 - Test failure still attempts report generation and retains a nonzero exit status. A report-generation failure must fail CI too. Validate both paths.
 
+Starting in **3.2.0**, `mcr test` always collects structured test results, even without `onTestEnd`. Results follow the coverage cache lifecycle: normally cleaned after generation, retained in debug mode, or exported by `raw` (including ZIP). Raw imports merge coverage only, not test results. Test names, paths and error strings may contain secrets; review artifacts before uploading them. Use `onTestEnd` to redact persisted results before publication; this does not redact terminal output or temporary files already written.
+
 ## Hooks and shutdown
 
 | Hook | Scope / timing |
 | --- | --- |
 | `onStart(report)` | CLI child execution, before spawn |
+| `onTestEnd(testResults)` | 3.2.0+, `mcr test` only: after result collection, before publication, `onReady` and coverage generation; awaited even on assertion failure |
 | `onReady(report, nodeV8CoverageDir, subprocess)` | CLI, after child exits, before reading inputs |
 | `onEntry(entry)` | V8 input processing; can mutate entry |
 | `onEnd(results)` | After report generation; suitable for thresholds |
 
 Hooks may be async. Use `onReady` for a concrete flush/readiness condition when necessary, not an arbitrary permanent delay. API integrations manage their own process lifecycle; they do not receive CLI-only hooks automatically. Preserve test/child failures even if cleanup or reporting also fails.
 
+`onTestEnd` is optional and is not called for skipped runs, other commands or API calls. Mutate the result object to sanitize persisted raw/debug data. If it throws, test results are not published, the command fails, and coverage generation is still attempted. Missing/invalid reports fail without invoking the hook; incomplete reports are delivered with `complete: false` and also fail the command. See the [README hook contract](../../../README.md#ontestend--mcr-test-only) for the result schema and storage details. Save separate results outside `outputDir` if subsequent coverage cleanup could remove them.
+
 ## API use in CommonJS hosts
 
 MCR 3.x uses ESM, but a CommonJS host can use dynamic import without converting its entire application:

package/skills/monocart-coverage-reports/references/collection.md

@@ -15,6 +15,8 @@ Examples use ESM (`.mjs`, or `.js` under `"type": "module"`) and the MCR 3.x run
 
 Do not assume Chromium V8 coverage works in Firefox/WebKit or that it automatically covers every browser context, page, worker, or remote backend. Explicitly collect the runtimes/targets the task requires.
 
+For test suites, prefer the [Playwright Test fixture and lifecycle in MCR best practices](best-practices.md#3-browser-playwright-test--mcr), or its `monocart-reporter` alternative. The standalone script below is for custom collection outside a runner.
+
 ## Playwright Chromium: complete standalone script
 
 Assumes the application's test server is already running at `APP_URL` (or the local default). Prefer the host's existing server lifecycle and readiness checks.

package/skills/monocart-coverage-reports/references/reports-and-ci.md

@@ -128,6 +128,8 @@ const options = {
 };
 ```
 
+**Test-result privacy (3.2.0+):** `mcr test` adds `test-results-<id>.json` to raw exports (including ZIP) and retains it in debug caches, even without `onTestEnd`. Test names, paths and error strings can contain credentials or personal data. Review artifacts before uploading, and use [`onTestEnd`](cli.md#hooks-and-shutdown) to redact persisted results before publication. This does not redact terminal output or temporary files already written. Raw imports merge coverage only; test results are not merged.
+
 The relative raw directory becomes `coverage-reports/shard-1/raw`. Upload/download the **entire** raw directory, including source files. After every required job finishes, merge in a separate output directory:
 
 ```js