diff --git a/playwright/code-coverage/raw-v8-coverage/README.md b/playwright/code-coverage/raw-v8-coverage/README.md index 2049f11..763b0e0 100644 --- a/playwright/code-coverage/raw-v8-coverage/README.md +++ b/playwright/code-coverage/raw-v8-coverage/README.md @@ -1,66 +1,43 @@ -# Playwright Raw V8 Coverage - -- **Framework:** `playwright` -- **Use case:** `features/coverage` -- **Source repository:** https://github.com/currents-dev/blog-playwright-coverage-demo - -## What this example does - -A tiny demo project that accompanies the Currents blog post **“How To Measure Code Coverage in Playwright Tests”** and demonstrates collecting **JS + CSS coverage** using Playwright’s `page.coverage` APIs (Chromium-only). - -## How this example is used - -- Install deps: `npm install` (repo uses `@playwright/test`, `http-server`, `typescript`). -- Start a static server on port **5173**: `npm run dev` (runs `npx http-server -c-1 -p 5173 .`). -- Run tests (Chromium project): `npm test` (`playwright test --project=chromium`). -- The Playwright test writes raw coverage JSON files into `coverage/raw/` (e.g. `js.json`, `css.json`, plus `*-invalid.json` variants). - -## What scenarios are included - -- **Coverage test file** - - `tests/coverage.spec.ts` contains **two flows**: - - “happy path” (fills qty/price, calculates total, loads items) + writes `coverage/raw/js.json` + `coverage/raw/css.json` - - “error path” (negative qty) + writes `js-invalid.json` + `css-invalid.json` -- **Minimal demo app code** - - `src/app.js` wires DOM events, validation, calculation, and “load items” behavior. - - `src/utils/math.js` includes deliberately uncovered branches (`qty === 0`) + an unused `legacyDiscount()` to show uncovered code. - - `src/services/api.js` fetches `/api/items` (tests stub this route). - - `src/ui/validate.js` validates numbers + negative inputs. - - `styles.css` includes `.hidden` and `.error` to show CSS coverage. -- **Sample raw coverage outputs checked into the repo** - - `coverage/raw/js.json` and `coverage/raw/css.json` are present and show the raw V8 coverage format produced by Playwright. -- **Config** - - `playwright.config.ts` runs **only Chromium** because coverage APIs work only there. - -## How to implement this in your own project - -1. Start from the copied source markdown files in this folder and identify the exact config files/scripts used. -2. Create or reuse a Currents project, then configure credentials through environment variables (`CURRENTS_RECORD_KEY`, `CURRENTS_PROJECT_ID`). -3. Replicate the framework + CI integration pattern shown in the source docs for this use case (reporter/plugin wiring, CI command, and build ID strategy). -4. Run the same local commands from the source docs first, then execute the CI variant to confirm dashboard reporting works end-to-end. -5. After validation, adapt the pattern to your repository structure while keeping secrets in env vars and preserving the same reporting/orchestration flow. - -### Implementation notes from the audit - -1. **Add a README** - - Right now there’s no README in the repo root; without the blog post, it’s not self-explanatory. -2. **Make `npm test` “just work” by starting the server automatically** - - Add Playwright `webServer` config (or a `start-server-and-test` script) so users don’t need two terminals or guess that port 5173 must be running. (Today tests assume `http://localhost:5173` is already up.) -3. **Add a “generate HTML coverage report” step** - - The repo collects raw coverage JSON, but doesn’t include a script/tooling to convert it into HTML/LCOV (e.g., v8-to-istanbul + nyc) even though that’s the typical “next step” users expect. -4. **Reformat source files** - - Many files are committed as single-line/minified (package.json, config, JS/TS), which makes copying/learning harder. -5. **Add a CI workflow** - - A simple GitHub Actions workflow running Chromium tests would make it easier to validate the example and reuse it. -6. **(Optional) Clarify relation to Currents** - - This repo is “for the blog article”; it doesn’t show uploading coverage to Currents. A README note like “this repo demonstrates collection; see X for Currents ingestion” would prevent confusion. - -## Source markdown copied into this folder - -- No source markdown files were found for this repository. - -## Repository content copied into this folder - -- Total tracked files copied: **17** -- Source repository does not include a root `README.md`. -- Path mapping: [`content-map.md`](content-map.md) +# Raw V8 coverage — developer notes (Currents) + +Use this folder to exercise Playwright’s Chromium `page.coverage` flow alongside **Currents [code coverage](https://docs.currents.dev/guides/coverage)**. The app is served as static files; tests assume `http://localhost:5173`. + +## Prerequisites + +- Node.js and npm +- A Currents project with [record key](https://docs.currents.dev/guides/record-key) and [project ID](https://docs.currents.dev/dashboard/projects/project-settings) (only if you are sending results to Currents) + +## Run locally (coverage files only) + +1. `npm install` +2. In one terminal: `npm run dev` (serves the app on port **5173**) +3. In another: `npm test` (`playwright test --project=chromium`) + +On success, the spec writes raw V8 payloads under `coverage/raw/` (e.g. `js.json`, `css.json`; invalid-path cases may emit `*-invalid.json`). Checked-in files in that directory are sample output, not a required step. + +**Note:** `playwright.config.ts` is Chromium-only on purpose (`page.coverage` is not available on Firefox/WebKit). + +## Wire up Currents (not included in this minimal config) + +This example ships with plain Playwright. To report to Currents, mirror the setup in [`../instrumented-coverage/`](../instrumented-coverage/): + +1. Add `@currents/playwright` (and `dotenv` if you load env from a file). +2. Set `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` in the environment (or `.env` for local runs). +3. Extend `defineConfig` with `CurrentsFixtures` / `CurrentsWorkerFixtures`, register `currentsReporter(...)`, and pass `currentsConfigOptions` including `coverage` (e.g. `coverage: { projects: true }` as in the instrumented example). +4. Set `use.baseURL` to `http://localhost:5173` so it matches `npm run dev`. + +For CLI/orchestrated runs, use the same `pwc` / `pwc-p` patterns described in the instrumented example README and the [Playwright + Currents](https://docs.currents.dev/getting-started/playwright/you-first-playwright-run) docs. + +## CI + +- Export `CURRENTS_RECORD_KEY` and `CURRENTS_PROJECT_ID` as protected variables or secrets. +- Start the static server before tests (same as local two-terminal flow), or add a `webServer` block in `playwright.config.ts` that runs `npm run dev` and waits on port 5173 so a single `playwright test` (or `pwc`) command is enough. + +## Reference + +- [Code coverage guide](https://docs.currents.dev/guides/coverage) +- Sibling example with Currents already wired: [`playwright/code-coverage/instrumented-coverage`](../instrumented-coverage/) + +## Licence + +MIT License