@reportforge/playwright-pdf 0.22.0 → 0.23.0

package/README.md

@@ -57,14 +57,16 @@ Three templates, one reporter. Every PDF is fully offline: fonts, charts, and sc
 - **Shard merging**: combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
 - **Notifications**: post pass/fail summaries to Slack, Teams, Discord, or email after each run; configurable trigger (`always` / `failure` / `success`) per channel; email and Discord support optional PDF attachment via `attachPdf`
 - **Flakiness trend**: top-N flakiest tests table with per-test dot sparkline across stored history runs in the `detailed` template; `flakinessTopN` option (default 5, `0` disables)
-- **Offline failure analysis**: sorts each failure into one of 7 root-cause buckets and renders a root-cause chip under each failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service: a small embedded classifier that updates over your existing license refresh; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
-- **On-device training**: teach the classifier your team's failures without any data leaving your machine. Label locally-collected samples (`npx @reportforge/playwright-pdf label-feedback`), then `train-model` trains and cross-validates a personal layer on-device; it activates only when it measurably beats the base model on your own labeled set (`evaluate-model` shows the comparison any time). Commit the model file to your repo via `failureAnalysis.localModelPath` to share it with CI. Training data, the trained model, and evaluation are all local files; the analysis code cannot even name a network primitive (CI-enforced source scan).
+- **Pass-rate trend**: cross-run trend chart from stored history; opt-in `remoteHistory` keeps the trend alive on ephemeral CI runners by storing aggregate numbers only (pass rate, counts, duration, verdict; no test titles or error text, and the branch name never travels in plaintext), with no extra network calls
+- **Offline failure analysis**: sorts each failure into one of 7 root-cause buckets and renders a root-cause chip under each failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service: a small embedded classifier with automatic updates; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
+- **On-device training**: teach the classifier your team's failures without any data leaving your machine. Label locally-collected samples (`npx @reportforge/playwright-pdf label-feedback`), then `train-model` trains and cross-validates a personal layer on-device; it activates only when it measurably beats the base model on your own labeled set (`evaluate-model` shows the comparison any time). Commit the model file to your repo via `failureAnalysis.localModelPath` to share it with CI. Training data, the trained model, and evaluation are all local files; the analysis code cannot even name a network primitive (enforced by an automated source audit).
 - `npx @reportforge/playwright-pdf export-feedback`: merges your locally-collected feedback (tokenized + redacted) into one CSV for review or moving between machines. Local file only; there is no upload.
 - **Rich execution capture**: opt-in "Steps to Reproduce" outline (a nested, copy-pasteable Markdown list of your `test.step`s and assertions; add `apiSteps` for the full click/fill/check trail), Node console tail, and trace/video links under each failed test in the defect log. Read straight from the Playwright step tree: no fixtures, no test-code changes. Enable via `capture` (`steps` / `apiSteps` / `console` / `evidence`); off by default.
 - **Configurable sections**: add or remove any report section per template via `sections`.
 - **Executive report brief band**: leads with a plain-language brief (trend + root causes) and one hero pass-rate number instead of a flat KPI grid
-- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
-- **Update notice**: when a newer reporter version is published, each run ends with one info line naming it and the update command; delivered over the existing license refresh, no extra network calls
+- **Data protection**: AES-256 password-protected PDFs (no external tools) and opt-in redaction of credentials/PII in report content and live streams
+- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a locally cached license between refreshes
+- **Update notice**: when a newer reporter version is published, each run ends with one info line naming it and the update command; no extra network calls
 
 ---
 
@@ -107,14 +109,14 @@ npx playwright test
 
 ### Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 20
 - `@playwright/test` ≥ 1.40 (peer dependency)
-- `puppeteer-core` ≥ 21 (peer dependency)
+- `puppeteer-core` ≥ 21 < 26 (peer dependency)
 - Chrome or Chromium installed on the machine
 
 ### Chrome setup
 
-The reporter auto-detects Chrome via `PUPPETEER_EXECUTABLE_PATH`, then system Chrome, then `chrome-finder`. Full per-OS instructions: [reportforge.org/docs/running-tests#chrome-setup](https://reportforge.org/docs/running-tests#chrome-setup).
+The reporter locates Chrome via the `puppeteerExecutablePath` option first, then the `PUPPETEER_EXECUTABLE_PATH` environment variable, then `chrome-finder` (system Chrome), then puppeteer-core's bundled Chromium if present. Full per-OS instructions: [reportforge.org/docs/running-tests#chrome-setup](https://reportforge.org/docs/running-tests#chrome-setup).
 
 **Windows**
 
@@ -186,7 +188,7 @@ All options are the second element of the reporter tuple.
 | `primaryColor` | `string` | `'#CC785C'` | Primary brand colour (3-, 6-, or 8-digit hex). Used for headers and accent bars. |
 | `accentColor` | `string` | `'#3F7D58'` | Accent brand colour (hex). Used for highlights and badges. |
 | `watermark` | `string` | n/a | Text to render as a diagonal watermark overlay from the Suite Breakdown page onward (summary/chart pages stay clean), e.g. `'CONFIDENTIAL'` or `'DRAFT'`. |
-| `pdfPassword` | `string` | n/a | Password-protect the generated PDF. Requires `qpdf` installed on the system. |
+| `pdfPassword` | `string` | n/a | Password-protect the generated PDF with AES-256, applied in-process with no external tools required. Also encrypts the failure-overflow sidecar (`*-failures.json.enc`; decrypt with `npx @reportforge/playwright-pdf decrypt-failures`). Recommended: `process.env.RF_PDF_PASSWORD`. |
 | `reportTitle` | `string` | `'Playwright Test Report'` | Custom title for the report cover page and running header. |
 | `projectName` | `string` | from `package.json` | Project or application name. Inferred from the `package.json` `name` field if absent. |
 | `open` | `boolean` | `false` | Open the generated PDF automatically after generation. For local use only; ignored in CI. |
@@ -199,13 +201,14 @@ All options are the second element of the reporter tuple.
 | `maxFileSizeMb` | `number` | `8` | Soft cap on the final PDF size in MB. If exceeded, the report is re-rendered once with the `'max'` compression preset. |
 | `shardResults` | `string \| string[]` | n/a | Glob or path array of Playwright JSON shard report files to merge into one PDF. See the Shard Merging docs. |
 | `notify` | `object` | n/a | Notification channels: `slack`, `teams` (each `{ url, enabled, on }`), `discord` (`{ url, enabled, on, attachPdf }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications docs. |
-| `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded Naive Bayes; no runtime network) with on-device personalization: label collected failures, then the `train-model` CLI trains + evaluates a local layer entirely on your machine; it activates only when it beats the base model, and nothing leaves the machine. Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `collectScope` (`blind-spots`\|`all`, default `blind-spots`), `autoUpdateModel` (default `true`), `localModel` (use the gate-passed on-device model, default `true`), `localModelPath` (share a team-trained model via a repo-committed file). See the Failure Analysis docs. |
+| `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded classifier; no runtime network) with on-device personalization: label collected failures, then the `train-model` CLI trains + evaluates a local layer entirely on your machine; it activates only when it beats the base model, and nothing leaves the machine. Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `collectScope` (`blind-spots`\|`all`, default `blind-spots`), `autoUpdateModel` (default `true`), `localModel` (use the gate-passed on-device model, default `true`), `localModelPath` (share a team-trained model via a repo-committed file). See the Failure Analysis docs. |
 | `capture` | `object` | `{}` (off) | Opt-in rich execution capture for the defect log (reporter-side; no fixtures, no test-code changes). Fields: `steps` (a copy-pasteable "Steps to Reproduce" outline built from the Playwright step tree; each row is a Markdown list line indented under its parent `test.step`, default `false`), `apiSteps` (include every top-level `pw:api` action (click/fill/check/goto) in the outline for a full action trail; without it the outline shows only `test.step` intent + `expect` assertions, default `false`), `console` (Node stdout/stderr tail, default `false`), `evidence` (trace/video file links, default `false`), `maxSteps` (default `50`), `maxConsoleLines` (default `50`). Renders in the Defect Log section of the `detailed` template. |
+| `redact` | `object` | `{ enabled: false }` | Opt-in masking of likely credentials/PII (passwords, tokens, API keys, Bearer/JWT values, emails, high-entropy strings) in report text and the live stream. `builtins` (default `true`) toggles the built-in patterns; `patterns` adds custom regexes (fully masked); `mask` sets the replacement text (default `'[REDACTED]'`). Screenshots cannot be redacted; use `includeScreenshots: false` for strict environments. |
 | `live` | `object` | `{}` (off) | Opt-in live test-execution streaming. When `enabled`, the reporter prints an unguessable watch link to the CI logs at run start and streams per-test progress to the hosted dashboard while tests run; all shards of one CI run converge on a single live view. Fields: `enabled` (default `false`), `runId` (override the auto-derived run id), `serverUrl` (override the streaming server), `steps` (`none`\|`failed`\|`intent`\|`all`, default `failed`; `intent` shows only your `test.step` names plus any failing step), `console` (stream stdout/stderr tails, default `false`), `flushMs` (batch debounce 500-10000, default `2000`). The PDF at the end of the run is unaffected. Requires an active subscription with the `live` entitlement. See the Live Runs docs. |
 | `historyFile` | `string` | `~/.reportforge/{key}/history.json` | Path to the history JSON file. Relative paths resolve from `cwd`. Enables pass-rate trending charts in the `detailed` template. |
 | `historySize` | `number` | `10` | Maximum number of test runs to keep in the history file (integer ≥ 2). Older runs are pruned on append. |
 | `showTrend` | `boolean` | `true` | Show the pass-rate sparkline and delta badge in the `detailed` template. Set to `false` to disable history tracking entirely. |
-| `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One request per run over the existing license connection carrying aggregate numbers only — no test titles, no error text; the branch name is sent as a hash. Falls back to the local history file on any failure. See the History docs. |
+| `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One small authenticated request per run carrying aggregate numbers only — no test titles, no error text, and the branch name never travels in plaintext. Falls back to the local history file on any failure. See the History docs. |
 | `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
 | `slowTestThreshold` | `number` | `10` | Minimum timed-test count before `SLOW` badges appear in the suite breakdown: below this, every test is trivially the "slowest" so badges stay hidden. On larger runs only genuine outliers (at least 2× the median test duration) are badged, so the badge stays rare. Set to `0` to drop the run-size gate (outliers still required). |
 | `requirementTagPattern` | `string` | `'^@?[A-Z][A-Z0-9]*-\\d+$'` | Regex deciding which tags count as requirement IDs in the Requirements Traceability section (`detailed` template). Matching tags (ticket shapes like `@ODP-5328`, `REQ-001`) get the traceability matrix; everything else (`@regression`, `@sanity`) collapses into a compact tag summary instead of repeating identical rows. Set to `''` to disable the split and list every tag in the matrix. |
@@ -238,7 +241,7 @@ reporter: [
 
 `steps: 'intent'` shows only your `test.step` names (plus any failing step): the cleanest, most readable trail. `'all'` adds every action and assertion beneath its parent step; `'failed'` (default) keeps intent + assertions + failures.
 
-Sharded runs need no extra config: the run id is derived from the run-shared CI identifier (e.g. `GITHUB_RUN_ID`), identical across every matrix shard. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
+Sharded runs need no extra config: every shard of one CI run converges on the same live view automatically. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
 
 Live streaming is best-effort and entitlement-gated: if the server is unreachable the run is unaffected, and an active subscription with the `live` feature is required. If you've configured Slack/Teams/Discord notifications, the watch link is also posted to those channels when the run starts.
 
@@ -315,6 +318,48 @@ The `on` trigger controls when the message fires:
 
 The summary includes pass rate, test counts, duration, and the report filename. Notifications require a valid license and fire after PDF generation (or after a PDF failure; you still get the ping).
 
+### Data Protection
+
+Two independent, opt-in controls: encrypt the PDF itself, and mask likely secrets before they ever reach report content.
+
+```typescript
+// playwright.config.ts
+reporter: [
+  ['@reportforge/playwright-pdf', {
+    pdfPassword: process.env.RF_PDF_PASSWORD,
+    redact: {
+      enabled: true,
+      patterns: ['MYCO_[A-Z0-9]+'],   // custom regexes, fully masked
+    },
+  }],
+],
+```
+
+**`pdfPassword`** encrypts the PDF with AES-256, applied in-process with no external tools required. When a failure-overflow sidecar is written (`maxInlineFailures` exceeded), it's encrypted too, as `{basename}-failures.json.enc`:
+
+```bash
+npx @reportforge/playwright-pdf decrypt-failures reports/2026-04-28-report-failures.json.enc --password=$RF_PDF_PASSWORD
+# or set RF_PDF_PASSWORD and drop --password
+```
+
+**`redact`** masks likely credentials and PII in error messages, stack traces, step titles, captured console output, test/suite titles, annotations, failure-analysis text, chart labels, and in the live watch stream. It runs after failure analysis, so classifier accuracy is unaffected. Built-in patterns (`builtins: true`, the default) catch:
+
+| Catches | Kept as-is | Example |
+|---|---|---|
+| `key=value` / `"key": "value"` credentials (`password`, `secret`, `token`, `apiKey`, `auth`, `credential`, `privateKey`, `accessKey`, `clientSecret`, …) | the key name | `password: "hunter2"` → `password: "[REDACTED]"` |
+| `Authorization: Bearer …` / `Basic …` | the scheme word | `Bearer eyJhbGc...` → `Bearer [REDACTED]` |
+| JWTs | n/a | `eyJhbGciOi...` |
+| Provider key prefixes | n/a | AWS `AKIA…`, GitHub `ghp_`/`gho_`/`github_pat_`, Slack `xox*`, OpenAI-style `sk-`, Razorpay `rzp_live_`/`rzp_test_`, Google `AIza…` |
+| URLs with embedded credentials | the username | `https://alice:hunter2@host` → `https://alice:[REDACTED]@host` |
+| Emails | first character + domain | `jsmith@example.com` → `j***@example.com` |
+| High-entropy strings (20+ mixed letters/digits) | n/a | tokens and keys with no recognizable prefix |
+
+Add your own with `patterns` (strings compiled as case-sensitive regexes with the `g` flag); custom matches are always fully masked. `mask` overrides the default replacement text (`'[REDACTED]'`).
+
+> **Screenshots cannot be redacted:** pixel content is opaque to text-based masking. Set `includeScreenshots: false` in strict environments.
+
+Full details at [reportforge.org/docs/advanced/security](https://reportforge.org/docs/advanced/security).
+
 ### Test History Trending
 
 After each run the reporter appends a summary entry to a local JSON file and renders a pass-rate sparkline + verdict row in the `detailed` template.
@@ -330,7 +375,7 @@ reporter: [['@reportforge/playwright-pdf', {
 }]]
 ```
 
-One request per run over the existing license connection, carrying aggregate numbers only (pass rate, counts, duration, verdict; no test titles, no error text — the branch name is sent as a hash). The server keeps the last 100 runs per project + branch and returns them for the chart; any failure falls back to the local file. The flakiness table stays local-only by design (it needs test titles, which never leave your machine). Bitbucket Pipelines users especially: Bitbucket caches are immutable once written, so `remoteHistory` is the practical path there.
+One small authenticated request per run, carrying aggregate numbers only (pass rate, counts, duration, verdict; no test titles, no error text, and the branch name never travels in plaintext). The server keeps roughly the last 100 runs per project + branch, expiring after 180 days, and returns them for the chart; any failure falls back to the local file. The flakiness table stays local-only by design (it needs test titles, which never leave your machine). Bitbucket Pipelines users especially: Bitbucket caches are immutable once written, so `remoteHistory` is the practical path there.
 
 **CI caching alternative** (keeps even aggregate numbers off the server): set `historyFile` to a project-relative path and cache it between runs:
 
@@ -439,7 +484,7 @@ reporter: [['@reportforge/playwright-pdf', {
 |---|---|
 | `coverPage` | Full-page cover: title, verdict badge, KPI stats strip, branch + commit |
 | `analysisOneliner` | One-line failure-analysis summary banner |
-| `releaseGate` | Ship/hold recommendation banner (APPROVED TO SHIP / HOLD) |
+| `releaseGate` | Ship/hold recommendation banner (APPROVED TO SHIP / HOLD, or a neutral NO TESTS RAN when the run executed zero tests) |
 | `summary` | KPI strip (total · passed · failed · timed-out · skipped · flaky), verdict, duration, pass rate, flaky callout |
 | `charts` | Pass-rate doughnut + stacked suite-results bar |
 | `trend` | Pass-rate trend line, run-history table, and flakiness table (rendered inside `charts`) |
@@ -450,6 +495,7 @@ reporter: [['@reportforge/playwright-pdf', {
 | `failureAnalysis` | Inline per-test root-cause chip under each failed test (category + representative error + match strength, from the offline classifier) |
 | `slowTests` | `SLOW` badge on the duration-ranked slowest tests, shown inline in the breakdown |
 | `defectLog` | `DEF-####` numbered failure table (severity, duration) + opt-in repro detail (`capture`) |
+| `briefBand` | Executive brief band: one plain-language sentence (trend delta + root causes) and a hero pass-rate stat |
 
 #### Display modifiers: tune a section that's on
 
@@ -468,7 +514,7 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 | Section | minimal | detailed | executive |
 |---|:-:|:-:|:-:|
 | `coverPage` | – | – | ✓ |
-| `analysisOneliner` | – | – | ✓ |
+| `analysisOneliner` | – | – | – |
 | `releaseGate` | ✓ | ✓ | ✓ |
 | `summary` | ✓ | ✓ | ✓ |
 | `charts` | – | ✓ | ✓ |
@@ -480,6 +526,7 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 | `failureAnalysis` | – | ✓ | – |
 | `slowTests` | – | ✓ | ✓ |
 | `defectLog` | – | ✓ | – |
+| `briefBand` | – | – | ✓ |
 | `passRate` | ✓ | ✓ | ✓ |
 | `fullEnvironment` | – | ✓ | – |
 | `retries` | ✓ | ✓ | – |
@@ -622,10 +669,10 @@ stage('Playwright Tests') {
 ReportForge ships a **hybrid offline-first** model:
 
 1. Paste your `RFSU-…` key into the config once (or set `RF_LICENSE_KEY`).
-2. On first run the reporter activates against the license server, receives a short-lived **Ed25519-signed JWT**, and caches it at `~/.reportforge/license.json`.
-3. Every subsequent run is **fully offline**: the cached JWT is verified locally against a public key bundled into the npm package. No network call.
-4. When the cache has less than 24 hours left, the reporter refreshes it in the background.
-5. Each subscription allows up to **25 active machines** in any rolling 30-day window. Machines that haven't run in 30 days are pruned automatically.
+2. On first run the reporter activates against the license server and caches a signed license at `~/.reportforge/license.json`.
+3. Every subsequent run is **fully offline**: the cached license is validated on-device. No network call.
+4. The reporter refreshes the cache automatically in the background before it expires.
+5. Each subscription allows up to **25 active machines**. Machines that haven't run in 30 days free up automatically.
 
 Cancel the subscription and the reporter keeps working until the end of the current billing period, then stops generating PDFs until you restart. **A license issue never aborts your test run**: the reporter logs a warning and skips PDF generation; your Playwright tests still pass.
 
@@ -675,8 +722,7 @@ Common issues:
 
 - **`Chrome/Chromium not found`** → install Google Chrome Stable; don't use the Ubuntu `chromium-browser` snap.
 - **Charts blank** → ensure `npm run bundle-chartjs` ran at build; the reporter waits up to 30s for `window.__chartsReady`.
-- **`pdfPassword` ignored** → requires `qpdf` on `PATH` (`apt install qpdf` / `brew install qpdf` / `choco install qpdf`).
-- **No PDF generated** → verify `RF_LICENSE_KEY` is set and your subscription is active. `RF_DEBUG=1` will show the activation result; missing key, expired subscription, network failure, or no JWT cache all skip PDF generation.
+- **No PDF generated** → verify `RF_LICENSE_KEY` is set and your subscription is active. `RF_DEBUG=1` will show the activation result; missing key, expired subscription, network failure, or no license cache all skip PDF generation.
 
 Full guide: [reportforge.org/docs/troubleshooting](https://reportforge.org/docs/troubleshooting).
 
@@ -694,7 +740,8 @@ Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
 - [Templates](https://reportforge.org/docs/templates): minimal, detailed, executive
 - [Live runs](https://reportforge.org/docs/advanced/live): stream per-test progress to a shared watch link
 - [Report Sections](https://reportforge.org/docs/configuration#report-sections): add or remove sections per template
-- [License & offline behaviour](https://reportforge.org/docs/licensing): JWT cache, machine cap, cancellation
+- [Data protection](https://reportforge.org/docs/advanced/security): password-encrypt PDFs and redact credentials/PII from report content
+- [License & offline behaviour](https://reportforge.org/docs/licensing): license cache, machine cap, cancellation
 - [Troubleshooting](https://reportforge.org/docs/troubleshooting): common issues and debug flags
 - [Changelog](https://reportforge.org/changelog): version history and release notes
 

package/SECURITY.md

@@ -40,8 +40,19 @@ Out of scope:
 
 - Denial of service / volumetric attacks.
 - Reports about the 25-machine licensing cap working as documented.
-- Vulnerabilities exclusively in third-party services we integrate
-  (Razorpay, Clerk, Vercel, Resend) — report those upstream.
+- Vulnerabilities exclusively in third-party services we integrate (for
+  example our payment provider, Razorpay) — report those upstream.
+
+## Report data protection
+
+A generated PDF can contain whatever your tests captured: error text, console
+output, screenshots. Two opt-in reporter options limit what a report exposes
+if it ends up somewhere it shouldn't. `pdfPassword` encrypts the PDF, and the
+failure-overflow sidecar when one is written, with AES-256, applied
+in-process with no external tools required. `redact` masks likely credentials
+and PII (tokens, API keys, emails, and more) out of report content and the
+live watch stream before they're written or streamed. Neither is on by
+default. Details: [reportforge.org/docs/advanced/security](https://reportforge.org/docs/advanced/security).
 
 ## Supported versions