@reportforge/playwright-pdf 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.5.0] — 2026-06-19
+
+### Added
+
+- **Timed-out tests are first-class** — surfaced as their own KPI card, pass-rate doughnut slice, and Suite Results bar segment instead of being folded into "Failed".
+- **Release gate on every template** — the ship/hold verdict banner now appears in `minimal` and `detailed`, not just `executive`.
+- **Severity-ranked failures** — failure cards are colour-coded and ordered critical-first (also drives defect-log numbering and sidecar-overflow priority).
+- **Describe-block Suite Results** — a single-file run breaks down by describe block instead of rendering one bar.
+- **Threshold-coloured requirements coverage bars** — red `<50%`, amber `<80%`, green `≥80%`.
+
+### Changed
+
+- **Compact page flow** — large sections flow and break between rows instead of each starting on a fresh page; a typical `detailed` run drops ~2 pages.
+- The pass-rate verdict renders "TIMED OUT" instead of "TIMEDOUT".
+
+### Fixed
+
+- **Pass rate could exceed 100%** on runs with flaky tests — a passed-on-retry test was double-counted in both `passed` and `flaky`. It is now counted as flaky only, so the rate is correct and the KPI cards reconcile to the total.
+- The pass-rate doughnut centre now matches the KPI strip (single source of truth) rather than computing a second, divergent figure.
+- Timed-out status badges render with the correct styling, and timed-out tests are recovered in sharded (`shardResults`) runs instead of being reported as failures.
+
+---
+
+## [0.4.0] — 2026-06-12
+
+### Added
+
+- **Failure analysis** — every failed test is classified into one of seven root-cause categories (assertion, timeout, selector/locator, network, and more) and failures that share a cause are grouped into clusters, rendered as a ranked breakdown in the `detailed` template. Classification runs fully offline — no network call, no AI service. The classifier model refreshes from the licensing server in the background (offline-tolerant; the bundled model is always the floor), with optional privacy-preserving local feedback collection. See `docs/advanced/failure-analysis`.
+
+---
+
 ## [0.3.1] — 2026-06-09
 
 ### Security

package/README.md

@@ -56,7 +56,7 @@ Three templates, one reporter. Every PDF is fully offline — fonts, charts, and
 - **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)
-- **Offline failure analysis** — classifies failures into 7 root-cause categories, clusters them, and renders a breakdown in the `detailed` PDF (one-liner in `executive`). No network, no AI service. The classifier model auto-updates offline over the existing license-refresh channel — each delivered model is Ed25519-signed and verified against the bundled public key, with the bundled model always the floor; set `failureAnalysis.autoUpdateModel: false` to pin the bundled model.
+- **Offline failure analysis** — sorts failures into 7 root-cause buckets and clusters them, right inside the `detailed` PDF (one-liner in `executive`). No network, no AI service — a small embedded classifier that updates itself safely 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).
 - `reportforge-export-feedback` — exports locally-collected unrecognized failures (tokenized, local-only) for optional manual sharing.
 - **Hybrid licensing** — one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
 
@@ -334,6 +334,10 @@ Everything in `minimal`, **plus** Chart.js pass-rate + suite-results charts, a n
 
 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.
 
+### Shared across all three
+
+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%).
+
 ### Generating multiple templates in one run
 
 Pass an array to `template` to generate one PDF per template from a single test run. The template name is appended to the output filename automatically:

package/dist/demo/cli.js

@@ -6251,7 +6251,8 @@ function statsFromTests(tests) {
   return {
     total: tests.length,
     passed: tests.filter((t) => t.status === "passed").length,
-    failed: tests.filter((t) => t.status === "failed" || t.status === "timedOut").length,
+    failed: tests.filter((t) => t.status === "failed").length,
+    timedOut: tests.filter((t) => t.status === "timedOut").length,
     skipped: tests.filter((t) => t.status === "skipped").length,
     flaky: tests.filter((t) => t.status === "flaky").length
   };
@@ -6381,7 +6382,7 @@ function buildDemoFailures() {
 }
 function buildDemoCharts(passed, failed, skipped, flaky, total) {
   return {
-    passRate: { passed, failed, skipped, flaky },
+    passRate: { passed, failed, timedOut: 0, skipped, flaky },
     suiteResults: [
       suiteEntry("auth", DEMO_AUTH_TESTS),
       suiteEntry("checkout", DEMO_CHECKOUT_TESTS),
@@ -6714,6 +6715,19 @@ var TemplateEngine = class {
       "upperCase",
       (s) => typeof s === "string" ? s.toUpperCase() : s
     );
+    this.handlebars.registerHelper("verdictLabel", (v) => {
+      const map = {
+        passed: "PASSED",
+        failed: "FAILED",
+        timedout: "TIMED OUT",
+        interrupted: "INTERRUPTED"
+      };
+      return map[v] ?? (typeof v === "string" ? v.toUpperCase() : v);
+    });
+    this.handlebars.registerHelper("coverageBand", (pct) => {
+      const n = Number(pct);
+      return n >= 80 ? "high" : n >= 50 ? "mid" : "low";
+    });
     this.handlebars.registerHelper("addOne", (n) => (n ?? 0) + 1);
     this.handlebars.registerHelper(
       "join",

package/dist/index.js

@@ -11215,16 +11215,31 @@ function runFailureAnalysis(reportData, options, cwd) {
 // src/collector/DataCollector.ts
 init_cjs_shims();
 
+// src/utils/strip-ansi.ts
+init_cjs_shims();
+var ANSI_PATTERN = new RegExp(
+  [
+    "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)",
+    "(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))"
+  ].join("|"),
+  "g"
+);
+function stripAnsi(input) {
+  return input.replace(ANSI_PATTERN, "");
+}
+
 // src/collector/SuiteWalker.ts
 init_cjs_shims();
 
 // src/collector/stats-utils.ts
 init_cjs_shims();
+var TOP_SUITES_FOR_CHART = 10;
 function statsFromTests(tests) {
   return {
     total: tests.length,
     passed: tests.filter((t) => t.status === "passed").length,
-    failed: tests.filter((t) => t.status === "failed" || t.status === "timedOut").length,
+    failed: tests.filter((t) => t.status === "failed").length,
+    timedOut: tests.filter((t) => t.status === "timedOut").length,
     skipped: tests.filter((t) => t.status === "skipped").length,
     flaky: tests.filter((t) => t.status === "flaky").length
   };
@@ -11235,12 +11250,32 @@ function aggregateStats(parts) {
       total: acc.total + s.total,
       passed: acc.passed + s.passed,
       failed: acc.failed + s.failed,
+      timedOut: acc.timedOut + s.timedOut,
       skipped: acc.skipped + s.skipped,
       flaky: acc.flaky + s.flaky
     }),
-    { total: 0, passed: 0, failed: 0, skipped: 0, flaky: 0 }
+    { total: 0, passed: 0, failed: 0, timedOut: 0, skipped: 0, flaky: 0 }
   );
 }
+function toRow(s) {
+  return {
+    label: s.title,
+    passed: s.stats.passed,
+    failed: s.stats.failed,
+    timedOut: s.stats.timedOut,
+    skipped: s.stats.skipped
+  };
+}
+function buildSuiteResults(projects, limit) {
+  const top = projects.flatMap((p) => p.suites);
+  if (top.length <= 1 && top[0] && top[0].suites.length > 0) {
+    const file = top[0];
+    const fs14 = statsFromTests(file.tests);
+    const rootRow = file.tests.length > 0 ? [{ label: file.title, passed: fs14.passed, failed: fs14.failed, timedOut: fs14.timedOut, skipped: fs14.skipped }] : [];
+    return [...rootRow, ...file.suites.map(toRow)].slice(0, limit);
+  }
+  return top.map(toRow).slice(0, limit);
+}
 
 // src/collector/SuiteWalker.ts
 var SuiteWalker = class {
@@ -11300,6 +11335,18 @@ var SuiteWalker = class {
   }
 };
 
+// src/collector/severity.ts
+init_cjs_shims();
+var SEVERITY_RANK = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3
+};
+function sortBySeverity(failures) {
+  return [...failures].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
+}
+
 // src/utils/env.ts
 init_cjs_shims();
 var import_child_process = require("child_process");
@@ -11389,7 +11436,6 @@ function gitCommit() {
 }
 
 // src/collector/DataCollector.ts
-var TOP_SUITES_FOR_CHART = 10;
 var DataCollector = class {
   constructor() {
     this.resultMap = /* @__PURE__ */ new Map();
@@ -11426,13 +11472,13 @@ var DataCollector = class {
   finalize(fullResult) {
     const walker = new SuiteWalker();
     const projects = walker.build(this.rootSuite, this.resultMap);
-    const stats = this.computeStats(projects, fullResult);
+    const stats = this.computeStats(fullResult);
     const environment = this.buildEnvironment();
     const charts = this.buildChartData(stats, projects);
     return {
       projects,
       stats,
-      failures: [...this.failureRecords],
+      failures: sortBySeverity(this.failureRecords),
       environment,
       charts
     };
@@ -11449,8 +11495,8 @@ var DataCollector = class {
       testTitle: test.title,
       suitePath,
       error: {
-        message: error.message ?? String(error),
-        stack: error.stack
+        message: stripAnsi(error.message ?? String(error)),
+        stack: error.stack ? stripAnsi(error.stack) : void 0
       },
       screenshotPath: screenshotAttachment?.path,
       screenshotBuffer: screenshotAttachment?.body,
@@ -11476,13 +11522,16 @@ var DataCollector = class {
     if (allLabels.some((l) => l.includes("low") || l.includes("minor"))) return "low";
     return "medium";
   }
-  computeStats(projects, fullResult) {
+  computeStats(fullResult) {
     let total = 0, passed = 0, failed = 0, skipped = 0, flaky = 0, timedOut = 0;
     for (const [, result] of this.resultMap) {
       total++;
       switch (result.status) {
+        // A test that passes on a retry (retry > 0) is flaky, NOT a clean pass.
+        // Counting it in `passed` too would double-count it against `flaky` and
+        // push passRate over 100%.
         case "passed":
-          passed++;
+          result.retry > 0 ? flaky++ : passed++;
           break;
         case "failed":
           failed++;
@@ -11499,13 +11548,6 @@ var DataCollector = class {
           break;
       }
     }
-    for (const project of projects) {
-      for (const suite of this.flattenSuites(project.suites)) {
-        for (const test of suite.tests) {
-          if (test.status === "flaky") flaky++;
-        }
-      }
-    }
     const duration = fullResult.duration ?? Date.now() - this.startTime;
     const passRate = total > 0 ? Math.round((passed + flaky) / total * 100) : 0;
     return {
@@ -11551,27 +11593,18 @@ var DataCollector = class {
     };
   }
   buildChartData(stats, projects) {
-    const suiteResults = projects.flatMap(
-      (p) => p.suites.map((s) => ({
-        label: s.title,
-        passed: s.stats.passed,
-        failed: s.stats.failed,
-        skipped: s.stats.skipped
-      }))
-    ).slice(0, TOP_SUITES_FOR_CHART);
+    const suiteResults = buildSuiteResults(projects, TOP_SUITES_FOR_CHART);
     return {
       passRate: {
         passed: stats.passed,
         failed: stats.failed,
+        timedOut: stats.timedOut,
         skipped: stats.skipped,
         flaky: stats.flaky
       },
       suiteResults
     };
   }
-  flattenSuites(suites) {
-    return suites.flatMap((s) => [s, ...this.flattenSuites(s.suites)]);
-  }
 };
 
 // src/collector/ShardMerger.ts
@@ -11579,15 +11612,14 @@ init_cjs_shims();
 var import_fs3 = require("fs");
 var import_glob = require("glob");
 var import_node_module = require("module");
-var TOP_SUITES_FOR_CHART2 = 10;
 var ShardMerger = class {
   merge(filePaths) {
     if (filePaths.length === 0) throw new Error("shardResults: no valid JSON shard files found");
     const resolved = this.resolveShardPaths(filePaths);
     const reports = this.loadReports(resolved);
     const projects = this.mergeProjects(reports);
-    const stats = this.mergeStats(reports);
-    const failures = this.extractFailures(reports);
+    const stats = this.mergeStats(reports, projects);
+    const failures = sortBySeverity(this.extractFailures(reports));
     const environment = this.buildEnvironment(reports[0]);
     const charts = this.buildCharts(stats, projects);
     return { projects, stats, failures, environment, charts };
@@ -11694,7 +11726,7 @@ var ShardMerger = class {
       id: spec.id,
       title: spec.title,
       fullTitle: [...suitePath, spec.title].join(" > "),
-      status: this.resolveStatus(test),
+      status: this.resolveStatus(test, lastResult),
       duration: lastResult?.duration ?? 0,
       retryCount: test ? test.results.length - 1 : 0,
       tags: spec.tags ?? [],
@@ -11702,8 +11734,9 @@ var ShardMerger = class {
       location: `${spec.file}:${spec.line}`
     };
   }
-  resolveStatus(test) {
+  resolveStatus(test, lastResult) {
     if (!test) return "skipped";
+    if (lastResult?.status === "timedOut") return "timedOut";
     switch (test.status) {
       case "expected":
         return "passed";
@@ -11717,7 +11750,7 @@ var ShardMerger = class {
         return "failed";
     }
   }
-  mergeStats(reports) {
+  mergeStats(reports, projects) {
     let expected = 0, unexpected = 0, flaky = 0, skipped = 0, maxDuration = 0;
     for (const r of reports) {
       expected += r.stats.expected;
@@ -11728,13 +11761,14 @@ var ShardMerger = class {
     }
     const total = expected + unexpected + flaky + skipped;
     const passRate = total > 0 ? Math.round((expected + flaky) / total * 100) : 0;
+    const timedOut = projects.reduce((n, p) => n + p.stats.timedOut, 0);
     return {
       total,
       passed: expected,
-      failed: unexpected,
+      failed: Math.max(0, unexpected - timedOut),
       skipped,
       flaky,
-      timedOut: 0,
+      timedOut,
       duration: maxDuration,
       passRate,
       verdict: unexpected > 0 ? "failed" : "passed"
@@ -11772,8 +11806,8 @@ var ShardMerger = class {
       testTitle: spec.title,
       suitePath,
       error: {
-        message: error?.message ?? "Test failed",
-        stack: error?.stack
+        message: stripAnsi(error?.message ?? "Test failed"),
+        stack: error?.stack ? stripAnsi(error.stack) : void 0
       },
       screenshotPath: lastResult?.attachments.find(
         (a) => a.name.toLowerCase().includes("screenshot") && a.contentType.startsWith("image/")
@@ -11812,18 +11846,13 @@ var ShardMerger = class {
     };
   }
   buildCharts(stats, projects) {
-    const suiteResults = projects.flatMap(
-      (p) => p.suites.map((s) => ({
-        label: s.title,
-        passed: s.stats.passed,
-        failed: s.stats.failed,
-        skipped: s.stats.skipped
-      }))
-    ).slice(0, TOP_SUITES_FOR_CHART2);
+    const suiteResults = buildSuiteResults(projects, TOP_SUITES_FOR_CHART);
     return {
       passRate: {
         passed: stats.passed,
         failed: stats.failed,
+        timedOut: stats.timedOut,
+        // always 0 in shard JSON (no separate timedOut count)
         skipped: stats.skipped,
         flaky: stats.flaky
       },
@@ -12038,6 +12067,19 @@ var TemplateEngine = class {
       "upperCase",
       (s) => typeof s === "string" ? s.toUpperCase() : s
     );
+    this.handlebars.registerHelper("verdictLabel", (v) => {
+      const map = {
+        passed: "PASSED",
+        failed: "FAILED",
+        timedout: "TIMED OUT",
+        interrupted: "INTERRUPTED"
+      };
+      return map[v] ?? (typeof v === "string" ? v.toUpperCase() : v);
+    });
+    this.handlebars.registerHelper("coverageBand", (pct) => {
+      const n = Number(pct);
+      return n >= 80 ? "high" : n >= 50 ? "mid" : "low";
+    });
     this.handlebars.registerHelper("addOne", (n) => (n ?? 0) + 1);
     this.handlebars.registerHelper(
       "join",
@@ -13055,7 +13097,7 @@ var PdfReporter = class {
     this.dataCollector = new DataCollector();
     this.pdfGenerator = new PdfGenerator();
     this.options = parseOptions(rawOptions);
-    const version = true ? "0.4.0" : "0.x";
+    const version = true ? "0.5.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,