executable-stories-formatters 0.4.0 → 0.5.0

package/dist/cli.js

@@ -2764,6 +2764,21 @@ body {
   }
 }
 
+/* ============================================================================
+   History metric badges
+   ============================================================================ */
+.badge { display: inline-block; padding: 2px 6px; border-radius: 4px; font-size: 0.75em; font-weight: 600; margin-left: 4px; vertical-align: middle; }
+.badge-grade { color: #fff; }
+.badge-grade-A { background: var(--success); }
+.badge-grade-B { background: #2196F3; }
+.badge-grade-C { background: #FF9800; }
+.badge-grade-D { background: #f44336; }
+.badge-grade-F { background: #9E0000; }
+.badge-flaky { background: #FF9800; color: #fff; }
+.badge-perf { font-size: 0.7em; }
+.badge-perf-improving { color: var(--success); }
+.badge-perf-regressing { color: var(--error); }
+
 `;
 
 // src/formatters/html/renderers/status.ts
@@ -2797,7 +2812,22 @@ function renderMetaInfo(args, deps) {
     items.push(`<dt>Git:</dt><dd>${deps.escapeHtml(shortSha)}</dd>`);
   }
   if (args.ciName) {
-    items.push(`<dt>CI:</dt><dd>${deps.escapeHtml(args.ciName)}</dd>`);
+    if (args.ciUrl && args.ciBuildNumber) {
+      items.push(
+        `<dt>CI:</dt><dd>${deps.escapeHtml(args.ciName)} <a href="${deps.escapeHtml(args.ciUrl)}">#${deps.escapeHtml(args.ciBuildNumber)}</a></dd>`
+      );
+    } else {
+      items.push(`<dt>CI:</dt><dd>${deps.escapeHtml(args.ciName)}</dd>`);
+    }
+  }
+  if (args.ciBranch) {
+    items.push(`<dt>Branch:</dt><dd>${deps.escapeHtml(args.ciBranch)}</dd>`);
+  }
+  if (args.ciCommitSha) {
+    const shortSha = args.ciCommitSha.length > 7 ? args.ciCommitSha.slice(0, 7) : args.ciCommitSha;
+    items.push(
+      `<dt>Commit:</dt><dd title="${deps.escapeHtml(args.ciCommitSha)}">${deps.escapeHtml(shortSha)}</dd>`
+    );
   }
   return `<dl class="meta-info">${items.join("")}</dl>`;
 }
@@ -3048,6 +3078,9 @@ function highlightStepParams(text, deps) {
   return result;
 }
 
+// src/history/sample-policy.ts
+var MIN_METRIC_SAMPLES = 5;
+
 // src/formatters/html/renderers/scenario.ts
 function renderScenario(args, deps) {
   const { tc } = args;
@@ -3068,6 +3101,19 @@ function renderScenario(args, deps) {
       traceBadge = `<span class="tag trace-tag" title="${deps.escapeHtml(otelMeta.traceId)}">${deps.escapeHtml(shortId)}\u2026</span>`;
     }
   }
+  let metricBadges = "";
+  const { metrics } = args;
+  if (metrics && metrics.sampleSize >= MIN_METRIC_SAMPLES) {
+    const grade = metrics.stabilityGrade;
+    metricBadges += `<span class="badge badge-grade badge-grade-${grade}" title="Pass rate: ${(metrics.passRate * 100).toFixed(0)}% (${metrics.sampleSize} runs)">${grade}</span>`;
+    if (metrics.flakinessLevel !== "stable") {
+      metricBadges += `<span class="badge badge-flaky">${metrics.flakinessLevel}</span>`;
+    }
+    if (metrics.performanceTrend !== "stable") {
+      const arrow = metrics.performanceTrend === "improving" ? "\u2191" : "\u2193";
+      metricBadges += `<span class="badge badge-perf badge-perf-${metrics.performanceTrend}">${arrow} ${metrics.performanceTrend}</span>`;
+    }
+  }
   const storyDocs = deps.renderDocs(tc.story.docs, "story-docs");
   const steps = deps.renderSteps(
     { steps: tc.story.steps, stepResults: tc.stepResults },
@@ -3102,7 +3148,7 @@ function renderScenario(args, deps) {
         <span class="status-icon ${statusClass}">${statusIcon}</span>
         <span class="scenario-name">${deps.escapeHtml(tc.story.scenario)}</span>
       </div>
-      <div class="scenario-meta">${tags}${traceBadge}</div>
+      <div class="scenario-meta">${tags}${traceBadge}${metricBadges}</div>
     </div>
     <span class="scenario-duration">${duration}</span>
   </div>
@@ -3314,7 +3360,12 @@ function renderFeature(args, deps) {
   const featureName = suitePaths.length > 0 && suitePaths[0].length > 0 ? suitePaths[0][0] : file.split("/").pop()?.replace(/\.[^.]+$/, "") ?? file;
   const collapsedClass = deps.startCollapsed ? " collapsed" : "";
   const ariaExpanded = !deps.startCollapsed;
-  const scenarios = testCases.map((tc) => deps.renderScenario({ tc }, deps.scenarioDeps)).join("\n");
+  const scenarios = testCases.map(
+    (tc) => deps.renderScenario(
+      { tc, metrics: args.metricsMap?.get(tc.id) },
+      deps.scenarioDeps
+    )
+  ).join("\n");
   return `
 <div class="feature${collapsedClass}">
   <div class="feature-header" role="button" tabindex="0" aria-expanded="${ariaExpanded}">
@@ -3359,7 +3410,11 @@ function buildBody(args, deps) {
         durationMs: run.durationMs,
         packageVersion: run.packageVersion,
         gitSha: run.gitSha,
-        ciName: run.ci?.name
+        ciName: run.ci?.name,
+        ciBranch: run.ci?.branch,
+        ciUrl: run.ci?.url,
+        ciCommitSha: run.ci?.commitSha,
+        ciBuildNumber: run.ci?.buildNumber
       },
       deps.metaDeps
     )
@@ -3388,7 +3443,10 @@ function buildBody(args, deps) {
   const byFile = groupBy(run.testCases, (tc) => tc.sourceFile);
   for (const [file, testCases] of byFile) {
     parts.push(
-      deps.renderFeature({ file, testCases }, deps.featureDeps)
+      deps.renderFeature(
+        { file, testCases, metricsMap: args.metricsMap },
+        deps.featureDeps
+      )
     );
   }
   return parts.join("\n");
@@ -5326,6 +5384,574 @@ function pickleStepArgumentToDocs(ps) {
   return docs;
 }
 
+// src/notifiers/ansi-strip.ts
+function stripAnsi(text) {
+  return text.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "");
+}
+
+// src/notifiers/slack.ts
+function truncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + "...";
+}
+function formatDuration2(ms) {
+  const seconds = ms / 1e3;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds.toFixed(0)}s`;
+}
+function buildSlackPayload(summary, maxFailedTests) {
+  const allPassed = summary.failed === 0;
+  const emoji = allPassed ? ":white_check_mark:" : ":x:";
+  const statusText = allPassed ? "Passed" : "Failed";
+  const blocks = [];
+  blocks.push({
+    type: "header",
+    text: {
+      type: "plain_text",
+      text: `${emoji} Test Results: ${summary.passed} passed, ${summary.failed} failed`,
+      emoji: true
+    }
+  });
+  blocks.push({
+    type: "section",
+    fields: [
+      { type: "mrkdwn", text: `*Total:* ${summary.total}` },
+      { type: "mrkdwn", text: `*Passed:* ${summary.passed}` },
+      { type: "mrkdwn", text: `*Failed:* ${summary.failed}` },
+      { type: "mrkdwn", text: `*Skipped:* ${summary.skipped}` },
+      { type: "mrkdwn", text: `*Duration:* ${formatDuration2(summary.durationMs)}` },
+      { type: "mrkdwn", text: `*Status:* ${statusText}` }
+    ]
+  });
+  if (summary.failedTests.length > 0) {
+    const displayedTests = summary.failedTests.slice(0, maxFailedTests);
+    const lines = displayedTests.map((t) => {
+      const name = t.name;
+      if (t.error) {
+        const cleanError = truncate(stripAnsi(t.error), 500);
+        return `*${name}*
+\`\`\`${cleanError}\`\`\``;
+      }
+      return `*${name}*`;
+    });
+    let text = lines.join("\n\n");
+    if (summary.failedTests.length > maxFailedTests) {
+      text += `
+
+_...and ${summary.failedTests.length - maxFailedTests} more_`;
+    }
+    blocks.push({
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text
+      }
+    });
+  }
+  if (summary.ci) {
+    const elements = [];
+    if (summary.ci.displayName) {
+      elements.push({ type: "mrkdwn", text: `*CI:* ${summary.ci.displayName}` });
+    }
+    if (summary.ci.branch) {
+      elements.push({ type: "mrkdwn", text: `*Branch:* ${summary.ci.branch}` });
+    }
+    if (summary.ci.commitSha) {
+      elements.push({ type: "mrkdwn", text: `*Commit:* ${summary.ci.commitSha.slice(0, 7)}` });
+    }
+    if (summary.ci.buildNumber) {
+      elements.push({ type: "mrkdwn", text: `*Build:* #${summary.ci.buildNumber}` });
+    }
+    if (elements.length > 0) {
+      blocks.push({
+        type: "context",
+        elements
+      });
+    }
+  }
+  if (summary.reportUrl) {
+    blocks.push({
+      type: "actions",
+      elements: [
+        {
+          type: "button",
+          text: {
+            type: "plain_text",
+            text: "View Report",
+            emoji: true
+          },
+          url: summary.reportUrl,
+          action_id: "view_report"
+        }
+      ]
+    });
+  }
+  return { blocks };
+}
+async function sendSlackNotification(args, deps) {
+  const { summary, webhookUrl, maxFailedTests = 5 } = args;
+  const { fetch, logger } = deps;
+  const payload = buildSlackPayload(summary, maxFailedTests);
+  try {
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const requestId = response.headers.get("x-request-id") ?? void 0;
+      let bodyText = "";
+      try {
+        bodyText = await response.text();
+      } catch {
+      }
+      const truncatedBody = truncate(bodyText, 200);
+      const idPart = requestId ? ` x-request-id=${requestId}` : "";
+      const errorMsg = `Slack notifier failed: HTTP ${response.status}${idPart} ${truncatedBody}`;
+      logger.warn(errorMsg);
+      return { ok: false, error: errorMsg };
+    }
+    return { ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const errorMsg = `Slack notifier failed: ${msg}`;
+    logger.warn(errorMsg);
+    return { ok: false, error: errorMsg };
+  }
+}
+
+// src/notifiers/teams.ts
+function truncate2(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + "...";
+}
+function formatDuration3(ms) {
+  const seconds = ms / 1e3;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds.toFixed(0)}s`;
+}
+function buildTeamsPayload(summary, maxFailedTests) {
+  const allPassed = summary.failed === 0;
+  const statusEmoji = allPassed ? "\u2705" : "\u274C";
+  const statusColor = allPassed ? "good" : "attention";
+  const bodyItems = [];
+  bodyItems.push({
+    type: "TextBlock",
+    size: "Large",
+    weight: "Bolder",
+    text: `${statusEmoji} Test Results`,
+    color: statusColor
+  });
+  bodyItems.push({
+    type: "FactSet",
+    facts: [
+      { title: "Total", value: String(summary.total) },
+      { title: "Passed", value: String(summary.passed) },
+      { title: "Failed", value: String(summary.failed) },
+      { title: "Skipped", value: String(summary.skipped) },
+      { title: "Duration", value: formatDuration3(summary.durationMs) }
+    ]
+  });
+  if (summary.failedTests.length > 0) {
+    const displayedTests = summary.failedTests.slice(0, maxFailedTests);
+    const failedItems = [
+      {
+        type: "TextBlock",
+        text: "Failed Tests",
+        weight: "Bolder",
+        spacing: "Medium"
+      }
+    ];
+    for (const t of displayedTests) {
+      failedItems.push({
+        type: "TextBlock",
+        text: `**${t.name}**`,
+        wrap: true
+      });
+      if (t.error) {
+        const cleanError = truncate2(stripAnsi(t.error), 500);
+        failedItems.push({
+          type: "TextBlock",
+          text: cleanError,
+          wrap: true,
+          fontType: "Monospace",
+          size: "Small",
+          color: "Attention"
+        });
+      }
+    }
+    if (summary.failedTests.length > maxFailedTests) {
+      failedItems.push({
+        type: "TextBlock",
+        text: `...and ${summary.failedTests.length - maxFailedTests} more`,
+        isSubtle: true,
+        spacing: "Small"
+      });
+    }
+    bodyItems.push({
+      type: "Container",
+      items: failedItems
+    });
+  }
+  if (summary.ci) {
+    const ciFacts = [];
+    if (summary.ci.displayName) {
+      ciFacts.push({ title: "CI", value: summary.ci.displayName });
+    }
+    if (summary.ci.branch) {
+      ciFacts.push({ title: "Branch", value: summary.ci.branch });
+    }
+    if (summary.ci.commitSha) {
+      ciFacts.push({ title: "Commit", value: summary.ci.commitSha.slice(0, 7) });
+    }
+    if (summary.ci.buildNumber) {
+      ciFacts.push({ title: "Build", value: `#${summary.ci.buildNumber}` });
+    }
+    if (ciFacts.length > 0) {
+      bodyItems.push({
+        type: "FactSet",
+        facts: ciFacts,
+        separator: true
+      });
+    }
+  }
+  const card = {
+    type: "AdaptiveCard",
+    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+    version: "1.4",
+    body: bodyItems
+  };
+  if (summary.reportUrl) {
+    card.actions = [
+      {
+        type: "Action.OpenUrl",
+        title: "View Report",
+        url: summary.reportUrl
+      }
+    ];
+  }
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        content: card
+      }
+    ]
+  };
+}
+async function sendTeamsNotification(args, deps) {
+  const { summary, webhookUrl, maxFailedTests = 5 } = args;
+  const { fetch, logger } = deps;
+  const payload = buildTeamsPayload(summary, maxFailedTests);
+  try {
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const requestId = response.headers.get("x-request-id") ?? void 0;
+      let bodyText = "";
+      try {
+        bodyText = await response.text();
+      } catch {
+      }
+      const truncatedBody = truncate2(bodyText, 200);
+      const idPart = requestId ? ` x-request-id=${requestId}` : "";
+      const errorMsg = `Teams notifier failed: HTTP ${response.status}${idPart} ${truncatedBody}`;
+      logger.warn(errorMsg);
+      return { ok: false, error: errorMsg };
+    }
+    return { ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const errorMsg = `Teams notifier failed: ${msg}`;
+    logger.warn(errorMsg);
+    return { ok: false, error: errorMsg };
+  }
+}
+
+// src/notifiers/hmac.ts
+import { createHmac } from "crypto";
+function signBody(args) {
+  let input;
+  let timestamp;
+  if (args.includeTimestamp) {
+    timestamp = args.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+    input = `${timestamp}.${args.body}`;
+  } else {
+    input = args.body;
+  }
+  const hex = createHmac("sha256", args.secret).update(input, "utf8").digest("hex");
+  return {
+    signature: `sha256=${hex}`,
+    timestamp
+  };
+}
+
+// src/notifiers/webhook.ts
+async function sendWebhookNotification(args, deps) {
+  const { summary, options } = args;
+  const { fetch, logger } = deps;
+  const payload = {
+    schemaVersion: 1,
+    event: "test_run_finished",
+    summary
+  };
+  const body = JSON.stringify(payload);
+  const headers = { "Content-Type": "application/json" };
+  if (options.headers) {
+    for (const [key, value] of Object.entries(options.headers)) {
+      headers[key] = value;
+    }
+  }
+  if (options.signer) {
+    const { secret, header, includeTimestamp, timestampHeader } = options.signer;
+    const result = signBody({ body, secret, includeTimestamp });
+    headers[header] = result.signature;
+    if (result.timestamp) {
+      headers[timestampHeader ?? "X-Timestamp"] = result.timestamp;
+    }
+  }
+  try {
+    const response = await fetch(options.url, {
+      method: options.method ?? "POST",
+      headers,
+      body
+    });
+    if (!response.ok) {
+      const requestId = response.headers.get("x-request-id") ?? void 0;
+      let snippet = "";
+      try {
+        snippet = (await response.text()).slice(0, 200);
+      } catch {
+      }
+      const idPart = requestId ? ` x-request-id=${requestId}` : "";
+      const errorMsg = `webhook: HTTP ${response.status}${idPart} ${snippet}`;
+      logger.warn(errorMsg);
+      return { ok: false, error: errorMsg };
+    }
+    return { ok: true };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const errorMsg = `webhook: ${msg}`;
+    logger.warn(errorMsg);
+    return { ok: false, error: errorMsg };
+  }
+}
+
+// src/notifiers/index.ts
+function buildSummary(run, reportUrl, toCIInfo2) {
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  const failedTests = [];
+  for (const tc of run.testCases) {
+    switch (tc.status) {
+      case "passed":
+        passed++;
+        break;
+      case "failed":
+        failed++;
+        failedTests.push({
+          testId: tc.id,
+          name: tc.story.scenario,
+          error: tc.errorMessage
+        });
+        break;
+      case "skipped":
+      case "pending":
+        skipped++;
+        break;
+    }
+  }
+  let ci;
+  if (run.ci) {
+    ci = toCIInfo2(run.ci);
+  }
+  return {
+    total: run.testCases.length,
+    passed,
+    failed,
+    skipped,
+    durationMs: run.durationMs,
+    failedTests,
+    ci,
+    reportUrl
+  };
+}
+function shouldNotify(condition, failedCount) {
+  if (condition === "never") return false;
+  if (condition === "on-failure" && failedCount === 0) return false;
+  return true;
+}
+async function sendNotifications(args, deps) {
+  const { run, notification } = args;
+  const { logger, toCIInfo: toCIInfo2 } = deps;
+  const env = deps.env ?? process.env;
+  if (!deps.fetch) {
+    logger.warn("notifications: skipped (fetch unavailable)");
+    return;
+  }
+  const fetch = deps.fetch;
+  const slackWebhookUrl = notification?.slackWebhookUrl ?? env.SLACK_WEBHOOK_URL;
+  const teamsWebhookUrl = notification?.teamsWebhookUrl ?? env.TEAMS_WEBHOOK_URL;
+  const globalCondition = notification?.condition ?? "on-failure";
+  const reportUrl = notification?.reportUrl;
+  const maxFailedTests = notification?.maxFailedTests ?? 5;
+  const webhooks = notification?.webhooks ?? [];
+  if (!slackWebhookUrl && !teamsWebhookUrl && webhooks.length === 0) {
+    return;
+  }
+  const summary = buildSummary(run, reportUrl, toCIInfo2);
+  const promises = [];
+  if (slackWebhookUrl && shouldNotify(globalCondition, summary.failed)) {
+    promises.push(
+      sendSlackNotification(
+        { summary, webhookUrl: slackWebhookUrl, maxFailedTests },
+        { fetch, logger }
+      ).then(() => void 0)
+    );
+  }
+  if (teamsWebhookUrl && shouldNotify(globalCondition, summary.failed)) {
+    promises.push(
+      sendTeamsNotification(
+        { summary, webhookUrl: teamsWebhookUrl, maxFailedTests },
+        { fetch, logger }
+      ).then(() => void 0)
+    );
+  }
+  for (const webhook of webhooks) {
+    const effectiveCondition = webhook.condition ?? globalCondition;
+    if (!shouldNotify(effectiveCondition, summary.failed)) continue;
+    promises.push(
+      sendWebhookNotification(
+        { summary, options: webhook, maxFailedTests },
+        { fetch, logger }
+      ).then(() => void 0)
+    );
+  }
+  await Promise.allSettled(promises);
+}
+
+// src/types/ci.ts
+var DISPLAY_NAMES = {
+  github: "GitHub Actions",
+  gitlab: "GitLab CI",
+  circleci: "CircleCI",
+  jenkins: "Jenkins",
+  azure: "Azure DevOps",
+  buildkite: "Buildkite",
+  travis: "Travis CI",
+  unknown: "CI"
+};
+var NAME_TO_PROVIDER = {
+  github: "github",
+  gitlab: "gitlab",
+  circleci: "circleci",
+  jenkins: "jenkins",
+  azure: "azure",
+  buildkite: "buildkite",
+  travis: "travis",
+  ci: "unknown"
+};
+function toCIInfo(raw) {
+  if (!raw) return void 0;
+  const provider = raw.provider ?? NAME_TO_PROVIDER[raw.name] ?? "unknown";
+  return {
+    provider,
+    displayName: DISPLAY_NAMES[provider],
+    url: raw.url,
+    buildNumber: raw.buildNumber,
+    branch: raw.branch,
+    commitSha: raw.commitSha,
+    prNumber: raw.prNumber
+  };
+}
+
+// src/history/history-store.ts
+function emptyStore() {
+  return { version: 1, maxRuns: 10, tests: {}, lastUpdated: 0 };
+}
+function loadHistory(args, deps) {
+  const content = deps.readFile(args.filePath);
+  if (content === void 0) {
+    return emptyStore();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    deps.logger.warn(`Failed to parse history file: ${args.filePath}`);
+    return emptyStore();
+  }
+  if (typeof parsed !== "object" || parsed === null || parsed.version !== 1) {
+    deps.logger.warn(
+      `Unknown history version in ${args.filePath}, expected version 1`
+    );
+    return emptyStore();
+  }
+  const obj = parsed;
+  if (typeof obj.tests !== "object" || obj.tests === null || Array.isArray(obj.tests)) {
+    deps.logger.warn(
+      `Malformed history store in ${args.filePath}: tests must be a non-null object`
+    );
+    return emptyStore();
+  }
+  return parsed;
+}
+function saveHistory(args, deps) {
+  deps.writeFile(args.filePath, JSON.stringify(args.store, null, 2));
+}
+function updateHistory(args) {
+  const { store, run, maxRuns } = args;
+  const newTests = { ...store.tests };
+  for (const tc of run.testCases) {
+    const entry = {
+      runId: run.runId,
+      timestamp: run.startedAtMs,
+      status: tc.status,
+      durationMs: tc.durationMs,
+      ci: run.ci ? {
+        provider: void 0,
+        branch: run.ci.branch,
+        commitSha: run.ci.commitSha
+      } : void 0
+    };
+    const existing = newTests[tc.id];
+    if (existing) {
+      const updatedEntries = [...existing.entries, entry];
+      const trimmed = updatedEntries.length > maxRuns ? updatedEntries.slice(updatedEntries.length - maxRuns) : updatedEntries;
+      newTests[tc.id] = {
+        ...existing,
+        testName: tc.story.scenario,
+        sourceFile: tc.sourceFile,
+        sourceLine: tc.sourceLine,
+        entries: trimmed
+      };
+    } else {
+      newTests[tc.id] = {
+        testId: tc.id,
+        testName: tc.story.scenario,
+        sourceFile: tc.sourceFile,
+        sourceLine: tc.sourceLine,
+        entries: [entry]
+      };
+    }
+  }
+  return {
+    version: 1,
+    maxRuns,
+    tests: newTests,
+    lastUpdated: Date.now()
+  };
+}
+
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   markdown: ".md",
@@ -5697,6 +6323,26 @@ OPTIONS
   --emit-canonical <path>       Write canonical JSON to given path
   --help                        Show this help message
 
+NOTIFICATIONS
+  --slack-webhook <url>         Slack incoming webhook URL (fallback: SLACK_WEBHOOK_URL env var)
+  --teams-webhook <url>         Teams incoming webhook URL (fallback: TEAMS_WEBHOOK_URL env var)
+  --notify <condition>          When to send: always, on-failure, never (default: on-failure)
+  --report-url <url>            URL to link in notification messages
+  --max-failed-tests <n>        Max failed tests to show in notifications (default: 5)
+
+GENERIC WEBHOOK
+  --webhook-url <url>            Generic webhook URL (repeatable for multiple endpoints)
+  --webhook-header <Key: Value>  Custom request header (repeatable)
+  --webhook-method <POST|PUT>    HTTP method (default: POST)
+  --webhook-hmac-secret <s>      HMAC-SHA256 signing secret
+  --webhook-hmac-header <name>   Signature header name (default: X-Signature)
+  --webhook-hmac-timestamp       Include timestamp in HMAC signing
+  Note: all --webhook-url entries share the same method/headers/signing options.
+
+HISTORY
+  --history-file <path>         Path to JSON history file (enables tracking)
+  --max-history-runs <n>        Max runs to keep in history per test (default: 10)
+
 EXIT CODES
   0  Success
   1  Schema validation failure
@@ -5733,6 +6379,19 @@ function parseCliArgs(argv) {
       stdin: { type: "boolean", default: false },
       "json-summary": { type: "boolean", default: false },
       "emit-canonical": { type: "string" },
+      "slack-webhook": { type: "string" },
+      "teams-webhook": { type: "string" },
+      notify: { type: "string", default: "on-failure" },
+      "report-url": { type: "string" },
+      "max-failed-tests": { type: "string" },
+      "history-file": { type: "string" },
+      "max-history-runs": { type: "string" },
+      "webhook-url": { type: "string", multiple: true },
+      "webhook-header": { type: "string", multiple: true },
+      "webhook-method": { type: "string" },
+      "webhook-hmac-secret": { type: "string" },
+      "webhook-hmac-header": { type: "string" },
+      "webhook-hmac-timestamp": { type: "boolean", default: false },
       help: { type: "boolean", default: false }
     },
     allowPositionals: true,
@@ -5764,6 +6423,53 @@ function parseCliArgs(argv) {
   }
   const noSynthesize = values["no-synthesize-stories"];
   const parseGlobs = (v) => v ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
+  const notifyValue = values.notify;
+  const validNotifyConditions = /* @__PURE__ */ new Set(["always", "on-failure", "never"]);
+  if (!validNotifyConditions.has(notifyValue)) {
+    console.error(`Error: --notify must be "always", "on-failure", or "never", got "${notifyValue}".`);
+    process.exit(EXIT_USAGE);
+  }
+  const maxFailedTestsStr = values["max-failed-tests"];
+  const maxFailedTests = maxFailedTestsStr ? parseInt(maxFailedTestsStr, 10) : 5;
+  if (maxFailedTestsStr && (isNaN(maxFailedTests) || maxFailedTests < 0)) {
+    console.error(`Error: --max-failed-tests must be a non-negative integer, got "${maxFailedTestsStr}".`);
+    process.exit(EXIT_USAGE);
+  }
+  const slackWebhook = values["slack-webhook"];
+  const teamsWebhook = values["teams-webhook"];
+  const webhookUrls = values["webhook-url"] ?? [];
+  const webhookHeaders = {};
+  const rawHeaders = values["webhook-header"] ?? [];
+  for (const h of rawHeaders) {
+    const colonIdx = h.indexOf(":");
+    if (colonIdx <= 0) {
+      console.error(`Warning: ignoring invalid --webhook-header "${h}" (expected "Key: Value")`);
+      continue;
+    }
+    const key = h.slice(0, colonIdx).trim();
+    const value = h.slice(colonIdx + 1).trim();
+    if (!key) {
+      console.error(`Warning: ignoring --webhook-header with empty key`);
+      continue;
+    }
+    webhookHeaders[key] = value;
+  }
+  const webhookMethodRaw = values["webhook-method"];
+  let webhookMethod = "POST";
+  if (webhookMethodRaw) {
+    const upper = webhookMethodRaw.toUpperCase();
+    if (upper !== "POST" && upper !== "PUT") {
+      console.error(`Error: --webhook-method must be "POST" or "PUT", got "${webhookMethodRaw}".`);
+      process.exit(EXIT_USAGE);
+    }
+    webhookMethod = upper;
+  }
+  const maxHistoryRunsStr = values["max-history-runs"];
+  const maxHistoryRuns = maxHistoryRunsStr ? parseInt(maxHistoryRunsStr, 10) : 10;
+  if (maxHistoryRunsStr && (isNaN(maxHistoryRuns) || maxHistoryRuns < 1)) {
+    console.error(`Error: --max-history-runs must be a positive integer, got "${maxHistoryRunsStr}".`);
+    process.exit(EXIT_USAGE);
+  }
   return {
     subcommand,
     inputFile,
@@ -5780,7 +6486,20 @@ function parseCliArgs(argv) {
     htmlNoMermaid: values["html-no-mermaid"],
     htmlNoMarkdown: values["html-no-markdown"],
     jsonSummary: values["json-summary"],
-    emitCanonical: values["emit-canonical"]
+    emitCanonical: values["emit-canonical"],
+    slackWebhook,
+    teamsWebhook,
+    notify: notifyValue,
+    reportUrl: values["report-url"],
+    maxFailedTests,
+    historyFile: values["history-file"],
+    maxHistoryRuns,
+    webhookUrls,
+    webhookHeaders,
+    webhookMethod,
+    webhookHmacSecret: values["webhook-hmac-secret"],
+    webhookHmacHeader: values["webhook-hmac-header"] ?? "X-Signature",
+    webhookHmacTimestamp: values["webhook-hmac-timestamp"]
   };
 }
 async function readInput(args) {
@@ -5864,6 +6583,8 @@ async function main() {
     }
     try {
       const result = await generateReports(run, args);
+      await dispatchNotifications(run, args);
+      runHistoryPipeline(run, args);
       printResult(result, args, startMs);
       process.exit(EXIT_SUCCESS);
     } catch (err) {
@@ -5920,6 +6641,8 @@ ${msg}`);
     }
     try {
       const result = await generateReports(run, args);
+      await dispatchNotifications(run, args);
+      runHistoryPipeline(run, args);
       printResult(result, args, startMs);
       process.exit(EXIT_SUCCESS);
     } catch (err) {
@@ -5975,6 +6698,8 @@ ${msg}`);
   }
   try {
     const result = await generateReports(canonical, args, droppedMissingStory);
+    await dispatchNotifications(canonical, args);
+    runHistoryPipeline(canonical, args);
     printResult(result, args, startMs, droppedMissingStory);
     process.exit(EXIT_SUCCESS);
   } catch (err) {
@@ -5983,6 +6708,85 @@ ${msg}`);
     process.exit(EXIT_GENERATION);
   }
 }
+async function dispatchNotifications(run, args) {
+  const webhooks = args.webhookUrls.map((url) => {
+    const opts = { url };
+    if (Object.keys(args.webhookHeaders).length > 0) {
+      opts.headers = { ...args.webhookHeaders };
+    }
+    if (args.webhookMethod !== "POST") {
+      opts.method = args.webhookMethod;
+    }
+    if (args.webhookHmacSecret) {
+      const signer = {
+        type: "hmac-sha256",
+        secret: args.webhookHmacSecret,
+        header: args.webhookHmacHeader
+      };
+      if (args.webhookHmacTimestamp) {
+        signer.includeTimestamp = true;
+      }
+      opts.signer = signer;
+    }
+    return opts;
+  });
+  await sendNotifications(
+    {
+      run,
+      notification: {
+        slackWebhookUrl: args.slackWebhook,
+        teamsWebhookUrl: args.teamsWebhook,
+        condition: args.notify,
+        reportUrl: args.reportUrl,
+        maxFailedTests: args.maxFailedTests,
+        webhooks: webhooks.length > 0 ? webhooks : void 0
+      }
+    },
+    {
+      fetch: globalThis.fetch,
+      logger: console,
+      toCIInfo
+    }
+  );
+}
+function runHistoryPipeline(run, args) {
+  if (!args.historyFile) return;
+  const historyPath = path3.resolve(args.historyFile);
+  const store = loadHistory(
+    { filePath: historyPath },
+    {
+      readFile: (p) => {
+        try {
+          return fs3.readFileSync(p, "utf8");
+        } catch {
+          return void 0;
+        }
+      },
+      logger: console
+    }
+  );
+  const updated = updateHistory({
+    store,
+    run,
+    maxRuns: args.maxHistoryRuns
+  });
+  const dir = path3.dirname(historyPath);
+  fs3.mkdirSync(dir, { recursive: true });
+  saveHistory(
+    { filePath: historyPath, store: updated },
+    { writeFile: (p, content) => fs3.writeFileSync(p, content, "utf8") }
+  );
+  let metricsCount = 0;
+  for (const testId of Object.keys(updated.tests)) {
+    const history = updated.tests[testId];
+    if (history.entries.length >= 3) {
+      metricsCount++;
+    }
+  }
+  if (metricsCount > 0) {
+    console.error(`History updated: ${historyPath} (${Object.keys(updated.tests).length} tests tracked)`);
+  }
+}
 async function generateReports(run, args, _droppedMissingStory = 0) {
   const generator = new ReportGenerator({
     include: args.include,