@reportforge/playwright-pdf 0.0.1 → 0.2.0

package/README.md

@@ -53,7 +53,8 @@ Three templates, one reporter. Every PDF is fully offline — fonts, charts, and
 - **Dynamic filenames** — `{date}`, `{branch}`, `{status}` tokens in the output path
 - **CI/CD snippets** — GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
 - **Shard merging** — combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
-- **Webhook notifications** — post pass/fail summaries to Slack, Teams, or Discord on every run; configurable per channel with `on: 'always' | 'failure' | 'success'`
+- **Notifications** — post pass/fail summaries to Slack, Teams, Discord, or email after each run; configurable trigger (`always` / `failure` / `success`) per channel; email supports 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)
 - **Hybrid licensing** — one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
 
 ---
@@ -183,10 +184,11 @@ All options are the second element of the reporter tuple.
 | `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` | — | Webhook notification channels. See [Webhook Notifications](#webhook-notifications). |
+| `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 sparkline entirely. |
+| `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 |
 
 Full reference: [reportforge.org/docs#configuration](https://reportforge.org/docs#configuration).
@@ -215,30 +217,37 @@ The merge step can run against a dummy test file with zero tests — `shardResul
 
 > **Note:** Timed-out tests are counted as failures in shard mode (Playwright JSON stats do not distinguish `timedOut` from `failed`).
 
-### Webhook Notifications
+### Notifications
 
-Post a summary message to Slack, Teams, or Discord after each run.
+Post a summary to Slack, Teams, Discord, or email after each run.
 
 ```typescript
 notify: {
   slack: {
-    url: 'https://hooks.slack.com/services/...',
-    enabled: true,               // required — defaults to false
-    on: 'always',                // 'always' | 'failure' | 'success'  (default: 'always')
+    url: process.env.SLACK_WEBHOOK_URL,
+    enabled: true,
+    on: 'failure',               // 'always' | 'failure' | 'success'  (default: 'always')
   },
   teams: {
-    url: 'https://outlook.office.com/webhook/...',
+    url: process.env.TEAMS_WEBHOOK_URL,
     enabled: true,
-    on: 'failure',
+    on: 'always',
   },
   discord: {
-    url: 'https://discord.com/api/webhooks/...',
+    url: process.env.DISCORD_WEBHOOK_URL,
+    enabled: true,
+    on: 'failure',
+  },
+  email: {
+    to: ['team@company.com', 'qa@company.com'],
     enabled: true,
+    on: 'failure',
+    attachPdf: false,            // set true to attach the generated PDF
   },
 },
 ```
 
-Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it — useful for staging configs. Set `enabled: true` to activate.
+Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it — useful for staging configs.
 
 The `on` trigger controls when the message fires:
 
@@ -248,7 +257,9 @@ The `on` trigger controls when the message fires:
 | `'failure'` | `stats.failed > 0` or run timed out / interrupted |
 | `'success'` | All tests passed |
 
-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 generation failure — you still get the ping).
+**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.
+
+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).
 
 ### Test History Trending
 
@@ -277,6 +288,19 @@ reporter: [['@reportforge/playwright-pdf', {
 
 **Monorepo** — each package needs a distinct `historyFile` (e.g. `.reportforge/api-history.json`, `.reportforge/web-history.json`) so runs do not overwrite each other.
 
+### Flakiness Trend Table
+
+The `detailed` template includes a **Top flaky tests** table showing which tests flake most often across your stored history. Each row shows the test name, flake rate (%), run count, and a dot sparkline (amber dot = flaky in that run).
+
+```typescript
+reporter: [['@reportforge/playwright-pdf', {
+  template: 'detailed',
+  flakinessTopN: 5,    // default — show top 5; set 0 to disable
+}]]
+```
+
+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.
+
 ### Filename tokens
 
 | Token | Replaced with | Example |

package/dist/index.d.mts

@@ -176,6 +176,24 @@ interface ReporterOptions {
      * @default true
      */
     showTrend?: boolean;
+    /**
+     * Number of flaky tests to display in the flakiness table (detailed template).
+     * Set to 0 to disable. Must be a non-negative integer.
+     * @default 5
+     */
+    flakinessTopN?: number;
+    /**
+     * Path to a custom Handlebars (.hbs) template file. When set, takes
+     * precedence over `template`. Relative paths resolve from `process.cwd()`.
+     * Pass an array to generate one PDF per template in a single run — each
+     * output filename gets the template basename injected automatically.
+     *
+     * @example
+     * templatePath: './templates/brand-report.hbs'
+     * @example
+     * templatePath: ['./templates/exec.hbs', './templates/eng.hbs']
+     */
+    templatePath?: string | string[];
 }
 
 /**
@@ -244,6 +262,7 @@ declare class PdfReporter implements Reporter {
     onEnd(result: FullResult): Promise<void>;
     private _collectData;
     private _appendTrend;
+    private _populateHistoryCharts;
     private _buildReportData;
     printsToStdio(): boolean;
     private resolveLicense;

package/dist/index.d.ts

@@ -176,6 +176,24 @@ interface ReporterOptions {
      * @default true
      */
     showTrend?: boolean;
+    /**
+     * Number of flaky tests to display in the flakiness table (detailed template).
+     * Set to 0 to disable. Must be a non-negative integer.
+     * @default 5
+     */
+    flakinessTopN?: number;
+    /**
+     * Path to a custom Handlebars (.hbs) template file. When set, takes
+     * precedence over `template`. Relative paths resolve from `process.cwd()`.
+     * Pass an array to generate one PDF per template in a single run — each
+     * output filename gets the template basename injected automatically.
+     *
+     * @example
+     * templatePath: './templates/brand-report.hbs'
+     * @example
+     * templatePath: ['./templates/exec.hbs', './templates/eng.hbs']
+     */
+    templatePath?: string | string[];
 }
 
 /**
@@ -244,6 +262,7 @@ declare class PdfReporter implements Reporter {
     onEnd(result: FullResult): Promise<void>;
     private _collectData;
     private _appendTrend;
+    private _populateHistoryCharts;
     private _buildReportData;
     printsToStdio(): boolean;
     private resolveLicense;