@reportforge/playwright-pdf 0.13.0 → 0.13.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +128 -106
- package/README.md +84 -84
- package/dist/cli/index.js +34 -21
- package/dist/index.js +94 -64
- package/dist/index.mjs +94 -64
- package/package.json +11 -2
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @reportforge/playwright-pdf
|
|
2
2
|
|
|
3
|
-
> Playwright PDF reporter
|
|
3
|
+
> Playwright PDF reporter: generate branded PDF reports from [Playwright Test](https://playwright.dev/) results. Three templates (minimal, detailed, executive) for developers, QA teams, and stakeholders. CI-ready, self-contained, with embedded screenshots and charts.
|
|
4
4
|
|
|
5
5
|
Drop it into any Playwright project and get a PDF report on every CI run. No changes to your tests.
|
|
6
6
|
|
|
@@ -21,7 +21,7 @@ Drop it into any Playwright project and get a PDF report on every CI run. No cha
|
|
|
21
21
|
|
|
22
22
|
## Report Gallery
|
|
23
23
|
|
|
24
|
-
Three templates, one reporter. Every PDF is fully offline
|
|
24
|
+
Three templates, one reporter. Every PDF is fully offline: fonts, charts, and screenshots are embedded.
|
|
25
25
|
|
|
26
26
|
<table>
|
|
27
27
|
<tr>
|
|
@@ -45,23 +45,23 @@ Three templates, one reporter. Every PDF is fully offline — fonts, charts, and
|
|
|
45
45
|
|
|
46
46
|
## Features
|
|
47
47
|
|
|
48
|
-
- **3 templates
|
|
49
|
-
- **Detailed reports
|
|
50
|
-
- **Embedded Chart.js
|
|
51
|
-
- **Self-contained PDFs
|
|
52
|
-
- **Custom branding
|
|
53
|
-
- **Dynamic filenames
|
|
54
|
-
- **Instant demo report
|
|
55
|
-
- **CI/CD snippets
|
|
56
|
-
- **Live runs
|
|
57
|
-
- **Shard merging
|
|
58
|
-
- **Notifications
|
|
59
|
-
- **Flakiness trend
|
|
60
|
-
- **Offline failure analysis
|
|
61
|
-
- `npx @reportforge/playwright-pdf export-feedback
|
|
62
|
-
- **Rich execution capture
|
|
63
|
-
- **Configurable sections
|
|
64
|
-
- **Hybrid licensing
|
|
48
|
+
- **3 templates**: `minimal` (developer), `detailed` (QA team), `executive` (stakeholders)
|
|
49
|
+
- **Detailed reports**: KPI dashboard, suite breakdown with inline failure detail (error, screenshot, root-cause chip) under each failed test, CI/CD environment
|
|
50
|
+
- **Embedded Chart.js**: pass-rate doughnut + per-suite bar chart, bundled inline (no CDN)
|
|
51
|
+
- **Self-contained PDFs**: screenshots, fonts, logos all embedded; share or archive with confidence
|
|
52
|
+
- **Custom branding**: logo, primary/accent colours, watermark, PDF password encryption
|
|
53
|
+
- **Dynamic filenames**: `{date}`, `{branch}`, `{status}` tokens in the output path
|
|
54
|
+
- **Instant demo report**: `npx @reportforge/playwright-pdf demo` generates a realistic sample PDF before subscribing, no license key required
|
|
55
|
+
- **CI/CD snippets**: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
|
|
56
|
+
- **Live runs**: opt-in `live` streams per-test progress to an unguessable watch link printed at run start; all shards of one CI run converge on a single live dashboard while tests execute. The PDF is still produced at the end, unchanged
|
|
57
|
+
- **Shard merging**: combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
|
|
58
|
+
- **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`
|
|
59
|
+
- **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)
|
|
60
|
+
- **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).
|
|
61
|
+
- `npx @reportforge/playwright-pdf export-feedback`: exports locally-collected unrecognized failures (tokenized, local-only) for optional manual sharing.
|
|
62
|
+
- **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.
|
|
63
|
+
- **Configurable sections**: add or remove any report section per template via `sections`.
|
|
64
|
+
- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
|
|
65
65
|
|
|
66
66
|
---
|
|
67
67
|
|
|
@@ -87,16 +87,16 @@ export default defineConfig({
|
|
|
87
87
|
});
|
|
88
88
|
```
|
|
89
89
|
|
|
90
|
-
`defineReporterConfig` is an optional typed identity helper
|
|
90
|
+
`defineReporterConfig` is an optional typed identity helper: it gives you IntelliSense and type-checking on the options object without a separate `ReporterOptions` import. You can also pass a plain object literal if you prefer.
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
93
|
npx playwright test
|
|
94
94
|
# → reports/2026-05-01-main-failed.pdf
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
> **See it first.** Run `npx @reportforge/playwright-pdf demo` to generate a realistic sample PDF in under 60 seconds
|
|
97
|
+
> **See it first.** Run `npx @reportforge/playwright-pdf demo` to generate a realistic sample PDF in under 60 seconds, no license key required. Supports `--template=minimal|detailed|executive` and `--output=<path>`.
|
|
98
98
|
|
|
99
|
-
> **License required.** Start a **[7-day free trial at reportforge.org/pricing](https://reportforge.org/pricing)
|
|
99
|
+
> **License required.** Start a **[7-day free trial at reportforge.org/pricing](https://reportforge.org/pricing)**: card required, no charge until day 8. Paste the resulting `RFSU-…` key into `RF_LICENSE_KEY`. Without a valid license the reporter logs a warning and skips PDF generation; your Playwright tests still run normally.
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
@@ -132,7 +132,7 @@ sudo apt-get update -qq && sudo apt-get install -y google-chrome-stable
|
|
|
132
132
|
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
-
> **Note:** Do not use the `chromium-browser` apt package
|
|
135
|
+
> **Note:** Do not use the `chromium-browser` apt package: it installs as a snap on Ubuntu and Puppeteer cannot drive it.
|
|
136
136
|
|
|
137
137
|
**macOS**
|
|
138
138
|
|
|
@@ -173,37 +173,37 @@ Currency is auto-detected by region; toggle on the pricing page.
|
|
|
173
173
|
|
|
174
174
|
All options are the second element of the reporter tuple.
|
|
175
175
|
|
|
176
|
-
<!-- AUTOGEN:options-table START
|
|
176
|
+
<!-- AUTOGEN:options-table START: edit scripts/docs/options-meta.ts, then run npm run docs:gen -->
|
|
177
177
|
| Option | Type | Default | Description |
|
|
178
178
|
|---|---|---|---|
|
|
179
179
|
| `outputFile` | `string` | `'playwright-report/{date}-report.pdf'` | Output path. Supports tokens: `{date}`, `{datetime}`, `{branch}`, `{status}`, `{total}`, `{passed}`, `{failed}`, `{project}`. Directory is created if absent. |
|
|
180
|
-
| `template` | `'minimal' \| 'detailed' \| 'executive'` or array | `'minimal'` | Template(s) to generate. Pass an array to produce one PDF per template in one run
|
|
180
|
+
| `template` | `'minimal' \| 'detailed' \| 'executive'` or array | `'minimal'` | Template(s) to generate. Pass an array to produce one PDF per template in one run: the template name is appended to each output filename automatically (e.g. `report-detailed.pdf`). |
|
|
181
181
|
| `licenseKey` | `string` | env `RF_LICENSE_KEY` | Subscription key (format `RFSU-…`). Falls back to the `RF_LICENSE_KEY` environment variable. PDF generation is skipped when absent or invalid. |
|
|
182
|
-
| `logo` | `string` |
|
|
182
|
+
| `logo` | `string` | n/a | Path to a logo image (PNG, JPG, or SVG) to embed in the report header. Supports absolute and relative paths. |
|
|
183
183
|
| `primaryColor` | `string` | `'#CC785C'` | Primary brand colour (3-, 6-, or 8-digit hex). Used for headers and accent bars. |
|
|
184
184
|
| `accentColor` | `string` | `'#3F7D58'` | Accent brand colour (hex). Used for highlights and badges. |
|
|
185
|
-
| `watermark` | `string` |
|
|
186
|
-
| `pdfPassword` | `string` |
|
|
185
|
+
| `watermark` | `string` | n/a | Text to render as a diagonal watermark overlay on every page, e.g. `'CONFIDENTIAL'` or `'DRAFT'`. |
|
|
186
|
+
| `pdfPassword` | `string` | n/a | Password-protect the generated PDF. Requires `qpdf` installed on the system. |
|
|
187
187
|
| `reportTitle` | `string` | `'Playwright Test Report'` | Custom title for the report cover page and running header. |
|
|
188
188
|
| `projectName` | `string` | from `package.json` | Project or application name. Inferred from the `package.json` `name` field if absent. |
|
|
189
|
-
| `open` | `boolean` | `false` | Open the generated PDF automatically after generation. For local use only
|
|
189
|
+
| `open` | `boolean` | `false` | Open the generated PDF automatically after generation. For local use only; ignored in CI. |
|
|
190
190
|
| `puppeteerExecutablePath` | `string` | auto-detect | Full path to a Chrome or Chromium binary. Falls back to `PUPPETEER_EXECUTABLE_PATH` env, then system Chrome discovery. |
|
|
191
191
|
| `serverUrl` | `string` | `'https://reportforge.org'` | Base URL for the ReportForge licensing server. Override only for self-hosting or local development. |
|
|
192
192
|
| `compressionLevel` | `'auto' \| 'none' \| 'balanced' \| 'max'` | `'auto'` | Screenshot JPEG quality preset. `'auto'` picks based on failure volume; `'none'` keeps original PNGs; `'balanced'` uses JPEG q85; `'max'` uses JPEG q70. |
|
|
193
|
-
| `includeScreenshots` | `boolean` | `true` | Embed Playwright screenshots in the PDF. Set to `false` to omit images
|
|
193
|
+
| `includeScreenshots` | `boolean` | `true` | Embed Playwright screenshots in the PDF. Set to `false` to omit images; useful for exec-audience reports or reducing file size. |
|
|
194
194
|
| `maxInlineFailures` | `number` | derived from `compressionLevel` | Cap on failure entries rendered inline in the PDF. Overflow is written to a sibling `{basename}-failures.json` sidecar file. |
|
|
195
195
|
| `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. |
|
|
196
|
-
| `shardResults` | `string \| string[]` |
|
|
197
|
-
| `notify` | `object` |
|
|
196
|
+
| `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. |
|
|
197
|
+
| `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. |
|
|
198
198
|
| `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded Naive Bayes; no runtime network). Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `autoUpdateModel` (default `true`). See the Failure Analysis docs. |
|
|
199
|
-
| `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
|
|
200
|
-
| `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
|
|
199
|
+
| `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. |
|
|
200
|
+
| `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. |
|
|
201
201
|
| `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. |
|
|
202
202
|
| `historySize` | `number` | `10` | Maximum number of test runs to keep in the history file (integer ≥ 2). Older runs are pruned on append. |
|
|
203
203
|
| `showTrend` | `boolean` | `true` | Show the pass-rate sparkline and delta badge in the `detailed` template. Set to `false` to disable history tracking entirely. |
|
|
204
204
|
| `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
|
|
205
|
-
| `slowTestThreshold` | `number` | `10` | Minimum timed-test count before `SLOW` badges appear in the suite breakdown
|
|
206
|
-
| `templatePath` | `string \| string[]` |
|
|
205
|
+
| `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). |
|
|
206
|
+
| `templatePath` | `string \| string[]` | n/a | Path to a custom Handlebars (`.hbs`) template file. Takes precedence over `template`. Pass an array to generate one PDF per custom template. See the Custom Templates docs. |
|
|
207
207
|
| `sections` | `object` | per-template | Override which report sections appear, on top of the chosen template's defaults. Flat keys are the baseline for every chosen template; per-template keys (`minimal`\|`detailed`\|`executive`) override per template. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. See the Report Sections docs. |
|
|
208
208
|
<!-- AUTOGEN:options-table END -->
|
|
209
209
|
|
|
@@ -211,9 +211,9 @@ Full reference: [reportforge.org/docs/configuration](https://reportforge.org/doc
|
|
|
211
211
|
|
|
212
212
|
### Live Runs
|
|
213
213
|
|
|
214
|
-
Watch a run as it happens. With `live` enabled, the reporter prints an unguessable watch link
|
|
214
|
+
Watch a run as it happens. With `live` enabled, the reporter prints an unguessable watch link (boxed under a `Live Tracker` heading) to your CI logs at run start and streams per-test progress to a hosted dashboard while tests execute. All shards of one CI run converge on a single live view. Each test shows its steps and assertions as sub-lines beneath its row: each step once, as it settles, indented under its parent `test.step` in source order (Playwright's hooks, fixtures, and teardown are filtered out). The PDF is still generated at the end, unchanged.
|
|
215
215
|
|
|
216
|
-
> The watch link is entitlement-gated. If you enable `live` but see no `Live Tracker` line, the reporter logs why (missing `RF_LICENSE_KEY`, or a cached token without the `live` entitlement
|
|
216
|
+
> The watch link is entitlement-gated. If you enable `live` but see no `Live Tracker` line, the reporter logs why (missing `RF_LICENSE_KEY`, or a cached token without the `live` entitlement; delete `~/.reportforge/license.json` to force re-activation).
|
|
217
217
|
|
|
218
218
|
```typescript
|
|
219
219
|
// playwright.config.ts
|
|
@@ -223,20 +223,20 @@ reporter: [
|
|
|
223
223
|
live: {
|
|
224
224
|
enabled: true,
|
|
225
225
|
steps: 'failed', // 'none' | 'failed' | 'intent' | 'all'
|
|
226
|
-
// console: false, // stream stdout/stderr tails (off by default
|
|
226
|
+
// console: false, // stream stdout/stderr tails (off by default; see note)
|
|
227
227
|
// flushMs: 2000, // batch debounce (500–10000)
|
|
228
228
|
},
|
|
229
229
|
}],
|
|
230
230
|
],
|
|
231
231
|
```
|
|
232
232
|
|
|
233
|
-
`steps: 'intent'` shows only your `test.step` names (plus any failing step)
|
|
233
|
+
`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.
|
|
234
234
|
|
|
235
|
-
Sharded runs need no extra config
|
|
235
|
+
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.
|
|
236
236
|
|
|
237
237
|
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.
|
|
238
238
|
|
|
239
|
-
> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on). Leaving `console: false` is recommended
|
|
239
|
+
> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on). Leaving `console: false` is recommended: enabling it streams your tests' stdout/stderr to anyone holding the link. Full details at [reportforge.org/docs/advanced/live](https://reportforge.org/docs/advanced/live).
|
|
240
240
|
|
|
241
241
|
### Shard Merging
|
|
242
242
|
|
|
@@ -245,7 +245,7 @@ Combine parallel Playwright shards into one PDF without re-running any tests.
|
|
|
245
245
|
**Workflow:**
|
|
246
246
|
|
|
247
247
|
1. Run each shard with `--reporter=json` to produce a JSON output file.
|
|
248
|
-
2. In a separate step, point `shardResults` at those files
|
|
248
|
+
2. In a separate step, point `shardResults` at those files; it accepts a glob or an explicit array.
|
|
249
249
|
|
|
250
250
|
```typescript
|
|
251
251
|
// playwright.config.ts (merge step)
|
|
@@ -258,7 +258,7 @@ reporter: [
|
|
|
258
258
|
],
|
|
259
259
|
```
|
|
260
260
|
|
|
261
|
-
The merge step can run against a dummy test file with zero tests
|
|
261
|
+
The merge step can run against a dummy test file with zero tests: `shardResults` takes precedence over live results.
|
|
262
262
|
|
|
263
263
|
> **Note:** Timed-out tests are counted as failures in shard mode (Playwright JSON stats do not distinguish `timedOut` from `failed`).
|
|
264
264
|
|
|
@@ -293,7 +293,7 @@ notify: {
|
|
|
293
293
|
},
|
|
294
294
|
```
|
|
295
295
|
|
|
296
|
-
Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it
|
|
296
|
+
Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it; useful for staging configs.
|
|
297
297
|
|
|
298
298
|
The `on` trigger controls when the message fires:
|
|
299
299
|
|
|
@@ -303,19 +303,19 @@ The `on` trigger controls when the message fires:
|
|
|
303
303
|
| `'failure'` | `stats.failed > 0` or run timed out / interrupted |
|
|
304
304
|
| `'success'` | All tests passed |
|
|
305
305
|
|
|
306
|
-
**Email** requires `RESEND_API_KEY` in the environment (get one at [resend.com](https://resend.com)). Sender defaults to `noreply@reportforge.org`; override with `RESEND_FROM`. Store webhook URLs and API keys as CI secrets
|
|
306
|
+
**Email** requires `RESEND_API_KEY` in the environment (get one at [resend.com](https://resend.com)). Sender defaults to `noreply@reportforge.org`; override with `RESEND_FROM`. Store webhook URLs and API keys as CI secrets; never commit them.
|
|
307
307
|
|
|
308
|
-
**PDF attachment** (`attachPdf: true`) is available on `email` and `discord
|
|
308
|
+
**PDF attachment** (`attachPdf: true`) is available on `email` and `discord`: Slack and Teams webhooks cannot carry file uploads. On Discord the PDF is uploaded with the message; if the upload fails or the PDF exceeds Discord's file-size cap, the summary still posts without the attachment. With multiple templates, the first PDF is attached.
|
|
309
309
|
|
|
310
|
-
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
|
|
310
|
+
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).
|
|
311
311
|
|
|
312
312
|
### Test History Trending
|
|
313
313
|
|
|
314
314
|
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.
|
|
315
315
|
|
|
316
|
-
**Local dev (zero config)
|
|
316
|
+
**Local dev (zero config)**: history is written automatically to `~/.reportforge/{projectKey}/history.json`. The sparkline appears once two or more runs have been recorded.
|
|
317
317
|
|
|
318
|
-
**CI with ephemeral runners
|
|
318
|
+
**CI with ephemeral runners**: set `historyFile` to a project-relative path and cache it between runs:
|
|
319
319
|
|
|
320
320
|
```typescript
|
|
321
321
|
// playwright.config.ts
|
|
@@ -331,10 +331,10 @@ reporter: [['@reportforge/playwright-pdf', {
|
|
|
331
331
|
with:
|
|
332
332
|
path: .reportforge/history.json
|
|
333
333
|
key: reportforge-history-${{ github.ref }}
|
|
334
|
-
# Omit restore-keys
|
|
334
|
+
# Omit restore-keys; cross-branch fallback causes misleading sparklines on PRs
|
|
335
335
|
```
|
|
336
336
|
|
|
337
|
-
**Monorepo
|
|
337
|
+
**Monorepo**: each package needs a distinct `historyFile` (e.g. `.reportforge/api-history.json`, `.reportforge/web-history.json`) so runs do not overwrite each other.
|
|
338
338
|
|
|
339
339
|
### Flakiness Trend Table
|
|
340
340
|
|
|
@@ -343,11 +343,11 @@ The `detailed` template includes a **Top flaky tests** table showing which tests
|
|
|
343
343
|
```typescript
|
|
344
344
|
reporter: [['@reportforge/playwright-pdf', {
|
|
345
345
|
template: 'detailed',
|
|
346
|
-
flakinessTopN: 5, // default
|
|
346
|
+
flakinessTopN: 5, // default: show top 5; set 0 to disable
|
|
347
347
|
}]]
|
|
348
348
|
```
|
|
349
349
|
|
|
350
|
-
The table is gated behind `showTrend: true` (the default) and appears automatically once history entries are present. Runs written before the flakiness feature was added are excluded from the denominator
|
|
350
|
+
The table is gated behind `showTrend: true` (the default) and appears automatically once history entries are present. Runs written before the flakiness feature was added are excluded from the denominator; the table fills in correctly as newer runs accumulate. Set `flakinessTopN: 0` to hide the table entirely.
|
|
351
351
|
|
|
352
352
|
### Filename tokens
|
|
353
353
|
|
|
@@ -361,21 +361,21 @@ The table is gated behind `showTrend: true` (the default) and appears automatica
|
|
|
361
361
|
|
|
362
362
|
## Templates
|
|
363
363
|
|
|
364
|
-
### `minimal
|
|
364
|
+
### `minimal`: Developer-focused
|
|
365
365
|
|
|
366
366
|
Clean layout, KPI numbers, hierarchical test table, failure details with stack traces and embedded screenshots. Fast to generate. Good for local development and PR checks.
|
|
367
367
|
|
|
368
|
-
### `detailed
|
|
368
|
+
### `detailed`: QA Team
|
|
369
369
|
|
|
370
370
|
Everything in `minimal`, **plus** Chart.js pass-rate + suite-results charts, a numbered defect log, a requirements traceability matrix derived from `@TAG` annotations, and the full CI/CD environment table.
|
|
371
371
|
|
|
372
|
-
### `executive
|
|
372
|
+
### `executive`: Stakeholder presentations
|
|
373
373
|
|
|
374
|
-
Full-page cover with verdict + KPI strip, followed by a compact dashboard with charts and a failures summary (titles only
|
|
374
|
+
Full-page cover with verdict + KPI strip, followed by a compact dashboard with charts and a failures summary (titles only, **no raw stack traces**). Best for sprint reports and management dashboards.
|
|
375
375
|
|
|
376
376
|
### Shared across all three
|
|
377
377
|
|
|
378
|
-
Every report leads with a **release-gate** ship/hold banner derived from the run verdict, surfaces **timed-out** tests as their own KPI card and pass-rate chart slice, and lists failures **most-severe first** (with severity-coloured card borders in `minimal` and `detailed`). Pages **pack compactly
|
|
378
|
+
Every report leads with a **release-gate** ship/hold banner derived from the run verdict, surfaces **timed-out** tests as their own KPI card and pass-rate chart slice, and lists failures **most-severe first** (with severity-coloured card borders in `minimal` and `detailed`). Pages **pack compactly**: large sections flow and break between rows instead of each starting on a fresh page. The Suite Results chart breaks a single-file run down by **describe block** so it never collapses to one bar. Requirements coverage bars are coloured by threshold (red <50%, amber <80%, green ≥80%).
|
|
379
379
|
|
|
380
380
|
### Generating multiple templates in one run
|
|
381
381
|
|
|
@@ -397,11 +397,11 @@ reporter: [
|
|
|
397
397
|
# → reports/2026-04-28-report-executive.pdf
|
|
398
398
|
```
|
|
399
399
|
|
|
400
|
-
One license check, one data-collection pass
|
|
400
|
+
One license check, one data-collection pass: faster than multiple reporter instances. Duplicate entries are silently deduplicated.
|
|
401
401
|
|
|
402
402
|
### Report Sections
|
|
403
403
|
|
|
404
|
-
Each built-in template ships a curated set of sections. The `sections` option lets you **add a section a template hides or remove one it shows
|
|
404
|
+
Each built-in template ships a curated set of sections. The `sections` option lets you **add a section a template hides or remove one it shows, per template**, without writing a custom template.
|
|
405
405
|
|
|
406
406
|
```ts
|
|
407
407
|
reporter: [['@reportforge/playwright-pdf', {
|
|
@@ -416,7 +416,7 @@ reporter: [['@reportforge/playwright-pdf', {
|
|
|
416
416
|
|
|
417
417
|
**Resolution order** (lowest → highest): the template's defaults → flat keys (baseline for all chosen templates) → per-template keys (`minimal` / `detailed` / `executive`). An unknown key throws a configuration error (typo-safe).
|
|
418
418
|
|
|
419
|
-
#### Block toggles
|
|
419
|
+
#### Block toggles: which sections appear
|
|
420
420
|
|
|
421
421
|
| Key | Renders |
|
|
422
422
|
|---|---|
|
|
@@ -434,7 +434,7 @@ reporter: [['@reportforge/playwright-pdf', {
|
|
|
434
434
|
| `slowTests` | `SLOW` badge on the duration-ranked slowest tests, shown inline in the breakdown |
|
|
435
435
|
| `defectLog` | `DEF-####` numbered failure table (severity, duration) + opt-in repro detail (`capture`) |
|
|
436
436
|
|
|
437
|
-
#### Display modifiers
|
|
437
|
+
#### Display modifiers: tune a section that's on
|
|
438
438
|
|
|
439
439
|
| Key | Effect |
|
|
440
440
|
|---|---|
|
|
@@ -471,11 +471,11 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
|
|
|
471
471
|
|
|
472
472
|
#### Dependencies & gotchas
|
|
473
473
|
|
|
474
|
-
- **`trend` needs `charts`.** The trend line, run-history, and flakiness table live inside the charts block, so `trend: true` does nothing with `charts: false` (it's coerced off). It also needs history data
|
|
475
|
-
- **Inline failure detail needs `suiteBreakdown`.** `failureDeepDive` (failure detail), `failureAnalysis` (root-cause chip), and `slowTests` (`SLOW` badge) now render *inside* the suite breakdown, so they show nothing when `suiteBreakdown` is off. The chip (`failureAnalysis`) also needs `failureDeepDive
|
|
476
|
-
- **Data-gated sections
|
|
477
|
-
- **Render-layer only.** `sections` controls what's drawn, never what's collected
|
|
478
|
-
- **Custom templates.** `sections` applies to the built-in templates; a custom `templatePath` controls its own layout (every section available) and ignores `sections
|
|
474
|
+
- **`trend` needs `charts`.** The trend line, run-history, and flakiness table live inside the charts block, so `trend: true` does nothing with `charts: false` (it's coerced off). It also needs history data; keep the top-level `showTrend` option on.
|
|
475
|
+
- **Inline failure detail needs `suiteBreakdown`.** `failureDeepDive` (failure detail), `failureAnalysis` (root-cause chip), and `slowTests` (`SLOW` badge) now render *inside* the suite breakdown, so they show nothing when `suiteBreakdown` is off. The chip (`failureAnalysis`) also needs `failureDeepDive`: it lives inside the failure detail, so it's coerced off without it.
|
|
476
|
+
- **Data-gated sections**: `failureAnalysis`, `requirementsMatrix`, `slowTests`, `defectLog` render only when there's matching data (classified failures, tagged tests, a meaningful slow set, failures). Toggling them on with no data shows nothing.
|
|
477
|
+
- **Render-layer only.** `sections` controls what's drawn, never what's collected; the data switches stay separate: `showTrend` (history), `flakinessTopN` (flaky-table size), `failureAnalysis.enabled` (classifier), `includeScreenshots` (images).
|
|
478
|
+
- **Custom templates.** `sections` applies to the built-in templates; a custom `templatePath` controls its own layout (every section available) and ignores `sections`. You'll get a warning if both are set.
|
|
479
479
|
|
|
480
480
|
---
|
|
481
481
|
|
|
@@ -500,7 +500,7 @@ Full workflows for all four CI providers: [reportforge.org/docs/ci-cd](https://r
|
|
|
500
500
|
path: reports/*.pdf
|
|
501
501
|
```
|
|
502
502
|
|
|
503
|
-
### GitHub Actions
|
|
503
|
+
### GitHub Actions: Sharded runs
|
|
504
504
|
|
|
505
505
|
Run shards in parallel with `--reporter=json`, then merge all JSON files into one PDF:
|
|
506
506
|
|
|
@@ -543,7 +543,7 @@ jobs:
|
|
|
543
543
|
with: { name: playwright-pdf-report, path: reports/*.pdf }
|
|
544
544
|
```
|
|
545
545
|
|
|
546
|
-
In `playwright.config.ts` set `shardResults: process.env.SHARD_RESULTS_GLOB`. `tests/dummy.spec.ts` can be a single skipped test
|
|
546
|
+
In `playwright.config.ts` set `shardResults: process.env.SHARD_RESULTS_GLOB`. `tests/dummy.spec.ts` can be a single skipped test: live results are ignored when `shardResults` is set.
|
|
547
547
|
|
|
548
548
|
### GitLab CI
|
|
549
549
|
|
|
@@ -606,11 +606,11 @@ ReportForge ships a **hybrid offline-first** model:
|
|
|
606
606
|
|
|
607
607
|
1. Paste your `RFSU-…` key into the config once (or set `RF_LICENSE_KEY`).
|
|
608
608
|
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`.
|
|
609
|
-
3. Every subsequent run is **fully offline
|
|
609
|
+
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.
|
|
610
610
|
4. When the cache has less than 24 hours left, the reporter refreshes it in the background.
|
|
611
611
|
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.
|
|
612
612
|
|
|
613
|
-
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
|
|
613
|
+
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.
|
|
614
614
|
|
|
615
615
|
```bash
|
|
616
616
|
export RF_LICENSE_KEY=RFSU-XXXX-XXXX-XXXX-XXXX
|
|
@@ -657,17 +657,17 @@ Full guide: [reportforge.org/docs/troubleshooting](https://reportforge.org/docs/
|
|
|
657
657
|
|
|
658
658
|
Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
|
|
659
659
|
|
|
660
|
-
- [Quick start](https://reportforge.org/docs/quickstart)
|
|
661
|
-
- [Chrome setup](https://reportforge.org/docs/running-tests#chrome-setup)
|
|
662
|
-
- [CI/CD integration](https://reportforge.org/docs/ci-cd)
|
|
663
|
-
- [Configuration reference](https://reportforge.org/docs/configuration)
|
|
664
|
-
- [Filename tokens](https://reportforge.org/docs/configuration#tokens)
|
|
665
|
-
- [Templates](https://reportforge.org/docs/templates)
|
|
666
|
-
- [Live runs](https://reportforge.org/docs/advanced/live)
|
|
667
|
-
- [Report Sections](https://reportforge.org/docs/configuration#report-sections)
|
|
668
|
-
- [License & offline behaviour](https://reportforge.org/docs/licensing)
|
|
669
|
-
- [Troubleshooting](https://reportforge.org/docs/troubleshooting)
|
|
670
|
-
- **Changelog
|
|
660
|
+
- [Quick start](https://reportforge.org/docs/quickstart): install, configure, activate
|
|
661
|
+
- [Chrome setup](https://reportforge.org/docs/running-tests#chrome-setup): Windows, Linux, macOS
|
|
662
|
+
- [CI/CD integration](https://reportforge.org/docs/ci-cd): GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
|
|
663
|
+
- [Configuration reference](https://reportforge.org/docs/configuration): all options
|
|
664
|
+
- [Filename tokens](https://reportforge.org/docs/configuration#tokens): `{date}`, `{branch}`, `{status}`
|
|
665
|
+
- [Templates](https://reportforge.org/docs/templates): minimal, detailed, executive
|
|
666
|
+
- [Live runs](https://reportforge.org/docs/advanced/live): stream per-test progress to a shared watch link
|
|
667
|
+
- [Report Sections](https://reportforge.org/docs/configuration#report-sections): add or remove sections per template
|
|
668
|
+
- [License & offline behaviour](https://reportforge.org/docs/licensing): JWT cache, machine cap, cancellation
|
|
669
|
+
- [Troubleshooting](https://reportforge.org/docs/troubleshooting): common issues and debug flags
|
|
670
|
+
- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
|
|
671
671
|
|
|
672
672
|
---
|
|
673
673
|
|
|
@@ -677,4 +677,4 @@ Questions and bug reports: email [support@reportforge.org](mailto:support@report
|
|
|
677
677
|
|
|
678
678
|
## License
|
|
679
679
|
|
|
680
|
-
MIT
|
|
680
|
+
MIT. See [LICENSE](./LICENSE).
|
package/dist/cli/index.js
CHANGED
|
@@ -7325,25 +7325,18 @@ var init_PdfEncryptor = __esm({
|
|
|
7325
7325
|
return;
|
|
7326
7326
|
}
|
|
7327
7327
|
const tmpPath = import_path3.default.join(import_os2.default.tmpdir(), `rf-encrypted-${Date.now()}.pdf`);
|
|
7328
|
-
const
|
|
7328
|
+
const argFile = import_path3.default.join(import_os2.default.tmpdir(), `rf-qpdf-args-${import_crypto2.default.randomBytes(8).toString("hex")}`);
|
|
7329
7329
|
try {
|
|
7330
|
-
|
|
7331
|
-
|
|
7332
|
-
(0, import_child_process2.execFileSync)("qpdf", [
|
|
7333
|
-
`--password-file=${pwFile}`,
|
|
7334
|
-
"--encrypt",
|
|
7335
|
-
"256",
|
|
7336
|
-
"--",
|
|
7337
|
-
pdfPath,
|
|
7338
|
-
tmpPath
|
|
7339
|
-
], { stdio: "pipe" });
|
|
7330
|
+
const args = ["--encrypt", password, password, "256", "--", pdfPath, tmpPath];
|
|
7331
|
+
import_fs5.default.writeFileSync(argFile, args.join("\n"), { mode: 384 });
|
|
7332
|
+
(0, import_child_process2.execFileSync)("qpdf", [`@${argFile}`], { stdio: "pipe" });
|
|
7340
7333
|
import_fs5.default.renameSync(tmpPath, pdfPath);
|
|
7341
7334
|
logger.info(`PDF encrypted with password.`);
|
|
7342
7335
|
} catch (e) {
|
|
7343
|
-
|
|
7336
|
+
throw new Error(`qpdf encryption failed: ${e.message}`);
|
|
7344
7337
|
} finally {
|
|
7345
7338
|
if (import_fs5.default.existsSync(tmpPath)) import_fs5.default.unlinkSync(tmpPath);
|
|
7346
|
-
import_fs5.default.rmSync(
|
|
7339
|
+
import_fs5.default.rmSync(argFile, { force: true });
|
|
7347
7340
|
}
|
|
7348
7341
|
}
|
|
7349
7342
|
isQpdfAvailable() {
|
|
@@ -7668,7 +7661,8 @@ var init_PdfGenerator = __esm({
|
|
|
7668
7661
|
if (capBytes > 0) {
|
|
7669
7662
|
const sizeBytes = (await import_fs8.default.promises.stat(outputPath)).size;
|
|
7670
7663
|
if (sizeBytes > capBytes) {
|
|
7671
|
-
const
|
|
7664
|
+
const inlinedCount = Math.min(templateData.failures.length, compression.maxInlineFailures);
|
|
7665
|
+
const tighter = this.tightenForCap(compression, sizeBytes, capBytes, inlinedCount);
|
|
7672
7666
|
logger.warn(
|
|
7673
7667
|
`PDF size ${fmtMb(sizeBytes)} exceeds cap ${fmtMb(capBytes)} \u2014 re-rendering (jpeg-q=${tighter.quality}, max-w=${tighter.maxWidth}px, inline-failures\u2264${tighter.maxInlineFailures}).`
|
|
7674
7668
|
);
|
|
@@ -7697,11 +7691,30 @@ var init_PdfGenerator = __esm({
|
|
|
7697
7691
|
}
|
|
7698
7692
|
resolveTemplateSources(options) {
|
|
7699
7693
|
if (options.templatePath && options.templatePath.length > 0) {
|
|
7700
|
-
|
|
7701
|
-
|
|
7702
|
-
absolutePath
|
|
7703
|
-
|
|
7704
|
-
}
|
|
7694
|
+
const byAbsolutePath = /* @__PURE__ */ new Map();
|
|
7695
|
+
for (const p of options.templatePath) {
|
|
7696
|
+
const absolutePath = import_path6.default.isAbsolute(p) ? p : import_path6.default.resolve(process.cwd(), p);
|
|
7697
|
+
if (!byAbsolutePath.has(absolutePath)) byAbsolutePath.set(absolutePath, p);
|
|
7698
|
+
}
|
|
7699
|
+
const labelCounts = /* @__PURE__ */ new Map();
|
|
7700
|
+
for (const rawPath of byAbsolutePath.values()) {
|
|
7701
|
+
const label = import_path6.default.basename(rawPath, ".hbs");
|
|
7702
|
+
labelCounts.set(label, (labelCounts.get(label) ?? 0) + 1);
|
|
7703
|
+
}
|
|
7704
|
+
const seenPerLabel = /* @__PURE__ */ new Map();
|
|
7705
|
+
return Array.from(byAbsolutePath.entries()).map(([absolutePath, rawPath]) => {
|
|
7706
|
+
const baseLabel = import_path6.default.basename(rawPath, ".hbs");
|
|
7707
|
+
let label = baseLabel;
|
|
7708
|
+
if ((labelCounts.get(baseLabel) ?? 0) > 1) {
|
|
7709
|
+
const n = (seenPerLabel.get(baseLabel) ?? 0) + 1;
|
|
7710
|
+
seenPerLabel.set(baseLabel, n);
|
|
7711
|
+
label = `${baseLabel}-${n}`;
|
|
7712
|
+
logger.warn(
|
|
7713
|
+
`Multiple templatePath entries resolve to the basename "${baseLabel}" \u2014 disambiguating output filenames with a numeric suffix ("${label}").`
|
|
7714
|
+
);
|
|
7715
|
+
}
|
|
7716
|
+
return { kind: "custom", absolutePath, label };
|
|
7717
|
+
});
|
|
7705
7718
|
}
|
|
7706
7719
|
const rawIds = Array.isArray(options.template) ? options.template : [options.template];
|
|
7707
7720
|
return [...new Set(rawIds)].map((id) => ({ kind: "builtin", id }));
|
|
@@ -7723,8 +7736,8 @@ var init_PdfGenerator = __esm({
|
|
|
7723
7736
|
* Also tightens JPEG quality and width to claw back bytes from each
|
|
7724
7737
|
* remaining image.
|
|
7725
7738
|
*/
|
|
7726
|
-
tightenForCap(prev, actualBytes, capBytes) {
|
|
7727
|
-
const observedPerFailure = actualBytes / Math.max(1,
|
|
7739
|
+
tightenForCap(prev, actualBytes, capBytes, actualInlinedCount) {
|
|
7740
|
+
const observedPerFailure = actualBytes / Math.max(1, actualInlinedCount);
|
|
7728
7741
|
const targetInline = Math.max(20, Math.floor(capBytes * 0.85 / observedPerFailure));
|
|
7729
7742
|
return {
|
|
7730
7743
|
effective: "max",
|