monocart-coverage-reports 3.0.0 → 3.1.0

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/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/repository-map.md

@@ -17,7 +17,7 @@ Current exports: main API, `/register` source-capture preload, `/converter` and
 
 ## Checkout navigation
 
-Paths below are relative to the repository root and are generally **not shipped in npm** except `lib/`.
+Paths below are relative to the repository root and are generally **not shipped in npm** except `lib/`. When working in a source checkout, read its root `AGENTS.md` first for shared development rules and command side effects. That file is checkout-only; do not require it when using the installed skill.
 
 | Task | Read first | Related validation / examples |
 | --- | --- | --- |
@@ -33,7 +33,7 @@ Paths below are relative to the repository root and are generally **not shipped
 | Filters and normalized paths | `lib/utils/util.js`, `lib/utils/source-path.js`, `lib/generate.js` | `test/unit/output-filter.test.js`, `test/unit/source-path.test.js` |
 | Native V8/Istanbul generation | `lib/v8/v8.js`, `lib/istanbul/istanbul.js`, `lib/reports/` | `test/test-v8-and-istanbul.js`, custom reporter examples under `test/` |
 | Snapshots | `lib/utils/snapshot.js` | `test/check-snapshot.js`, `test/snapshot/` |
-| Report UI | `src/app/`, `src/vendor/`, `vite.config.mjs` | `npm run dev`, `npm run build` |
+| HTML assets and report UI | `lib/assets.js`, `lib/default/template.html`, `src/app/`, `src/vendor/`, `vite.config.mjs` | `npm run dev`, `npm run build`, `npm run test-runtime` |
 | Runtime compatibility / upgrade | `migrate-to-3.md`, `scripts/test-runtime.js` | `test/unit/node-version.test.js` |
 
 ## Development validation
@@ -48,7 +48,11 @@ npm run test-runtime
 
 Unit tests run directly with `node:test`, independently of the MCR CLI and coverage pipeline. For a focused test: `node --test test/unit/config.test.js`. Run `npm run test-unit-coverage` separately to collect coverage through `mcr test`; reports are written to `.temp/coverage-unit/`. For focused coverage: `node ./lib/cli.js test -c test/mcr.config.unit.js test/unit/config.test.js`. Browser/integration scripts may require downloaded browsers, built fixtures, local servers, and more time; inspect the relevant script before running it. `npm run build` invokes `postbuild` and builds test fixtures. `npm test` also runs integration/report generation and documentation generation; it is not a lightweight unit-only check.
 
-Avoid unrelated generated changes. `npm run lint` currently includes `--fix`; inspect its scope before invoking it. Do not edit generated `lib/packages/*`, `lib/assets.js`, `dist/`, `docs/`, or snapshots just to hide a source defect; use the project's build/generation workflow when those artifacts genuinely need updating.
+A fresh checkout needs `npm run build` to generate `lib/packages/` before tests that import these bundles. Rebuild after changing UI, template, or vendor-entry source.
+
+Avoid unrelated generated changes. `npm run lint` currently includes `--fix`; inspect its scope before invoking it. Use `npx --no-install eslint src/ test/unit/` for the usual scope without fixes, and explicit paths for other changed source. Do not hand-edit generated `lib/packages/*`, `dist/`, `docs/`, or `test/mock/*/dist/`; use the build/generation workflow. `lib/assets.js` is handwritten runtime source, not generated output. Snapshot baseline changes must be intentional and reviewed, never a way to hide a defect.
+
+Do not use `npm run eol` for validation: it removes the index and runs a hard reset. `npm run test:snap` overwrites baselines. `npm run publish` prepares a release through `npm version`, including its build hook and commit/tag creation; obtain explicit approval before release preparation or external writes.
 
 When changing public behavior, align implementation, `lib/index.d.ts`, default options, English/Chinese docs, migration notes where applicable, and focused tests. This skill supports MCR 3.x only. Validate the installed package separately when release compatibility matters; do not infer support for other major versions from these recipes.
 

package/lib/packages/chunks/chunk-RVOSNMVU.js

@@ -1,2 +0,0 @@
-import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
-var g=Object.create;var f=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var i=Object.getOwnPropertyNames;var j=Object.getPrototypeOf,k=Object.prototype.hasOwnProperty;var m=(a=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(a,{get:(b,c)=>(typeof require<"u"?require:b)[c]}):a)(function(a){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+a+'" is not supported')});var n=(a,b)=>()=>{try{return b||a((b={exports:{}}).exports,b),b.exports}catch(c){throw b=0,c}};var l=(a,b,c,e)=>{if(b&&typeof b=="object"||typeof b=="function")for(let d of i(b))!k.call(a,d)&&d!==c&&f(a,d,{get:()=>b[d],enumerable:!(e=h(b,d))||e.enumerable});return a};var o=(a,b,c)=>(c=a!=null?g(j(a)):{},l(b||!a||!a.__esModule?f(c,"default",{value:a,enumerable:!0}):c,a));export{m as a,n as b,o as c};