@specbook/core 0.1.0 → 0.3.0

package/src/reporters/index.ts

@@ -1,5 +1,8 @@
 import { stripAnsi } from '../assert'
+import { diffAssertion } from '../diff'
 import type { RunResult, StepResult } from '../types'
+import { reportTotals } from './envelope'
+import { traceLines } from './trace'
 
 export interface Reporter {
   onEvent?(e: unknown): void
@@ -40,35 +43,74 @@ export function formatPretty(results: RunResult[]): string {
 
 const esc = (s: unknown) =>
   String(s).replace(
-    /[<>&"']/g,
-    (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[c] as string,
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: characters XML 1.0 forbids
+    /[<>&"']|[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g,
+    (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[c] ?? '',
   )
 
-export function toJUnit(results: RunResult[]): string {
+export interface JUnitOptions {
+  /** ISO time the run began; shown on each suite */
+  timestamp?: string
+  hostname?: string
+  /** shown as `<properties>` on each suite (env, git sha, seed…) */
+  properties?: Record<string, string | undefined>
+  /** service → origin, for the trace in `<system-out>` */
+  origins?: Record<string, string>
+}
+
+const leafSteps = (steps: StepResult[]): StepResult[] =>
+  steps.flatMap((s) => (s.children?.length ? leafSteps(s.children) : [s]))
+
+/**
+ * JUnit XML: one suite per flow or request, one case per step (named `flow › step`, class = the project file), failures
+ * with the expected and received values, errors with their message, skipped steps, a flow that passed on a retry as a
+ * `<flakyFailure>`, and the redacted request/response trace in `<system-out>`.
+ */
+export function toJUnit(results: RunResult[], o: JUnitOptions = {}): string {
   const suites = results.map((r) => {
-    const flat: StepResult[] = []
-    const walk = (s: StepResult) => (s.children?.length ? s.children.forEach(walk) : flat.push(s))
-    r.steps.forEach(walk)
-    const failures = flat.filter((s) => s.status === 'fail' || s.status === 'error').length
+    const flat = leafSteps(r.steps)
+    const failures = flat.filter((s) => s.status === 'fail').length
+    const errors = flat.filter((s) => s.status === 'error').length
+    const skipped = flat.filter((s) => s.status === 'skipped').length
+    const props = Object.entries({ env: r.env, seed: r.seed, ...o.properties })
+      .filter(([, v]) => v !== undefined && v !== '')
+      .map(([k, v]) => `      <property name="${esc(k)}" value="${esc(v)}"/>`)
+      .join('\n')
     const cases = flat
       .map((s) => {
         const time = (s.durationMs / 1000).toFixed(3)
         const failed = s.assertions.filter((a) => !a.pass)
         let inner = ''
         if (s.status === 'skipped') inner = '<skipped/>'
-        else if (s.status === 'error') inner = `<error message="${esc(s.error ?? 'error')}"/>`
+        else if (s.status === 'error')
+          inner = `<error message="${esc(s.error ?? 'error')}" type="Error">${esc(s.error ?? 'error')}</error>`
         else if (failed.length) {
           inner = failed
-            .map(
-              (a) =>
-                `<failure message="${esc(a.label)}">${esc(`expected: ${JSON.stringify(a.expected)}\nactual: ${JSON.stringify(a.actual)}`)}</failure>`,
-            )
+            .map((a) => {
+              const lines = diffAssertion(a)
+                .filter((l) => l.kind !== 'skip')
+                .map(
+                  (l) =>
+                    `${l.kind === 'expected' ? '- ' : l.kind === 'received' ? '+ ' : '  '}${l.text}`,
+                )
+              const at = a.location
+                ? `\nat ${a.location.file}:${a.location.line}:${a.location.column ?? 1}`
+                : ''
+              return `<failure message="${esc(a.label)}" type="${esc(a.operator)}">${esc(`${lines.join('\n')}${at}`)}</failure>`
+            })
             .join('')
         }
-        return `    <testcase classname="${esc(r.id)}" name="${esc(s.name)}" time="${time}">${inner}</testcase>`
+        if (r.flaky && s.status === 'pass' && (r.attempts ?? 1) > 1)
+          inner += `<flakyFailure message="passed on attempt ${r.attempts}"/>`
+        const trace =
+          s.status === 'fail' || s.status === 'error'
+            ? `<system-out>${esc(traceLines(s, { origins: o.origins }).join('\n'))}</system-out>`
+            : ''
+        return `    <testcase classname="${esc(r.file ?? r.id)}" name="${esc(`${r.title} › ${s.name}`)}" time="${time}">${inner}${trace}</testcase>`
       })
       .join('\n')
-    return `  <testsuite name="${esc(r.title)}" tests="${flat.length}" failures="${failures}" time="${(r.durationMs / 1000).toFixed(3)}">\n${cases}\n  </testsuite>`
+    const stamp = r.startedAt || o.timestamp
+    return `  <testsuite name="${esc(r.title)}" tests="${flat.length}" failures="${failures}" errors="${errors}" skipped="${skipped}" time="${(r.durationMs / 1000).toFixed(3)}"${stamp ? ` timestamp="${esc(stamp)}"` : ''}${o.hostname ? ` hostname="${esc(o.hostname)}"` : ''}>\n    <properties>\n${props}\n    </properties>\n${cases}\n  </testsuite>`
   })
   return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n${suites.join('\n')}\n</testsuites>\n`
 }
@@ -82,24 +124,96 @@ export function exitCode(results: RunResult[]): 0 | 1 | 2 {
   return 0
 }
 
-/** GitHub Actions workflow commands: one annotation per failing assertion/step. */
-export function formatGithub(results: RunResult[]): string {
-  const esc = (v: string) => v.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A')
+/** For `specbook test`: 0 when every flow passed (a flaky one counts), 1 when any failed or errored. */
+export function testExitCode(results: RunResult[]): 0 | 1 {
+  return results.some((r) => r.status !== 'pass') ? 1 : 0
+}
+
+export interface GithubOptions {
+  /** folder the paths are made relative to (the project or repository root) */
+  cwd?: string
+}
+
+/** A workflow command property: `%`, newlines, `:` and `,` are escaped. */
+const prop = (v: string) =>
+  v
+    .replace(/%/g, '%25')
+    .replace(/\r/g, '%0D')
+    .replace(/\n/g, '%0A')
+    .replace(/:/g, '%3A')
+    .replace(/,/g, '%2C')
+const data = (v: string) => v.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A')
+
+/** GitHub Actions workflow commands: one annotation per failing assertion/step, a warning for a flaky flow. */
+export function formatGithub(results: RunResult[], o: GithubOptions = {}): string {
+  const rel = (f: string) => (o.cwd && f.startsWith(`${o.cwd}/`) ? f.slice(o.cwd.length + 1) : f)
   const lines: string[] = []
   const visit = (r: RunResult, s: StepResult) => {
     for (const c of s.children ?? []) visit(r, c)
-    if (s.status === 'error' || s.status === 'skipped') {
-      if (s.status === 'error')
-        lines.push(`::error title=${esc(`${r.title}: ${s.name}`)}::${esc(s.error ?? 'error')}`)
-      return
-    }
+    if (s.children?.length) return
+    const title = prop(`${r.title}: ${s.name}`)
+    const file = r.file ? `file=${prop(r.file)},` : ''
+    if (s.status === 'error')
+      lines.push(`::error ${file}title=${title}::${data(s.error ?? 'error')}`)
+    if (s.status === 'skipped' || s.status === 'error') return
     for (const a of s.assertions.filter((x) => !x.pass)) {
-      const loc = a.location ? `file=${esc(a.location.file)},line=${a.location.line},` : ''
-      lines.push(`::error ${loc}title=${esc(`${r.title}: ${s.name}`)}::${esc(a.label)}`)
+      const loc = a.location ? `file=${prop(rel(a.location.file))},line=${a.location.line},` : file
+      lines.push(`::error ${loc}title=${title}::${data(a.label)}`)
     }
   }
-  for (const r of results) for (const s of r.steps) visit(r, s)
+  for (const r of results) {
+    for (const s of r.steps) visit(r, s)
+    if (r.flaky)
+      lines.push(
+        `::warning ${r.file ? `file=${prop(r.file)},` : ''}title=${prop(`${r.title}: flaky`)}::${data(`passed on attempt ${r.attempts}`)}`,
+      )
+  }
   const ok = results.filter((r) => r.status === 'pass').length
   lines.push(`${ok}/${results.length} runs passed`)
   return lines.join('\n')
 }
+
+/** Markdown for `$GITHUB_STEP_SUMMARY`: totals, a table of flows, and what failed. */
+export function githubSummary(
+  results: RunResult[],
+  meta: { env: string; runUrl?: string } = { env: '' },
+): string {
+  const t = reportTotals(results)
+  const mark = (r: RunResult) =>
+    r.status === 'pass' ? (r.flaky ? '⚠️ flaky' : '✅') : r.status === 'error' ? '❗ error' : '❌'
+  const cell = (s: string) => s.replace(/\|/g, '\\|')
+  const lines = [
+    `### specbook test${meta.env ? ` · ${meta.env}` : ''}`,
+    '',
+    `**${t.flows.passed}** passed · **${t.flows.failed + t.flows.errored}** failed · **${t.flows.flaky}** flaky · ${results.length} total`,
+    '',
+    '| | Flow | Steps | Assertions | Time |',
+    '| --- | --- | --- | --- | --- |',
+    ...results.map(
+      (r) =>
+        `| ${mark(r)} | ${cell(r.title)} | ${r.totals.passed}/${r.totals.steps} | ${r.totals.assertions.passed}/${r.totals.assertions.passed + r.totals.assertions.failed} | ${(r.durationMs / 1000).toFixed(2)}s |`,
+    ),
+  ]
+  const bad = results.flatMap((r) =>
+    leafSteps(r.steps)
+      .filter((s) => s.status === 'fail' || s.status === 'error')
+      .map((s) => ({ r, s })),
+  )
+  if (bad.length) {
+    lines.push('', '#### Failures', '')
+    for (const { r, s } of bad) {
+      lines.push(`- **${cell(r.title)} › ${cell(s.name)}**`)
+      if (s.error) lines.push(`  - ${s.error}`)
+      for (const a of s.assertions.filter((x) => !x.pass)) lines.push(`  - ${a.label}`)
+    }
+  }
+  if (meta.runUrl) lines.push('', `[Run](${meta.runUrl})`)
+  return `${lines.join('\n')}\n`
+}
+
+export * from './ci'
+export * from './color'
+export * from './envelope'
+export * from './list'
+export * from './redact'
+export * from './trace'

package/src/reporters/list.ts

@@ -0,0 +1,254 @@
+// The default report: steps as they finish, then what failed (with the assertion, a source frame and the trace) and a summary.
+
+import { type DiffLine, diffAssertion } from '../diff'
+import type { RunEvent } from '../runner/run'
+import type { AssertionResult, RunResult, StepResult } from '../types'
+import { type Colors, createColors } from './color'
+import { reportTotals } from './envelope'
+import { type TraceOptions, traceLines } from './trace'
+
+export interface ListOptions {
+  colors?: Colors
+  /** only failures and the summary */
+  quiet?: boolean
+  /** show the request and response of a failed step (default), of every step, or not at all */
+  trace?: 'on-failure' | 'always' | 'off'
+  /** service → origin, to show full addresses in a trace */
+  origins?: Record<string, string>
+  /** paths are shown relative to this folder */
+  cwd?: string
+  /** the text of a project file, for the source frame of a failed assertion */
+  readSource?: (file: string) => string | undefined
+  /** the command that runs just this flow again */
+  rerun?: (r: RunResult) => string | undefined
+  /** how long the whole run took, for the summary */
+  durationMs?: number
+}
+
+const MARKS = { pass: '✓', fail: '✗', error: '!', skipped: '–' } as const
+
+export const formatDuration = (ms: number): string =>
+  ms < 1000
+    ? `${Math.round(ms)}ms`
+    : ms < 60_000
+      ? `${(ms / 1000).toFixed(2)}s`
+      : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`
+
+const leaves = (steps: StepResult[]): StepResult[] =>
+  steps.flatMap((s) => (s.children?.length ? leaves(s.children) : [s]))
+
+function paint(status: StepResult['status'], c: Colors, text: string): string {
+  return status === 'pass'
+    ? c.green(text)
+    : status === 'skipped'
+      ? c.dim(text)
+      : status === 'error'
+        ? c.yellow(text)
+        : c.red(text)
+}
+
+interface StepFacts {
+  status: StepResult['status']
+  flow: string
+  step: string
+  method?: string
+  url?: string
+  code?: number
+  ms?: number
+}
+
+/** `✓ Checkout › Create order  POST /orders  201  85ms` */
+export function stepLine(f: StepFacts, c: Colors, indent = '  '): string {
+  const detail = [
+    f.method && f.url ? `${f.method} ${f.url}` : '',
+    f.code ? String(f.code) : '',
+    f.ms !== undefined ? formatDuration(f.ms) : '',
+  ]
+    .filter(Boolean)
+    .join('  ')
+  // a request that is its own flow is named once
+  const name = f.flow === f.step ? f.step : `${f.flow} › ${f.step}`
+  return `${indent}${paint(f.status, c, MARKS[f.status])} ${name}${detail ? `  ${c.dim(detail)}` : ''}`
+}
+
+function diffText(lines: DiffLine[], c: Colors, indent: string): string[] {
+  return lines.map((l) =>
+    l.kind === 'expected'
+      ? `${indent}${c.green(`- ${l.text}`)}`
+      : l.kind === 'received'
+        ? `${indent}${c.red(`+ ${l.text}`)}`
+        : l.kind === 'skip'
+          ? `${indent}${c.dim(`  ${l.text}`)}`
+          : `${indent}${c.dim(`  ${l.text}`)}`,
+  )
+}
+
+/** The lines around `line` with a caret under `column`, from a file's text. */
+export function codeFrame(
+  source: string,
+  line: number,
+  column = 1,
+  c: Colors = createColors(false),
+  around = 2,
+): string[] {
+  const lines = source.split('\n')
+  const from = Math.max(1, line - around)
+  const to = Math.min(lines.length, line + around)
+  const width = String(to).length
+  const out: string[] = []
+  for (let n = from; n <= to; n++) {
+    const text = lines[n - 1] ?? ''
+    const mark = n === line ? c.red('>') : ' '
+    out.push(`${mark} ${c.dim(String(n).padStart(width))} ${c.dim('|')} ${text}`)
+    if (n === line)
+      out.push(
+        `  ${' '.repeat(width)} ${c.dim('|')} ${' '.repeat(Math.max(0, column - 1))}${c.red('^')}`,
+      )
+  }
+  return out
+}
+
+const rel = (file: string, cwd?: string) =>
+  cwd && file.startsWith(`${cwd}/`) ? file.slice(cwd.length + 1) : file
+
+function assertionBlock(a: AssertionResult, o: ListOptions, c: Colors): string[] {
+  const out = [`    ${c.red('✗')} ${a.label}`]
+  const diff = diffAssertion(a)
+  if (diff.length) {
+    out.push(`      ${c.green('- Expected')}  ${c.red('+ Received')}`)
+    out.push(...diffText(diff, c, '      '))
+  }
+  if (a.location) {
+    out.push(
+      `      ${c.dim(`at ${rel(a.location.file, o.cwd)}:${a.location.line}:${a.location.column ?? 1}`)}`,
+    )
+    const text = o.readSource?.(a.location.file)
+    if (text !== undefined)
+      for (const l of codeFrame(text, a.location.line, a.location.column, c))
+        out.push(`        ${l}`)
+  }
+  return out
+}
+
+/** One block per failed or errored step: the assertions that failed, why a step errored, and its trace. */
+export function formatFailures(results: RunResult[], o: ListOptions = {}): string {
+  const c = o.colors ?? createColors(false)
+  const out: string[] = []
+  for (const r of results) {
+    for (const s of leaves(r.steps)) {
+      if (s.status !== 'fail' && s.status !== 'error') continue
+      const where = r.file ? `${r.file} › ` : ''
+      out.push(
+        '',
+        `${c.bold(c.red(' FAIL '))} ${where}${r.title === s.name ? r.title : `${r.title} › ${s.name}`}  ${c.dim(`[${r.env}] ${formatDuration(s.durationMs)}`)}`,
+      )
+      if (s.status === 'error') out.push(`    ${c.yellow('!')} ${s.error ?? 'error'}`)
+      for (const a of s.assertions) if (!a.pass) out.push(...assertionBlock(a, o, c))
+      if ((o.trace ?? 'on-failure') !== 'off')
+        for (const l of traceLines(s, { origins: o.origins })) out.push(`    ${c.dim(l)}`)
+      const rerun = o.rerun?.(r)
+      if (rerun) out.push(`    ${c.dim(`Re-run: ${rerun}`)}`)
+    }
+  }
+  return out.join('\n')
+}
+
+/** `Flows 8 passed | 1 failed | 1 flaky`, steps, assertions, time and the slowest steps. */
+export function formatSummary(results: RunResult[], o: ListOptions = {}): string {
+  const c = o.colors ?? createColors(false)
+  const t = reportTotals(results)
+  const part = (n: number, word: string, paintFn: (s: string) => string) =>
+    n ? paintFn(`${n} ${word}`) : ''
+  const join = (...parts: string[]) => parts.filter(Boolean).join(c.dim(' | ')) || c.dim('none')
+  const lines = [
+    '',
+    `${c.bold(' Flows      ')} ${join(
+      part(t.flows.failed, 'failed', c.red),
+      part(t.flows.errored, 'errored', c.yellow),
+      part(t.flows.flaky, 'flaky', c.yellow),
+      part(t.flows.passed, 'passed', c.green),
+    )} ${c.dim(`(${results.length})`)}`,
+    `${c.bold(' Steps      ')} ${join(
+      part(t.steps.failed, 'failed', c.red),
+      part(t.steps.skipped, 'skipped', c.dim),
+      part(t.steps.passed, 'passed', c.green),
+    )}`,
+    `${c.bold(' Assertions ')} ${join(
+      part(t.assertions.failed, 'failed', c.red),
+      part(t.assertions.passed, 'passed', c.green),
+    )}`,
+  ]
+  const total = o.durationMs ?? results.reduce((n, r) => n + r.durationMs, 0)
+  lines.push(`${c.bold(' Duration   ')} ${formatDuration(total)}`)
+  const slow = results
+    .flatMap((r) =>
+      leaves(r.steps)
+        .filter((s) => s.status !== 'skipped')
+        // a request is a flow of one step: its name is said once
+        .map((s) => ({
+          name: r.title === s.name ? r.title : `${r.title} › ${s.name}`,
+          ms: s.durationMs,
+        })),
+    )
+    .sort((a, b) => b.ms - a.ms)
+    .slice(0, 5)
+  if (slow.length > 1) {
+    const times = slow.map((s) => formatDuration(s.ms))
+    const width = Math.max(...times.map((t) => t.length))
+    lines.push(c.bold(' Slowest'))
+    for (const [i, s] of slow.entries())
+      lines.push(`   ${c.dim(`${(times[i] as string).padStart(width)}  ${s.name}`)}`)
+  }
+  return lines.join('\n')
+}
+
+function stepFacts(r: RunResult, s: StepResult): StepFacts {
+  return {
+    status: s.status,
+    flow: r.title,
+    step: s.name,
+    method: s.request?.method,
+    url: s.request?.url,
+    code: s.response?.status,
+    ms: s.status === 'skipped' ? undefined : s.durationMs,
+  }
+}
+
+/** The whole report at once, from finished results (what the streaming reporter prints, in one string). */
+export function formatList(results: RunResult[], o: ListOptions = {}): string {
+  const c = o.colors ?? createColors(false)
+  const lines: string[] = []
+  if (!o.quiet)
+    for (const r of results)
+      for (const s of leaves(r.steps)) lines.push(stepLine(stepFacts(r, s), c))
+  const failures = formatFailures(results, o)
+  return [lines.join('\n'), failures, formatSummary(results, o)].filter((x) => x !== '').join('\n')
+}
+
+/** Prints each step as it finishes, from the run's events; at the end prints the failures and the summary. */
+export function createListReporter(o: ListOptions & { write(text: string): void }) {
+  const c = o.colors ?? createColors(false)
+  let flow = ''
+  const facts = new Map<string, Partial<StepFacts>>()
+  return {
+    onEvent(e: RunEvent) {
+      if (e.type === 'run:start') flow = e.title ?? e.id
+      else if (e.type === 'request')
+        facts.set(e.name, { ...facts.get(e.name), method: e.request.method, url: e.request.url })
+      else if (e.type === 'response')
+        facts.set(e.name, { ...facts.get(e.name), code: e.status, ms: e.durationMs })
+      else if (e.type === 'step:end') {
+        const f = facts.get(e.name)
+        facts.delete(e.name)
+        if (e.status === 'pass' && o.quiet) return
+        o.write(`${stepLine({ ...f, status: e.status, flow, step: e.name }, c)}\n`)
+      }
+    },
+    onEnd(results: RunResult[]) {
+      const rest = [formatFailures(results, o), formatSummary(results, o)].filter((x) => x !== '')
+      o.write(`${rest.join('\n')}\n`)
+    },
+  }
+}
+
+export type { TraceOptions }

package/src/reporters/redact.ts

@@ -0,0 +1,113 @@
+// What a report may show of a run. Resolved secret values are already masked by the runner; this removes what is secret
+// without being one of ours: credentials in headers, and tokens and passwords that an API returns or a request captures.
+
+import type { RunEvent } from '../runner/run'
+import type { AssertionResult, RunResult, StepResult } from '../types'
+
+export const REDACTED = '***'
+
+/** Headers whose values are never shown, whatever they hold. */
+const DENIED_HEADERS = new Set([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'x-auth-token',
+  'x-csrf-token',
+  'x-xsrf-token',
+])
+
+export const isDeniedHeader = (name: string) => DENIED_HEADERS.has(name.toLowerCase())
+
+/** `accessToken`, `access_token`, `client-secret` → words joined by `_`, lowercase. */
+const normalize = (key: string) =>
+  key
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[-.\s]+/g, '_')
+    .toLowerCase()
+
+const SENSITIVE =
+  /(^|_)(tokens?|secrets?|passwords?|passwd|authorization|credentials?|cookies?|api_?keys?|private_?keys?|access_?keys?|secret_?keys?)$/
+
+/** Whether a property named like this holds something that should not be printed (`access_token`, `password`, `apiKey`). */
+export const isSensitiveKey = (key: string) => SENSITIVE.test(normalize(key))
+
+function redactValue(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(redactValue)
+  if (v !== null && typeof v === 'object') {
+    return Object.fromEntries(
+      Object.entries(v).map(([k, x]) => [
+        k,
+        isSensitiveKey(k) && (typeof x === 'string' || typeof x === 'number')
+          ? REDACTED
+          : redactValue(x),
+      ]),
+    )
+  }
+  return v
+}
+
+export function redactHeaders(headers: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(headers).map(([k, v]) => [k, isDeniedHeader(k) ? REDACTED : v]),
+  )
+}
+
+function redactAssertion(a: AssertionResult): AssertionResult {
+  const hasValues = 'actual' in a || 'expected' in a
+  return {
+    ...a,
+    actual: redactValue(a.actual),
+    expected: redactValue(a.expected),
+    // a recorded diff is text made from the values; with the values present it is rebuilt from the clean ones
+    diff: hasValues ? undefined : a.diff,
+  }
+}
+
+function redactStep(s: StepResult): StepResult {
+  return {
+    ...s,
+    assertions: s.assertions.map(redactAssertion),
+    request: s.request
+      ? {
+          ...s.request,
+          headers: redactHeaders(s.request.headers),
+          body: redactValue(s.request.body),
+        }
+      : undefined,
+    response: s.response
+      ? {
+          ...s.response,
+          headers: redactHeaders(s.response.headers),
+          body: redactValue(s.response.body),
+        }
+      : undefined,
+    captured: redactValue(s.captured) as Record<string, unknown>,
+    children: s.children?.map(redactStep),
+  }
+}
+
+/** A copy of the results that is safe to print, attach to a build or send to a monitoring service. */
+export function redactResults(results: RunResult[]): RunResult[] {
+  return results.map((r) => ({ ...r, steps: r.steps.map(redactStep) }))
+}
+
+/** The same for one event of a run, before it is written to a log or a stream. */
+export function redactEvent(e: RunEvent): RunEvent {
+  if (e.type === 'request')
+    return {
+      ...e,
+      request: {
+        ...e.request,
+        headers: redactHeaders(e.request.headers),
+        body: redactValue(e.request.body),
+      },
+    }
+  if (e.type === 'capture')
+    return { ...e, captured: redactValue(e.captured) as Record<string, unknown> }
+  if (e.type === 'assert:pass' || e.type === 'assert:fail')
+    return { ...e, assertion: redactAssertion(e.assertion) }
+  if (e.type === 'done') return { ...e, result: redactResults([e.result])[0] as RunResult }
+  return e
+}

package/src/reporters/trace.ts

@@ -0,0 +1,70 @@
+// The request and response of a step as text, for a failure: what was sent, what came back, redacted and shortened.
+
+import { statusText } from '../diff'
+import type { StepResult } from '../types'
+import { isDeniedHeader, REDACTED } from './redact'
+
+/** Response headers worth showing: the rest is noise in a failure. */
+const SHOWN_RESPONSE_HEADERS = [
+  'content-type',
+  'x-request-id',
+  'x-correlation-id',
+  'x-amzn-trace-id',
+  'traceparent',
+  'retry-after',
+  'location',
+]
+
+export interface TraceOptions {
+  /** service → origin (`https://api.example.com`), to show the full address */
+  origins?: Record<string, string>
+  /** characters of a body shown before it is cut (default 2048) */
+  maxBody?: number
+}
+
+function body(v: unknown, max: number): string[] {
+  if (v === undefined || v === null || v === '') return []
+  let text: string
+  try {
+    text = typeof v === 'string' ? v : (JSON.stringify(v, null, 2) ?? String(v))
+  } catch {
+    text = String(v)
+  }
+  const cut = text.length > max
+  const lines = (cut ? text.slice(0, max) : text).split('\n')
+  if (cut) lines.push(`… ${text.length - max} more characters`)
+  return lines
+}
+
+const query = (q: Record<string, string | string[]>) => {
+  const parts = Object.entries(q).flatMap(([k, v]) =>
+    (Array.isArray(v) ? v : [v]).map((x) => `${k}=${x}`),
+  )
+  return parts.length ? `?${parts.join('&')}` : ''
+}
+
+/** The trace of one step as lines (without indentation): `Request`, its headers and body, `Response`, and the same. */
+export function traceLines(step: StepResult, o: TraceOptions = {}): string[] {
+  const max = o.maxBody ?? 2048
+  const out: string[] = []
+  const r = step.request
+  if (r) {
+    const origin = o.origins?.[r.service] ?? ''
+    out.push(`Request   ${r.method} ${origin}${r.url}${query(r.query)}`)
+    for (const [k, v] of Object.entries(r.headers))
+      out.push(`  ${k}: ${isDeniedHeader(k) ? REDACTED : v}`)
+    for (const l of body(r.body, max)) out.push(`  ${l}`)
+  }
+  const res = step.response
+  if (res) {
+    out.push(
+      `Response  ${[res.status, statusText(res.status)].filter(Boolean).join(' ')}  ${res.durationMs}ms`,
+    )
+    for (const name of SHOWN_RESPONSE_HEADERS) {
+      const v = res.headers[name]
+      if (v !== undefined) out.push(`  ${name}: ${isDeniedHeader(name) ? REDACTED : v}`)
+    }
+    for (const l of body(res.body, max)) out.push(`  ${l}`)
+  }
+  return out
+}