@reportforge/playwright-pdf 0.2.0 → 0.2.2

package/README.md

@@ -165,31 +165,34 @@ Currency is auto-detected by region; toggle on the pricing page.
 
 All options are the second element of the reporter tuple.
 
+<!-- AUTOGEN:options-table START — edit scripts/docs/options-meta.ts, then run npm run docs:gen -->
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `template` | `'minimal' \| 'detailed' \| 'executive'` or array | `'minimal'` | Template(s) to generate. Pass an array to produce one PDF per template — the template name is appended automatically (e.g. `report-detailed.pdf`). |
-| `outputFile` | `string` | `'playwright-report/{date}-report.pdf'` | Output path (supports tokens) |
-| `reportTitle` | `string` | `'Playwright Test Report'` | Title in header and cover |
-| `projectName` | `string` | from `package.json` | Project name shown in report |
-| `logo` | `string` | — | Path to logo image (PNG / JPG / SVG) |
-| `primaryColor` | `string` | `'#CC785C'` | Brand colour (hex) |
-| `accentColor` | `string` | `'#3F7D58'` | Accent colour (hex) |
-| `watermark` | `string` | — | Diagonal watermark text (e.g. `'CONFIDENTIAL'`) |
-| `pdfPassword` | `string` | — | Password-protect the PDF (requires `qpdf`) |
-| `licenseKey` | `string` | env `RF_LICENSE_KEY` | Subscription key (format `RFSU-…`) |
-| `compressionLevel` | `'auto' \| 'none' \| 'balanced' \| 'max'` | `'auto'` | Screenshot JPEG quality + inline failure cap |
-| `includeScreenshots` | `boolean` | `true` | Embed screenshots in the PDF. Set to `false` to omit images — useful for exec-audience reports or reducing file size. |
-| `maxInlineFailures` | `number` | derived from `compressionLevel` | Cap on inline failures; overflow spills to `{basename}-failures.json` |
-| `maxFileSizeMb` | `number` | `8` | Soft cap; reporter re-renders with `max` compression once if exceeded |
-| `serverUrl` | `string` | `'https://reportforge.org'` | Licensing server base URL (override only for self-hosting) |
-| `open` | `boolean` | `false` | Open PDF after generation (local only) |
-| `shardResults` | `string \| string[]` | — | Glob or path array of Playwright JSON shard files to merge into one PDF. |
-| `notify` | `object` | — | Notification channels: `slack`, `teams`, `discord` (each `{ url, enabled, on }`), `email` (`{ to, enabled, on, attachPdf }`). See [Notifications](#notifications). |
-| `historyFile` | `string` | `~/.reportforge/{key}/history.json` | Path to history JSON. Relative paths resolved from cwd at startup. |
-| `historySize` | `number` | `10` | Max run entries to keep (integer ≥ 2). |
-| `showTrend` | `boolean` | `true` | Set to `false` to disable history write and trend charts entirely. |
-| `flakinessTopN` | `number` | `5` | Max flaky tests to show in the `detailed` template flakiness table. `0` disables the table. |
-| `puppeteerExecutablePath` | `string` | auto-detect | Path to Chrome / Chromium |
+| `outputFile` | `string` | `'playwright-report/{date}-report.pdf'` | Output path. Supports tokens: `{date}`, `{datetime}`, `{branch}`, `{status}`, `{total}`, `{passed}`, `{failed}`, `{project}`. Directory is created if absent. |
+| `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`). |
+| `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. |
+| `logo` | `string` | — | Path to a logo image (PNG, JPG, or SVG) to embed in the report header. Supports absolute and relative paths. |
+| `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` | — | Text to render as a diagonal watermark overlay on every page — e.g. `'CONFIDENTIAL'`, `'DRAFT'`. |
+| `pdfPassword` | `string` | — | Password-protect the generated PDF. Requires `qpdf` installed on the system. |
+| `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. |
+| `puppeteerExecutablePath` | `string` | auto-detect | Full path to a Chrome or Chromium binary. Falls back to `PUPPETEER_EXECUTABLE_PATH` env, then system Chrome discovery. |
+| `serverUrl` | `string` | `'https://reportforge.org'` | Base URL for the ReportForge licensing server. Override only for self-hosting or local development. |
+| `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. |
+| `includeScreenshots` | `boolean` | `true` | Embed Playwright screenshots in the PDF. Set to `false` to omit images — useful for exec-audience reports or reducing file size. |
+| `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. |
+| `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[]` | — | Glob or path array of Playwright JSON shard report files to merge into one PDF. See the Shard Merging docs. |
+| `notify` | `object` | — | Notification channels: `slack`, `teams`, `discord` (each `{ url, enabled, on }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications 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. |
+| `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
+| `templatePath` | `string \| string[]` | — | 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. |
+<!-- AUTOGEN:options-table END -->
 
 Full reference: [reportforge.org/docs#configuration](https://reportforge.org/docs#configuration).
 

package/dist/index.d.mts

@@ -136,9 +136,12 @@ interface ReporterOptions {
      */
     shardResults?: string | string[];
     /**
-     * Webhook notification channels. Post a pass/fail summary after each run.
+     * Notification channels. Post a pass/fail summary after each test run.
      * Each channel must have `enabled: true` to fire (default is `false`).
      * `on` controls the trigger: `'always'` (default), `'failure'`, or `'success'`.
+     *
+     * - `slack` / `teams` / `discord`: webhook URL channels
+     * - `email`: sends via Resend; `to` is required; `attachPdf: true` attaches the PDF
      */
     notify?: {
         slack?: {
@@ -156,6 +159,12 @@ interface ReporterOptions {
             on?: 'always' | 'failure' | 'success';
             enabled?: boolean;
         };
+        email?: {
+            to: string[];
+            on?: 'always' | 'failure' | 'success';
+            enabled?: boolean;
+            attachPdf?: boolean;
+        };
     };
     /**
      * Path to the history JSON file. Defaults to

package/dist/index.d.ts

@@ -136,9 +136,12 @@ interface ReporterOptions {
      */
     shardResults?: string | string[];
     /**
-     * Webhook notification channels. Post a pass/fail summary after each run.
+     * Notification channels. Post a pass/fail summary after each test run.
      * Each channel must have `enabled: true` to fire (default is `false`).
      * `on` controls the trigger: `'always'` (default), `'failure'`, or `'success'`.
+     *
+     * - `slack` / `teams` / `discord`: webhook URL channels
+     * - `email`: sends via Resend; `to` is required; `attachPdf: true` attaches the PDF
      */
     notify?: {
         slack?: {
@@ -156,6 +159,12 @@ interface ReporterOptions {
             on?: 'always' | 'failure' | 'success';
             enabled?: boolean;
         };
+        email?: {
+            to: string[];
+            on?: 'always' | 'failure' | 'success';
+            enabled?: boolean;
+            attachPdf?: boolean;
+        };
     };
     /**
      * Path to the history JSON file. Defaults to

package/dist/index.js

@@ -10971,6 +10971,18 @@ function detectCiEnv() {
       ciProvider: "CircleCI"
     };
   }
+  if (env.BITBUCKET_BUILD_NUMBER) {
+    const workspace = env.BITBUCKET_WORKSPACE;
+    const repoSlug = env.BITBUCKET_REPO_SLUG;
+    const buildNumber = env.BITBUCKET_BUILD_NUMBER;
+    const buildUrl = workspace && repoSlug && buildNumber ? `https://bitbucket.org/${workspace}/${repoSlug}/pipelines/results/${buildNumber}` : "";
+    return {
+      branch: env.BITBUCKET_BRANCH || "unknown",
+      commit: env.BITBUCKET_COMMIT?.slice(0, COMMIT_HASH_LENGTH) || "unknown",
+      buildUrl,
+      ciProvider: "Bitbucket Pipelines"
+    };
+  }
   return {
     branch: gitBranch(),
     commit: gitCommit(),
@@ -11021,6 +11033,13 @@ var DataCollector = class {
       if (existing >= 0) this.failureRecords.splice(existing, 1);
     }
   }
+  /**
+   * Builds the final `ReportData` payload from all accumulated hook data.
+   *
+   * @param fullResult - Playwright's `FullResult` (contains `duration` + `status`).
+   * @returns Structured data for the PDF generator, including projects tree,
+   *   aggregated stats, failures, environment info, and chart inputs.
+   */
   finalize(fullResult) {
     const walker = new SuiteWalker();
     const projects = walker.build(this.rootSuite, this.resultMap);
@@ -11955,6 +11974,15 @@ var import_path6 = __toESM(require("path"));
 var import_fs9 = __toESM(require("fs"));
 var MAX_BRANCH_LENGTH = 50;
 var FilenameResolver = class {
+  /**
+   * Expands `{date}`, `{branch}`, and `{status}` tokens in `template`, then
+   * resolves to an absolute path and creates the parent directory.
+   *
+   * @param template - Output path, possibly relative to `cwd` and possibly
+   *   containing `{date}`, `{branch}`, or `{status}` tokens.
+   * @param ctx - Runtime values for token expansion.
+   * @returns Absolute path with parent directories created.
+   */
   resolve(template, ctx) {
     const date = this.formatDate(ctx.date);
     const branch = this.sanitiseBranch(ctx.branch);
@@ -11964,6 +11992,14 @@ var FilenameResolver = class {
     import_fs9.default.mkdirSync(import_path6.default.dirname(absolute), { recursive: true });
     return absolute;
   }
+  /**
+   * Inserts `suffix` before the file extension so multi-template runs produce
+   * unique filenames from the same base path.
+   *
+   * @example
+   * injectTemplateSuffix('/out/2026-report.pdf', 'executive')
+   * // → '/out/2026-report-executive.pdf'
+   */
   injectTemplateSuffix(outputPath, suffix) {
     const ext = import_path6.default.extname(outputPath);
     const base = outputPath.slice(0, outputPath.length - ext.length);
@@ -12086,6 +12122,24 @@ var PdfGenerator = class {
     } catch {
     }
   }
+  /**
+   * Generates one PDF per template source and returns their absolute output paths.
+   *
+   * Launches a single Puppeteer browser instance shared across all template
+   * renders to avoid the 2–5 s startup cost per template. Each render pass goes
+   * through: failure pagination → screenshot embedding → Handlebars render →
+   * temp HTML write → `page.pdf()`.
+   *
+   * Size cap enforcement: if the first-pass PDF exceeds `options.maxFileSizeMb`,
+   * compression settings are tightened (quality 55, maxWidth 800, inline cap
+   * scaled to fit) and the PDF is re-rendered once. A second overrun warns but
+   * is not re-rendered.
+   *
+   * @param data - Assembled `ReportData` (projects, stats, failures, charts).
+   * @param options - Validated reporter options.
+   * @param _licenseInfo - Kept for API symmetry; unused in this method.
+   * @returns Absolute paths of written PDF files.
+   */
   async generateAll(data, options, _licenseInfo) {
     const sources = this.resolveTemplateSources(options);
     const isMulti = sources.length > 1;
@@ -12616,7 +12670,7 @@ var PdfReporter = class {
     this.dataCollector = new DataCollector();
     this.pdfGenerator = new PdfGenerator();
     this.options = parseOptions(rawOptions);
-    const version = true ? "0.2.0" : "0.x";
+    const version = true ? "0.2.2" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/dist/index.mjs

@@ -10972,6 +10972,18 @@ function detectCiEnv() {
       ciProvider: "CircleCI"
     };
   }
+  if (env.BITBUCKET_BUILD_NUMBER) {
+    const workspace = env.BITBUCKET_WORKSPACE;
+    const repoSlug = env.BITBUCKET_REPO_SLUG;
+    const buildNumber = env.BITBUCKET_BUILD_NUMBER;
+    const buildUrl = workspace && repoSlug && buildNumber ? `https://bitbucket.org/${workspace}/${repoSlug}/pipelines/results/${buildNumber}` : "";
+    return {
+      branch: env.BITBUCKET_BRANCH || "unknown",
+      commit: env.BITBUCKET_COMMIT?.slice(0, COMMIT_HASH_LENGTH) || "unknown",
+      buildUrl,
+      ciProvider: "Bitbucket Pipelines"
+    };
+  }
   return {
     branch: gitBranch(),
     commit: gitCommit(),
@@ -11022,6 +11034,13 @@ var DataCollector = class {
       if (existing >= 0) this.failureRecords.splice(existing, 1);
     }
   }
+  /**
+   * Builds the final `ReportData` payload from all accumulated hook data.
+   *
+   * @param fullResult - Playwright's `FullResult` (contains `duration` + `status`).
+   * @returns Structured data for the PDF generator, including projects tree,
+   *   aggregated stats, failures, environment info, and chart inputs.
+   */
   finalize(fullResult) {
     const walker = new SuiteWalker();
     const projects = walker.build(this.rootSuite, this.resultMap);
@@ -11956,6 +11975,15 @@ import path7 from "path";
 import fs8 from "fs";
 var MAX_BRANCH_LENGTH = 50;
 var FilenameResolver = class {
+  /**
+   * Expands `{date}`, `{branch}`, and `{status}` tokens in `template`, then
+   * resolves to an absolute path and creates the parent directory.
+   *
+   * @param template - Output path, possibly relative to `cwd` and possibly
+   *   containing `{date}`, `{branch}`, or `{status}` tokens.
+   * @param ctx - Runtime values for token expansion.
+   * @returns Absolute path with parent directories created.
+   */
   resolve(template, ctx) {
     const date = this.formatDate(ctx.date);
     const branch = this.sanitiseBranch(ctx.branch);
@@ -11965,6 +11993,14 @@ var FilenameResolver = class {
     fs8.mkdirSync(path7.dirname(absolute), { recursive: true });
     return absolute;
   }
+  /**
+   * Inserts `suffix` before the file extension so multi-template runs produce
+   * unique filenames from the same base path.
+   *
+   * @example
+   * injectTemplateSuffix('/out/2026-report.pdf', 'executive')
+   * // → '/out/2026-report-executive.pdf'
+   */
   injectTemplateSuffix(outputPath, suffix) {
     const ext = path7.extname(outputPath);
     const base = outputPath.slice(0, outputPath.length - ext.length);
@@ -12087,6 +12123,24 @@ var PdfGenerator = class {
     } catch {
     }
   }
+  /**
+   * Generates one PDF per template source and returns their absolute output paths.
+   *
+   * Launches a single Puppeteer browser instance shared across all template
+   * renders to avoid the 2–5 s startup cost per template. Each render pass goes
+   * through: failure pagination → screenshot embedding → Handlebars render →
+   * temp HTML write → `page.pdf()`.
+   *
+   * Size cap enforcement: if the first-pass PDF exceeds `options.maxFileSizeMb`,
+   * compression settings are tightened (quality 55, maxWidth 800, inline cap
+   * scaled to fit) and the PDF is re-rendered once. A second overrun warns but
+   * is not re-rendered.
+   *
+   * @param data - Assembled `ReportData` (projects, stats, failures, charts).
+   * @param options - Validated reporter options.
+   * @param _licenseInfo - Kept for API symmetry; unused in this method.
+   * @returns Absolute paths of written PDF files.
+   */
   async generateAll(data, options, _licenseInfo) {
     const sources = this.resolveTemplateSources(options);
     const isMulti = sources.length > 1;
@@ -12617,7 +12671,7 @@ var PdfReporter = class {
     this.dataCollector = new DataCollector();
     this.pdfGenerator = new PdfGenerator();
     this.options = parseOptions(rawOptions);
-    const version = true ? "0.2.0" : "0.x";
+    const version = true ? "0.2.2" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Enterprise-ready PDF reports for Playwright Test — minimal, detailed, and executive templates with CI/CD integrations",
   "license": "MIT",
   "author": "ReportForge",
@@ -60,7 +60,9 @@
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build",
     "generate-license": "tsx scripts/generate-license.ts",
-    "snapshot-png": "tsx scripts/snapshot-png.ts"
+    "snapshot-png": "tsx scripts/snapshot-png.ts",
+    "docs:gen": "tsx scripts/docs/sync-docs.ts --write",
+    "check:docs": "tsx scripts/docs/sync-docs.ts --check"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40.0",