@reportforge/playwright-pdf 0.9.0 → 0.10.1

package/README.md

@@ -211,7 +211,9 @@ Full reference: [reportforge.org/docs/configuration](https://reportforge.org/doc
 
 ### Live Runs
 
-Watch a run as it happens. With `live` enabled, the reporter prints an unguessable watch link 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. The PDF is still generated at the end, unchanged.
+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 as sub-lines beneath its own row, and the PDF is still generated at the end, unchanged.
+
+> 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).
 
 ```typescript
 // playwright.config.ts
@@ -230,7 +232,7 @@ reporter: [
 
 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.
+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).
 

package/dist/index.d.mts

@@ -442,6 +442,15 @@ declare class PdfReporter implements Reporter {
      * 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

@@ -442,6 +442,15 @@ declare class PdfReporter implements Reporter {
      * 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.js

@@ -13319,6 +13319,22 @@ _${name}_`
 
 // src/notify/formatters/teams.ts
 init_cjs_shims();
+function buildTeamsSimpleMessage(text) {
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [{ type: "TextBlock", text, wrap: true }]
+        }
+      }
+    ]
+  };
+}
 function buildTeamsPayload(stats, pdfPaths, reportTitle) {
   const label = statusLabel(stats.verdict);
   const name = reportName(pdfPaths, reportTitle);
@@ -13525,6 +13541,30 @@ var NotificationSender = class {
     }
     return result;
   }
+  /**
+   * Fire-and-forget "live run started" ping to the enabled chat channels, carrying
+   * the watch URL so teammates can open the live view without hunting through CI
+   * logs. Only channels with `on: 'always'` receive it — a start ping has no
+   * pass/fail outcome, so a `failure`/`success`-only channel is left alone. Never
+   * touches the email channel (too heavy for a start signal). Resolves even if
+   * every post fails; live is best-effort.
+   */
+  async sendLiveStarted(notifyConfig, watchUrl, branch) {
+    if (!notifyConfig) return;
+    const line = `ReportForge: live test run started${branch ? ` on ${branch}` : ""}. Watch: ${watchUrl}`;
+    const payloads = {
+      slack: { text: line },
+      teams: buildTeamsSimpleMessage(line),
+      discord: { content: line }
+    };
+    await Promise.allSettled(
+      Object.keys(payloads).map((name) => {
+        const channel = notifyConfig[name];
+        if (!channel || !channel.enabled || channel.on !== "always") return Promise.resolve();
+        return this.post(`${name} (live-start)`, channel.url, payloads[name]);
+      })
+    );
+  }
   async post(name, url, payload, result) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 1e4);
@@ -13537,10 +13577,10 @@ var NotificationSender = class {
       });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       logger.info(`[notify] ${name}: sent`);
-      result.sent.push(name);
+      result?.sent.push(name);
     } catch (err) {
       logger.warn(`[notify] ${name}: ${err instanceof Error ? err.message : String(err)}`);
-      result.failed.push(name);
+      result?.failed.push(name);
     } finally {
       clearTimeout(timeoutId);
     }
@@ -13582,7 +13622,8 @@ var LiveStreamer = class {
   }
   enqueueTest(update) {
     if (!this.enabled) return;
-    this.testStates.set(update.id, { status: update.status, retry: update.retry });
+    const prevRetry = this.testStates.get(update.id)?.retry;
+    this.testStates.set(update.id, { status: update.status, retry: update.retry ?? prevRetry });
     this.testBuffer.push(update);
     this.capPreLicenseBuffer();
     this.scheduleFlush();
@@ -13712,11 +13753,10 @@ var LiveStreamer = class {
       this.enabled = false;
       this.testBuffer = [];
       this.eventBuffer = [];
-      this.warn("Live streaming disabled \u2014 no active license or live entitlement.");
+      logger.debug("Live streaming disabled \u2014 no active license or live entitlement.");
       return false;
     }
     this.jwt = info.jwt;
-    if (this.config.watchUrl) logger.info(`Live results: ${this.config.watchUrl}`);
     return true;
   }
   async send(body) {
@@ -13776,8 +13816,8 @@ function deriveRunId(opts) {
   if (fromEnv) return fromEnv;
   return detectCiRunId() ?? (0, import_crypto9.randomUUID)();
 }
-function computeWatchToken(runId) {
-  const secret = process.env.RF_LICENSE_KEY?.trim();
+function computeWatchToken(runId, key) {
+  const secret = key?.trim() || process.env.RF_LICENSE_KEY?.trim();
   if (!secret) return null;
   return (0, import_crypto8.createHmac)("sha256", secret).update(`live:${runId}`).digest("hex").slice(0, WATCH_TOKEN_HEX_LEN);
 }
@@ -13785,6 +13825,13 @@ function buildWatchUrl(serverUrl, runId, token) {
   const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
   return `${base}/live/${encodeURIComponent(runId)}?t=${encodeURIComponent(token)}`;
 }
+function formatLiveBanner(url) {
+  const label = "Live Tracker";
+  const link = `Watch live: ${url}`;
+  const width = Math.max(label.length, link.length);
+  const rule = "\u2500".repeat(width + 2);
+  return [rule, ` ${label.padEnd(width)} `, ` ${link.padEnd(width)} `, rule].join("\n");
+}
 function shardKeyOf(shard) {
   if (!shard || !shard.total) return "1/1";
   return `${shard.current}/${shard.total}`;
@@ -13819,6 +13866,17 @@ function shouldEmitStep(step, mode) {
   if (step.error) return true;
   return step.category === "test.step" || step.category === "expect";
 }
+function isCurrentStep(step) {
+  return step.category === "test.step" && !!step.title;
+}
+function mapCurrentStep(testId, step, shardKey) {
+  return {
+    id: testId,
+    status: "running",
+    shardKey,
+    currentStep: clampWithEllipsis(step.title ?? "", MAX_STEP_TITLE_CHARS)
+  };
+}
 function mapStep(testId, step, phase, shardKey) {
   return {
     kind: "step",
@@ -13853,7 +13911,7 @@ var PdfReporter = class {
     this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.9.0" : "0.x";
+    const version = true ? "0.10.1" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -13887,9 +13945,14 @@ var PdfReporter = class {
     }
   }
   onStepBegin(test, _result, step) {
-    if (!this.liveStreamer || !shouldEmitStep(step, this.liveSteps)) return;
+    if (!this.liveStreamer) return;
     try {
-      this.liveStreamer.enqueueEvent(mapStep(test.id, step, "begin", this.liveShardKey));
+      if (this.liveSteps !== "none" && isCurrentStep(step)) {
+        this.liveStreamer.enqueueTest(mapCurrentStep(test.id, step, this.liveShardKey));
+      }
+      if (shouldEmitStep(step, this.liveSteps)) {
+        this.liveStreamer.enqueueEvent(mapStep(test.id, step, "begin", this.liveShardKey));
+      }
     } catch {
     }
   }
@@ -14062,19 +14125,61 @@ var PdfReporter = class {
     this.liveSteps = live.steps;
     this.liveConsole = live.console;
     void this.license();
-    const token = computeWatchToken(runId);
+    const token = computeWatchToken(runId, this.options.licenseKey);
     const watchUrl = token ? buildWatchUrl(serverUrl, runId, token) : void 0;
+    const env = detectCiEnv();
+    if (watchUrl) {
+      void this.announceLive(watchUrl, env, shard).catch(() => {
+      });
+    } else {
+      logger.warn(
+        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
+      );
+    }
     this.liveStreamer = new LiveStreamer({
       serverUrl,
       runId,
       shardKey: this.liveShardKey,
       shardTotal: shard?.total ?? null,
       license: () => this.license(),
-      env: detectCiEnv(),
-      watchUrl,
+      env,
       flushMs: live.flushMs
     });
   }
+  /**
+   * 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.
+   */
+  async announceLive(watchUrl, env, shard) {
+    const info = await this.license();
+    if (!info) {
+      logger.warn("Live is enabled but no active license resolved \u2014 no watch link or streaming.");
+      return;
+    }
+    if (!info.jwt) {
+      logger.warn(
+        "Live is enabled but the license has no signed token (offline with no cached token?) \u2014 no streaming."
+      );
+      return;
+    }
+    if (!info.features?.includes("live")) {
+      logger.warn(
+        "Live is enabled but your license token does not include the 'live' entitlement \u2014 no watch link or streaming. This usually means a cached token predates live streaming and could not be refreshed. Ensure network access on the next run, or delete ~/.reportforge/license.json to force re-activation. If it persists on an active subscription, contact support."
+      );
+      return;
+    }
+    logger.info(`Live Tracker: ${watchUrl}`);
+    console.log(formatLiveBanner(watchUrl));
+    const isPrimaryShard = !shard || shard.current === 1;
+    const notify = this.options.notify;
+    if (isPrimaryShard && notify) {
+      await new NotificationSender().sendLiveStarted(notify, watchUrl, env?.branch);
+    }
+  }
   resolveProjectName() {
     try {
       const pkgPath = import_path12.default.resolve(process.cwd(), "package.json");

package/dist/index.mjs

@@ -13320,6 +13320,22 @@ _${name}_`
 
 // src/notify/formatters/teams.ts
 init_esm_shims();
+function buildTeamsSimpleMessage(text) {
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [{ type: "TextBlock", text, wrap: true }]
+        }
+      }
+    ]
+  };
+}
 function buildTeamsPayload(stats, pdfPaths, reportTitle) {
   const label = statusLabel(stats.verdict);
   const name = reportName(pdfPaths, reportTitle);
@@ -13526,6 +13542,30 @@ var NotificationSender = class {
     }
     return result;
   }
+  /**
+   * Fire-and-forget "live run started" ping to the enabled chat channels, carrying
+   * the watch URL so teammates can open the live view without hunting through CI
+   * logs. Only channels with `on: 'always'` receive it — a start ping has no
+   * pass/fail outcome, so a `failure`/`success`-only channel is left alone. Never
+   * touches the email channel (too heavy for a start signal). Resolves even if
+   * every post fails; live is best-effort.
+   */
+  async sendLiveStarted(notifyConfig, watchUrl, branch) {
+    if (!notifyConfig) return;
+    const line = `ReportForge: live test run started${branch ? ` on ${branch}` : ""}. Watch: ${watchUrl}`;
+    const payloads = {
+      slack: { text: line },
+      teams: buildTeamsSimpleMessage(line),
+      discord: { content: line }
+    };
+    await Promise.allSettled(
+      Object.keys(payloads).map((name) => {
+        const channel = notifyConfig[name];
+        if (!channel || !channel.enabled || channel.on !== "always") return Promise.resolve();
+        return this.post(`${name} (live-start)`, channel.url, payloads[name]);
+      })
+    );
+  }
   async post(name, url, payload, result) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 1e4);
@@ -13538,10 +13578,10 @@ var NotificationSender = class {
       });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       logger.info(`[notify] ${name}: sent`);
-      result.sent.push(name);
+      result?.sent.push(name);
     } catch (err) {
       logger.warn(`[notify] ${name}: ${err instanceof Error ? err.message : String(err)}`);
-      result.failed.push(name);
+      result?.failed.push(name);
     } finally {
       clearTimeout(timeoutId);
     }
@@ -13583,7 +13623,8 @@ var LiveStreamer = class {
   }
   enqueueTest(update) {
     if (!this.enabled) return;
-    this.testStates.set(update.id, { status: update.status, retry: update.retry });
+    const prevRetry = this.testStates.get(update.id)?.retry;
+    this.testStates.set(update.id, { status: update.status, retry: update.retry ?? prevRetry });
     this.testBuffer.push(update);
     this.capPreLicenseBuffer();
     this.scheduleFlush();
@@ -13713,11 +13754,10 @@ var LiveStreamer = class {
       this.enabled = false;
       this.testBuffer = [];
       this.eventBuffer = [];
-      this.warn("Live streaming disabled \u2014 no active license or live entitlement.");
+      logger.debug("Live streaming disabled \u2014 no active license or live entitlement.");
       return false;
     }
     this.jwt = info.jwt;
-    if (this.config.watchUrl) logger.info(`Live results: ${this.config.watchUrl}`);
     return true;
   }
   async send(body) {
@@ -13777,8 +13817,8 @@ function deriveRunId(opts) {
   if (fromEnv) return fromEnv;
   return detectCiRunId() ?? randomUUID2();
 }
-function computeWatchToken(runId) {
-  const secret = process.env.RF_LICENSE_KEY?.trim();
+function computeWatchToken(runId, key) {
+  const secret = key?.trim() || process.env.RF_LICENSE_KEY?.trim();
   if (!secret) return null;
   return createHmac3("sha256", secret).update(`live:${runId}`).digest("hex").slice(0, WATCH_TOKEN_HEX_LEN);
 }
@@ -13786,6 +13826,13 @@ function buildWatchUrl(serverUrl, runId, token) {
   const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
   return `${base}/live/${encodeURIComponent(runId)}?t=${encodeURIComponent(token)}`;
 }
+function formatLiveBanner(url) {
+  const label = "Live Tracker";
+  const link = `Watch live: ${url}`;
+  const width = Math.max(label.length, link.length);
+  const rule = "\u2500".repeat(width + 2);
+  return [rule, ` ${label.padEnd(width)} `, ` ${link.padEnd(width)} `, rule].join("\n");
+}
 function shardKeyOf(shard) {
   if (!shard || !shard.total) return "1/1";
   return `${shard.current}/${shard.total}`;
@@ -13820,6 +13867,17 @@ function shouldEmitStep(step, mode) {
   if (step.error) return true;
   return step.category === "test.step" || step.category === "expect";
 }
+function isCurrentStep(step) {
+  return step.category === "test.step" && !!step.title;
+}
+function mapCurrentStep(testId, step, shardKey) {
+  return {
+    id: testId,
+    status: "running",
+    shardKey,
+    currentStep: clampWithEllipsis(step.title ?? "", MAX_STEP_TITLE_CHARS)
+  };
+}
 function mapStep(testId, step, phase, shardKey) {
   return {
     kind: "step",
@@ -13854,7 +13912,7 @@ var PdfReporter = class {
     this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.9.0" : "0.x";
+    const version = true ? "0.10.1" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -13888,9 +13946,14 @@ var PdfReporter = class {
     }
   }
   onStepBegin(test, _result, step) {
-    if (!this.liveStreamer || !shouldEmitStep(step, this.liveSteps)) return;
+    if (!this.liveStreamer) return;
     try {
-      this.liveStreamer.enqueueEvent(mapStep(test.id, step, "begin", this.liveShardKey));
+      if (this.liveSteps !== "none" && isCurrentStep(step)) {
+        this.liveStreamer.enqueueTest(mapCurrentStep(test.id, step, this.liveShardKey));
+      }
+      if (shouldEmitStep(step, this.liveSteps)) {
+        this.liveStreamer.enqueueEvent(mapStep(test.id, step, "begin", this.liveShardKey));
+      }
     } catch {
     }
   }
@@ -14063,19 +14126,61 @@ var PdfReporter = class {
     this.liveSteps = live.steps;
     this.liveConsole = live.console;
     void this.license();
-    const token = computeWatchToken(runId);
+    const token = computeWatchToken(runId, this.options.licenseKey);
     const watchUrl = token ? buildWatchUrl(serverUrl, runId, token) : void 0;
+    const env = detectCiEnv();
+    if (watchUrl) {
+      void this.announceLive(watchUrl, env, shard).catch(() => {
+      });
+    } else {
+      logger.warn(
+        "Live is enabled but no RF_LICENSE_KEY was found \u2014 cannot mint a watch link or stream. Set RF_LICENSE_KEY (or the `licenseKey` option)."
+      );
+    }
     this.liveStreamer = new LiveStreamer({
       serverUrl,
       runId,
       shardKey: this.liveShardKey,
       shardTotal: shard?.total ?? null,
       license: () => this.license(),
-      env: detectCiEnv(),
-      watchUrl,
+      env,
       flushMs: live.flushMs
     });
   }
+  /**
+   * 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.
+   */
+  async announceLive(watchUrl, env, shard) {
+    const info = await this.license();
+    if (!info) {
+      logger.warn("Live is enabled but no active license resolved \u2014 no watch link or streaming.");
+      return;
+    }
+    if (!info.jwt) {
+      logger.warn(
+        "Live is enabled but the license has no signed token (offline with no cached token?) \u2014 no streaming."
+      );
+      return;
+    }
+    if (!info.features?.includes("live")) {
+      logger.warn(
+        "Live is enabled but your license token does not include the 'live' entitlement \u2014 no watch link or streaming. This usually means a cached token predates live streaming and could not be refreshed. Ensure network access on the next run, or delete ~/.reportforge/license.json to force re-activation. If it persists on an active subscription, contact support."
+      );
+      return;
+    }
+    logger.info(`Live Tracker: ${watchUrl}`);
+    console.log(formatLiveBanner(watchUrl));
+    const isPrimaryShard = !shard || shard.current === 1;
+    const notify = this.options.notify;
+    if (isPrimaryShard && notify) {
+      await new NotificationSender().sendLiveStarted(notify, watchUrl, env?.branch);
+    }
+  }
   resolveProjectName() {
     try {
       const pkgPath = path14.resolve(process.cwd(), "package.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Enterprise-ready PDF reports for Playwright Test — minimal, detailed, and executive templates with CI/CD integrations",
   "license": "MIT",
   "author": "ReportForge",