executable-stories-formatters 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -280,6 +280,8 @@ interface MarkdownFormatterOptions {
     permalinkBaseUrl?: string;
     /** URL template for ticket links. Use {ticket} as placeholder. E.g., "https://jira.example.com/browse/{ticket}" */
     ticketUrlTemplate?: string;
+    /** URL template for trace links. Use {traceId} as placeholder. E.g., "https://grafana.example.com/explore?traceId={traceId}" */
+    traceUrlTemplate?: string;
     /** Include source links when permalinkBaseUrl is set. Default: true */
     includeSourceLinks?: boolean;
     /** Custom renderers for doc entries */
@@ -350,6 +352,7 @@ interface ResolvedFormatterOptions {
         includeSummaryTable: boolean;
         permalinkBaseUrl?: string;
         ticketUrlTemplate?: string;
+        traceUrlTemplate?: string;
         includeSourceLinks: boolean;
         customRenderers?: MarkdownRenderers;
     };
@@ -871,6 +874,8 @@ interface MarkdownOptions {
     permalinkBaseUrl?: string;
     /** URL template for ticket links. Use {ticket} as placeholder */
     ticketUrlTemplate?: string;
+    /** URL template for trace links. Use {traceId} as placeholder. E.g. "https://grafana.example.com/explore?traceId={traceId}" */
+    traceUrlTemplate?: string;
     /** Include source links when permalinkBaseUrl is set. Default: true */
     includeSourceLinks?: boolean;
     /** Custom renderers for doc entries */
@@ -1376,6 +1381,27 @@ declare function clearVersionCache(): void;
  */
 declare function detectCI(env?: Record<string, string | undefined>): RawCIInfo | undefined;
 
+/**
+ * OTel trace context detection.
+ *
+ * Detects an active OpenTelemetry span via `@opentelemetry/api` (optional peer).
+ * Uses `createRequire` so the import is lazy and never breaks if OTel isn't installed.
+ */
+interface OtelTraceContext {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * Try to read trace context from the currently-active OTel span.
+ * Returns `undefined` when `@opentelemetry/api` is not installed or no span is active.
+ */
+declare function tryGetActiveOtelContext(): OtelTraceContext | undefined;
+/**
+ * Replace `{traceId}` in a URL template.
+ * Returns `undefined` when no template is provided.
+ */
+declare function resolveTraceUrl(template: string | undefined, traceId: string): string | undefined;
+
 /**
  * @executable-stories/formatters
  *
@@ -1465,4 +1491,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
 
-export { type Attachment, type CIInfo, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, HtmlFormatter, type HtmlOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type Logger, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestRunResult, type TestStatus, type ValidationResult, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, canonicalizeRun, clearVersionCache, createReportGenerator, deriveStepResults, detectCI, findGitDir, formatDuration, generateRunId, generateTestCaseId, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, slugify, validateCanonicalRun };
+export { type Attachment, type CIInfo, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, HtmlFormatter, type HtmlOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type Logger, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestRunResult, type TestStatus, type ValidationResult, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, canonicalizeRun, clearVersionCache, createReportGenerator, deriveStepResults, detectCI, findGitDir, formatDuration, generateRunId, generateTestCaseId, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, resolveTraceUrl, slugify, tryGetActiveOtelContext, validateCanonicalRun };

package/dist/index.d.ts

@@ -280,6 +280,8 @@ interface MarkdownFormatterOptions {
     permalinkBaseUrl?: string;
     /** URL template for ticket links. Use {ticket} as placeholder. E.g., "https://jira.example.com/browse/{ticket}" */
     ticketUrlTemplate?: string;
+    /** URL template for trace links. Use {traceId} as placeholder. E.g., "https://grafana.example.com/explore?traceId={traceId}" */
+    traceUrlTemplate?: string;
     /** Include source links when permalinkBaseUrl is set. Default: true */
     includeSourceLinks?: boolean;
     /** Custom renderers for doc entries */
@@ -350,6 +352,7 @@ interface ResolvedFormatterOptions {
         includeSummaryTable: boolean;
         permalinkBaseUrl?: string;
         ticketUrlTemplate?: string;
+        traceUrlTemplate?: string;
         includeSourceLinks: boolean;
         customRenderers?: MarkdownRenderers;
     };
@@ -871,6 +874,8 @@ interface MarkdownOptions {
     permalinkBaseUrl?: string;
     /** URL template for ticket links. Use {ticket} as placeholder */
     ticketUrlTemplate?: string;
+    /** URL template for trace links. Use {traceId} as placeholder. E.g. "https://grafana.example.com/explore?traceId={traceId}" */
+    traceUrlTemplate?: string;
     /** Include source links when permalinkBaseUrl is set. Default: true */
     includeSourceLinks?: boolean;
     /** Custom renderers for doc entries */
@@ -1376,6 +1381,27 @@ declare function clearVersionCache(): void;
  */
 declare function detectCI(env?: Record<string, string | undefined>): RawCIInfo | undefined;
 
+/**
+ * OTel trace context detection.
+ *
+ * Detects an active OpenTelemetry span via `@opentelemetry/api` (optional peer).
+ * Uses `createRequire` so the import is lazy and never breaks if OTel isn't installed.
+ */
+interface OtelTraceContext {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * Try to read trace context from the currently-active OTel span.
+ * Returns `undefined` when `@opentelemetry/api` is not installed or no span is active.
+ */
+declare function tryGetActiveOtelContext(): OtelTraceContext | undefined;
+/**
+ * Replace `{traceId}` in a URL template.
+ * Returns `undefined` when no template is provided.
+ */
+declare function resolveTraceUrl(template: string | undefined, traceId: string): string | undefined;
+
 /**
  * @executable-stories/formatters
  *
@@ -1465,4 +1491,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
 
-export { type Attachment, type CIInfo, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, HtmlFormatter, type HtmlOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type Logger, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestRunResult, type TestStatus, type ValidationResult, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, canonicalizeRun, clearVersionCache, createReportGenerator, deriveStepResults, detectCI, findGitDir, formatDuration, generateRunId, generateTestCaseId, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, slugify, validateCanonicalRun };
+export { type Attachment, type CIInfo, type CanonicalizeOptions, type ColocatedStyle, type CoverageSummary, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DocEntry, type FormatterOptions, type GenerateArgs, type GenerateDeps, type GenerateResult, HtmlFormatter, type HtmlOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type Logger, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, RawAttachment, RawCIInfo, RawRun, RawStatus, ReportGenerator, type ResolvedFormatterOptions, type StepResult, StoryMeta, StoryStep, type TestCaseAttempt, type TestCaseResult, type TestRunResult, type TestStatus, type ValidationResult, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, canonicalizeRun, clearVersionCache, createReportGenerator, deriveStepResults, detectCI, findGitDir, formatDuration, generateRunId, generateTestCaseId, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, readBranchName, readGitSha, readPackageVersion, resolveAttachment, resolveAttachments, resolveTraceUrl, slugify, tryGetActiveOtelContext, validateCanonicalRun };

package/dist/index.js

@@ -883,6 +883,18 @@ function initCollapse() {
       }
     });
   });
+
+  document.querySelectorAll('.trace-view-header').forEach(header => {
+    header.addEventListener('click', () => {
+      toggleCollapse(header, header.closest('.trace-view'));
+    });
+    header.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        toggleCollapse(header, header.closest('.trace-view'));
+      }
+    });
+  });
 }
 
 function expandAll() {
@@ -1086,6 +1098,7 @@ var CSS_STYLES = `
   --tag-bg: hsl(145 55% 95%);
   --tag-color: hsl(145 63% 30%);
   --tag-border: hsl(145 55% 85%);
+  --step-param-color: hsl(220 70% 50%);
 
   /* Accordion/Collapsible styling */
   --accordion-header-hover: hsl(0 0% 98%);
@@ -1144,6 +1157,7 @@ var CSS_STYLES = `
   --tag-bg: hsl(145 35% 14%);
   --tag-color: hsl(145 63% 60%);
   --tag-border: hsl(145 35% 22%);
+  --step-param-color: hsl(220 70% 70%);
 
   /* Accordion/Collapsible styling */
   --accordion-header-hover: hsl(0 0% 11%);
@@ -1192,6 +1206,7 @@ var CSS_STYLES = `
     --tag-bg: hsl(145 35% 14%);
     --tag-color: hsl(145 63% 60%);
     --tag-border: hsl(145 35% 22%);
+    --step-param-color: hsl(220 70% 70%);
     --accordion-header-hover: hsl(0 0% 11%);
     --accordion-content-bg: hsl(0 0% 7%);
   }
@@ -1737,6 +1752,12 @@ body {
   color: var(--foreground);
 }
 
+.step-param {
+  font-style: italic;
+  font-weight: 500;
+  color: var(--step-param-color);
+}
+
 .step-duration {
   color: var(--muted-foreground);
   font-size: 0.6875rem;
@@ -2413,6 +2434,7 @@ body {
   font-family: inherit;
   background: none;
 }
+
 `;
 
 // src/formatters/html/renderers/status.ts
@@ -2657,10 +2679,11 @@ function renderStep(step, stepResult, index, deps) {
   const isContinuation = CONTINUATION_KEYWORDS.includes(keywordTrimmed);
   const stepClass = isContinuation ? "step continuation" : "step";
   const stepDocs = deps.renderDocs(step.docs, "step-docs");
+  const textHtml = deps.highlightStepParams ? deps.highlightStepParams(step.text) : deps.escapeHtml(step.text);
   return `<div class="${stepClass}">
   <span class="step-status ${statusClass}">${statusIcon}</span>
   <span class="step-keyword">${deps.escapeHtml(step.keyword)}</span>
-  <span class="step-text">${deps.escapeHtml(step.text)}</span>
+  <span class="step-text">${textHtml}</span>
   <span class="step-duration">${duration}</span>
 </div>${stepDocs}`;
 }
@@ -2672,6 +2695,30 @@ function renderSteps(args, deps) {
   return `<div class="steps">${stepsHtml}</div>`;
 }
 
+// src/formatters/html/renderers/step-params.ts
+var STEP_PARAM_PATTERN = /"[^"]*"|(?<![\w.\-])\d+(?:\.\d+)?(?![\w.\-])/g;
+function highlightStepParams(text, deps) {
+  const matches = Array.from(text.matchAll(STEP_PARAM_PATTERN));
+  if (matches.length === 0) {
+    return deps.escapeHtml(text);
+  }
+  let result = "";
+  let lastIndex = 0;
+  for (const match of matches) {
+    const matchStart = match.index;
+    const matchEnd = matchStart + match[0].length;
+    if (matchStart > lastIndex) {
+      result += deps.escapeHtml(text.slice(lastIndex, matchStart));
+    }
+    result += `<span class="step-param">${deps.escapeHtml(match[0])}</span>`;
+    lastIndex = matchEnd;
+  }
+  if (lastIndex < text.length) {
+    result += deps.escapeHtml(text.slice(lastIndex));
+  }
+  return result;
+}
+
 // src/formatters/html/renderers/scenario.ts
 function renderScenario(args, deps) {
   const { tc } = args;
@@ -2679,6 +2726,19 @@ function renderScenario(args, deps) {
   const statusClass = `status-${tc.status}`;
   const duration = tc.durationMs > 0 ? `${(tc.durationMs / 1e3).toFixed(2)}s` : "";
   const tags = tc.tags.map((t) => `<span class="tag">${deps.escapeHtml(t)}</span>`).join("");
+  const otelMeta = tc.story.meta?.otel;
+  let traceBadge = "";
+  if (otelMeta?.traceId) {
+    const shortId = otelMeta.traceId.slice(0, 16);
+    const traceLink = tc.story.docs?.find(
+      (d) => d.kind === "link" && d.label === "View Trace"
+    );
+    if (traceLink) {
+      traceBadge = `<a class="tag trace-tag" href="${deps.escapeHtml(traceLink.url)}" title="${deps.escapeHtml(otelMeta.traceId)}" target="_blank" rel="noopener">${deps.escapeHtml(shortId)}\u2026</a>`;
+    } else {
+      traceBadge = `<span class="tag trace-tag" title="${deps.escapeHtml(otelMeta.traceId)}">${deps.escapeHtml(shortId)}\u2026</span>`;
+    }
+  }
   const storyDocs = deps.renderDocs(tc.story.docs, "story-docs");
   const steps = deps.renderSteps(
     { steps: tc.story.steps, stepResults: tc.stepResults },
@@ -2709,7 +2769,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}</div>
+      <div class="scenario-meta">${tags}${traceBadge}</div>
     </div>
     <span class="scenario-duration">${duration}</span>
   </div>
@@ -2843,7 +2903,8 @@ function createHtmlFormatter(options = {}) {
   const stepsDeps = {
     escapeHtml,
     getStatusIcon,
-    renderDocs
+    renderDocs,
+    highlightStepParams: (text) => highlightStepParams(text, { escapeHtml })
   };
   const scenarioDeps = {
     escapeHtml,
@@ -3145,6 +3206,7 @@ var MarkdownFormatter = class {
       includeSummaryTable: options.includeSummaryTable ?? false,
       permalinkBaseUrl: options.permalinkBaseUrl,
       ticketUrlTemplate: options.ticketUrlTemplate,
+      traceUrlTemplate: options.traceUrlTemplate,
       includeSourceLinks: options.includeSourceLinks ?? true,
       customRenderers: options.customRenderers
     };
@@ -3367,6 +3429,18 @@ var MarkdownFormatter = class {
         meta.push(`Tickets: ${tc.story.tickets.map((t) => `\`${t}\``).join(", ")}`);
       }
     }
+    const otelMeta = tc.story.meta?.otel;
+    if (otelMeta?.traceId) {
+      const traceTemplate = this.options.traceUrlTemplate;
+      if (traceTemplate) {
+        const url = traceTemplate.replace(/\{traceId\}/g, otelMeta.traceId);
+        meta.push(
+          `Trace: [${otelMeta.traceId.slice(0, 16)}\u2026](${url})`
+        );
+      } else {
+        meta.push(`Trace: \`${otelMeta.traceId}\``);
+      }
+    }
     if (meta.length > 0) {
       lines.push(meta.join(" | "));
     }
@@ -5309,6 +5383,31 @@ function detectCI4(env = process.env) {
   return void 0;
 }
 
+// src/utils/otel-detect.ts
+import { createRequire } from "module";
+function getRequire() {
+  const url = import.meta.url ?? (typeof __filename !== "undefined" ? `file://${__filename}` : void 0);
+  if (!url) throw new Error("Cannot determine module URL");
+  return createRequire(url);
+}
+function tryGetActiveOtelContext() {
+  try {
+    const api = getRequire()("@opentelemetry/api");
+    const span = api.trace?.getActiveSpan?.();
+    if (!span) return void 0;
+    const ctx = span.spanContext?.();
+    if (!ctx?.traceId || ctx.traceId === "00000000000000000000000000000000")
+      return void 0;
+    return { traceId: ctx.traceId, spanId: ctx.spanId };
+  } catch {
+    return void 0;
+  }
+}
+function resolveTraceUrl(template, traceId) {
+  if (!template) return void 0;
+  return template.replace(/\{traceId\}/g, traceId);
+}
+
 // src/index.ts
 var FORMAT_EXTENSIONS = {
   markdown: ".md",
@@ -5499,6 +5598,7 @@ var ReportGenerator = class {
         includeSummaryTable: options.markdown?.includeSummaryTable ?? false,
         permalinkBaseUrl: options.markdown?.permalinkBaseUrl,
         ticketUrlTemplate: options.markdown?.ticketUrlTemplate,
+        traceUrlTemplate: options.markdown?.traceUrlTemplate,
         includeSourceLinks: options.markdown?.includeSourceLinks ?? true,
         customRenderers: options.markdown?.customRenderers
       }
@@ -5624,6 +5724,7 @@ var ReportGenerator = class {
           includeSummaryTable: this.options.markdown.includeSummaryTable,
           permalinkBaseUrl: this.options.markdown.permalinkBaseUrl,
           ticketUrlTemplate: this.options.markdown.ticketUrlTemplate,
+          traceUrlTemplate: this.options.markdown.traceUrlTemplate,
           includeSourceLinks: this.options.markdown.includeSourceLinks,
           customRenderers: this.options.markdown.customRenderers
         });
@@ -5685,7 +5786,9 @@ export {
   readPackageVersion,
   resolveAttachment,
   resolveAttachments,
+  resolveTraceUrl,
   slugify,
+  tryGetActiveOtelContext,
   validateCanonicalRun
 };
 //# sourceMappingURL=index.js.map