@reportforge/playwright-pdf 0.8.1 → 0.10.0

package/README.md

@@ -53,6 +53,7 @@ Three templates, one reporter. Every PDF is fully offline — fonts, charts, and
 - **Dynamic filenames** — `{date}`, `{branch}`, `{status}` tokens in the output path
 - **Instant demo report** — `npx @reportforge/playwright-pdf demo` generates a realistic sample PDF before subscribing — no license key required
 - **CI/CD snippets** — GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
+- **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
 - **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 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)
@@ -196,6 +197,7 @@ All options are the second element of the reporter tuple.
 | `notify` | `object` | — | Notification channels: `slack`, `teams`, `discord` (each `{ url, enabled, on }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications docs. |
 | `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. |
 | `capture` | `object` | `{}` (off) | Opt-in rich execution capture for the defect log (reporter-side; no fixtures, no test-code changes). Fields: `steps` (compacted repro-steps trail from the Playwright step tree, default `false`), `apiSteps` (include granular `pw:api` click/fill/goto actions in the trail; off by default the trail shows only `test.step` intent + `expect` assertions + the failing action, 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. |
+| `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`\|`all`, default `failed`), `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. |
@@ -207,6 +209,31 @@ All options are the second element of the reporter tuple.
 
 Full reference: [reportforge.org/docs/configuration](https://reportforge.org/docs/configuration).
 
+### Live Runs
+
+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 running test shows the step it's currently executing, and the PDF is still generated at the end, unchanged.
+
+```typescript
+// playwright.config.ts
+reporter: [
+  ['@reportforge/playwright-pdf', {
+    outputFile: 'reports/{date}-report.pdf',
+    live: {
+      enabled: true,
+      steps: 'failed',   // 'none' | 'failed' | 'all'
+      // console: false,  // stream stdout/stderr tails (off by default — see note)
+      // flushMs: 2000,   // batch debounce (500–10000)
+    },
+  }],
+],
+```
+
+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.
+
+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.
+
+> **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).
+
 ### Shard Merging
 
 Combine parallel Playwright shards into one PDF without re-running any tests.
@@ -629,6 +656,7 @@ Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
 - [Configuration reference](https://reportforge.org/docs/configuration) — all options
 - [Filename tokens](https://reportforge.org/docs/configuration#tokens) — `{date}`, `{branch}`, `{status}`
 - [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
 - [Troubleshooting](https://reportforge.org/docs/troubleshooting) — common issues and debug flags

package/dist/cli/index.js

@@ -11831,7 +11831,7 @@ ${issues}`);
   }
   return result.data;
 }
-var hexColor, channelConfigSchema, emailChannelConfigSchema, notifyConfigSchema, failureAnalysisConfigSchema, captureConfigSchema, sectionFlagsShape, sectionFlagsSchema, sectionsSchema, ReporterOptionsSchema;
+var hexColor, channelConfigSchema, emailChannelConfigSchema, notifyConfigSchema, failureAnalysisConfigSchema, captureConfigSchema, liveConfigSchema, sectionFlagsShape, sectionFlagsSchema, sectionsSchema, ReporterOptionsSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
@@ -11878,6 +11878,21 @@ var init_schema = __esm({
       maxSteps: external_exports.number().int().min(1).max(500).default(50),
       maxConsoleLines: external_exports.number().int().min(1).max(1e3).default(50)
     }).default({});
+    liveConfigSchema = external_exports.object({
+      enabled: external_exports.boolean().default(false),
+      // Override the auto-derived run id. All shards of one run must share it.
+      runId: external_exports.string().optional(),
+      // Override the streaming/server base URL (defaults to the license serverUrl).
+      serverUrl: external_exports.string().url().optional(),
+      // Step verbosity: 'none' skips steps, 'failed' streams intent + assertions +
+      // errored steps, 'all' streams every step.
+      steps: external_exports.enum(["none", "failed", "all"]).default("failed"),
+      // Stream test stdout/stderr tails. Off by default — may leak secrets printed
+      // by tests to a token-holder.
+      console: external_exports.boolean().default(false),
+      // Debounce window for batched flushes (ms).
+      flushMs: external_exports.number().int().min(500).max(1e4).default(2e3)
+    }).default({});
     sectionFlagsShape = Object.fromEntries(
       SECTION_KEYS.map((k) => [k, external_exports.boolean().optional()])
     );
@@ -11919,6 +11934,7 @@ var init_schema = __esm({
       slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
       failureAnalysis: failureAnalysisConfigSchema,
       capture: captureConfigSchema,
+      live: liveConfigSchema,
       templatePath: external_exports.union([
         external_exports.string().regex(/\.hbs$/, "templatePath must end with .hbs").refine((v) => v.slice(0, -4).trim().length > 0, "templatePath basename must not be empty"),
         external_exports.array(

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Reporter, FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult } from '@playwright/test/reporter';
 
 /**
  * Canonical section catalog. 13 block toggles (section present/absent) followed
@@ -237,6 +237,38 @@ interface ReporterOptions {
         /** Max console lines retained per stream. Default: 50 */
         maxConsoleLines?: number;
     };
+    /**
+     * Live test-execution streaming (opt-in, off by default). When enabled the
+     * reporter mints an unguessable watch link, prints it to the CI logs at run
+     * start, and streams per-test progress (and optionally per-step / console
+     * tails) to the hosted dashboard while your tests run. All shards of one CI
+     * run converge on a single live view automatically. The PDF generated at the
+     * end of the run is unaffected. Requires an active subscription with the
+     * `live` entitlement; degrades to a no-op otherwise.
+     *
+     * @example
+     * live: { enabled: true, steps: 'all' }
+     */
+    live?: {
+        /** Enable live streaming. Default: false */
+        enabled?: boolean;
+        /** Override the auto-derived run id. All shards of one run must share it. */
+        runId?: string;
+        /** Override the streaming server base URL. Defaults to the license `serverUrl`. */
+        serverUrl?: string;
+        /**
+         * Step verbosity: `'none'` skips steps, `'failed'` streams author intent +
+         * assertions + errored steps, `'all'` streams every step. Default: `'failed'`
+         */
+        steps?: 'none' | 'failed' | 'all';
+        /**
+         * Stream test stdout/stderr tails to the watch page. Off by default — may
+         * leak secrets printed by tests to anyone holding the watch link. Default: false
+         */
+        console?: boolean;
+        /** Debounce window for batched flushes, in milliseconds (500–10000). Default: 2000 */
+        flushMs?: number;
+    };
     /**
      * Path to the history JSON file. Defaults to
      * `~/.reportforge/{projectKey}/history.json` where `projectKey` is derived
@@ -330,6 +362,13 @@ interface LicenseInfo {
     jwt?: string;
     machinesUsed?: number;
     machineLimit?: number;
+    /**
+     * Entitlement flags carried on the signed JWT (`features` claim). Surfaces
+     * server-gated capabilities (e.g. `'live'`) to the reporter without a second
+     * network trip. Undefined for caches written by reporter versions before this
+     * field was persisted — treat absence as "no extra features".
+     */
+    features?: string[];
 }
 
 /**
@@ -371,16 +410,47 @@ declare class PdfReporter implements Reporter {
     private readonly licenseClient;
     private readonly dataCollector;
     private readonly pdfGenerator;
+    private licensePromise?;
+    private liveStreamer?;
+    private liveShardKey;
+    private liveSteps;
+    private liveConsole;
     constructor(rawOptions?: ReporterOptions);
     onBegin(config: FullConfig, suite: Suite): void;
+    onTestBegin(test: TestCase): void;
     onTestEnd(test: TestCase, result: TestResult): void;
+    onStepBegin(test: TestCase, _result: TestResult, step: TestStep): void;
+    onStepEnd(test: TestCase, _result: TestResult, step: TestStep): void;
+    onStdOut(chunk: string | Buffer, test?: TestCase): void;
+    onStdErr(chunk: string | Buffer, test?: TestCase): void;
+    onExit(): Promise<void>;
     onEnd(result: FullResult): Promise<void>;
     private _collectData;
     private _appendTrend;
     private _populateHistoryCharts;
     private _buildReportData;
     printsToStdio(): boolean;
+    /**
+     * Memoized license resolution shared by the live stream (kicked early in
+     * onBegin) and PDF generation (awaited in onEnd) — at most one network trip.
+     */
+    private license;
     private resolveLicense;
+    /**
+     * Wires up live streaming: derives the run id (shared by all shards), kicks
+     * the license resolution early, builds the streamer, and prints the watch
+     * link to the CI logs. Throws are caught by the onBegin try/catch.
+     */
+    private setupLive;
+    /**
+     * Announces the watch link once the run is confirmed live-entitled. Gating on
+     * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
+     * feature) guarantees the link is never printed or posted for a run that will
+     * never stream — no dead links. The chat ping fires from the primary shard only
+     * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
+     * not N. The banner still prints from every shard's own log.
+     */
+    private announceLive;
     private resolveProjectName;
     private openPdf;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Reporter, FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
+import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult } from '@playwright/test/reporter';
 
 /**
  * Canonical section catalog. 13 block toggles (section present/absent) followed
@@ -237,6 +237,38 @@ interface ReporterOptions {
         /** Max console lines retained per stream. Default: 50 */
         maxConsoleLines?: number;
     };
+    /**
+     * Live test-execution streaming (opt-in, off by default). When enabled the
+     * reporter mints an unguessable watch link, prints it to the CI logs at run
+     * start, and streams per-test progress (and optionally per-step / console
+     * tails) to the hosted dashboard while your tests run. All shards of one CI
+     * run converge on a single live view automatically. The PDF generated at the
+     * end of the run is unaffected. Requires an active subscription with the
+     * `live` entitlement; degrades to a no-op otherwise.
+     *
+     * @example
+     * live: { enabled: true, steps: 'all' }
+     */
+    live?: {
+        /** Enable live streaming. Default: false */
+        enabled?: boolean;
+        /** Override the auto-derived run id. All shards of one run must share it. */
+        runId?: string;
+        /** Override the streaming server base URL. Defaults to the license `serverUrl`. */
+        serverUrl?: string;
+        /**
+         * Step verbosity: `'none'` skips steps, `'failed'` streams author intent +
+         * assertions + errored steps, `'all'` streams every step. Default: `'failed'`
+         */
+        steps?: 'none' | 'failed' | 'all';
+        /**
+         * Stream test stdout/stderr tails to the watch page. Off by default — may
+         * leak secrets printed by tests to anyone holding the watch link. Default: false
+         */
+        console?: boolean;
+        /** Debounce window for batched flushes, in milliseconds (500–10000). Default: 2000 */
+        flushMs?: number;
+    };
     /**
      * Path to the history JSON file. Defaults to
      * `~/.reportforge/{projectKey}/history.json` where `projectKey` is derived
@@ -330,6 +362,13 @@ interface LicenseInfo {
     jwt?: string;
     machinesUsed?: number;
     machineLimit?: number;
+    /**
+     * Entitlement flags carried on the signed JWT (`features` claim). Surfaces
+     * server-gated capabilities (e.g. `'live'`) to the reporter without a second
+     * network trip. Undefined for caches written by reporter versions before this
+     * field was persisted — treat absence as "no extra features".
+     */
+    features?: string[];
 }
 
 /**
@@ -371,16 +410,47 @@ declare class PdfReporter implements Reporter {
     private readonly licenseClient;
     private readonly dataCollector;
     private readonly pdfGenerator;
+    private licensePromise?;
+    private liveStreamer?;
+    private liveShardKey;
+    private liveSteps;
+    private liveConsole;
     constructor(rawOptions?: ReporterOptions);
     onBegin(config: FullConfig, suite: Suite): void;
+    onTestBegin(test: TestCase): void;
     onTestEnd(test: TestCase, result: TestResult): void;
+    onStepBegin(test: TestCase, _result: TestResult, step: TestStep): void;
+    onStepEnd(test: TestCase, _result: TestResult, step: TestStep): void;
+    onStdOut(chunk: string | Buffer, test?: TestCase): void;
+    onStdErr(chunk: string | Buffer, test?: TestCase): void;
+    onExit(): Promise<void>;
     onEnd(result: FullResult): Promise<void>;
     private _collectData;
     private _appendTrend;
     private _populateHistoryCharts;
     private _buildReportData;
     printsToStdio(): boolean;
+    /**
+     * Memoized license resolution shared by the live stream (kicked early in
+     * onBegin) and PDF generation (awaited in onEnd) — at most one network trip.
+     */
+    private license;
     private resolveLicense;
+    /**
+     * Wires up live streaming: derives the run id (shared by all shards), kicks
+     * the license resolution early, builds the streamer, and prints the watch
+     * link to the CI logs. Throws are caught by the onBegin try/catch.
+     */
+    private setupLive;
+    /**
+     * Announces the watch link once the run is confirmed live-entitled. Gating on
+     * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
+     * feature) guarantees the link is never printed or posted for a run that will
+     * never stream — no dead links. The chat ping fires from the primary shard only
+     * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
+     * not N. The banner still prints from every shard's own log.
+     */
+    private announceLive;
     private resolveProjectName;
     private openPdf;
 }