Skip to content

[CSR-3589] feat: added readme for v8 code coverage #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
miguelangaranocurrents wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[CSR-3589] feat: added readme for v8 code coverage #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 43 additions & 66 deletions playwright/code-coverage/raw-v8-coverage/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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