@specbook/core 0.2.0 → 0.3.0

package/src/reporters/ci.ts

@@ -0,0 +1,53 @@
+// Where a run happens, from the environment a CI system sets, for the report's header and its links.
+
+export interface CiInfo {
+  provider: string
+  runUrl?: string
+  sha?: string
+  branch?: string
+}
+
+export function detectCi(env: Record<string, string | undefined>): CiInfo | undefined {
+  if (env.GITHUB_ACTIONS === 'true') {
+    const server = env.GITHUB_SERVER_URL ?? 'https://github.com'
+    return {
+      provider: 'github-actions',
+      runUrl:
+        env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID
+          ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`
+          : undefined,
+      sha: env.GITHUB_SHA,
+      branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+    }
+  }
+  if (env.GITLAB_CI === 'true')
+    return {
+      provider: 'gitlab-ci',
+      runUrl: env.CI_PIPELINE_URL,
+      sha: env.CI_COMMIT_SHA,
+      branch: env.CI_COMMIT_REF_NAME,
+    }
+  if (env.CIRCLECI === 'true')
+    return {
+      provider: 'circleci',
+      runUrl: env.CIRCLE_BUILD_URL,
+      sha: env.CIRCLE_SHA1,
+      branch: env.CIRCLE_BRANCH,
+    }
+  if (env.BUILDKITE === 'true')
+    return {
+      provider: 'buildkite',
+      runUrl: env.BUILDKITE_BUILD_URL,
+      sha: env.BUILDKITE_COMMIT,
+      branch: env.BUILDKITE_BRANCH,
+    }
+  if (env.JENKINS_URL)
+    return {
+      provider: 'jenkins',
+      runUrl: env.BUILD_URL,
+      sha: env.GIT_COMMIT,
+      branch: env.GIT_BRANCH,
+    }
+  if (env.CI) return { provider: 'ci' }
+  return undefined
+}

package/src/reporters/color.ts

@@ -0,0 +1,34 @@
+// Terminal colors, only when they will be seen: a TTY or a CI log that renders them, not NO_COLOR, or FORCE_COLOR.
+
+export interface Colors {
+  red(s: string): string
+  green(s: string): string
+  yellow(s: string): string
+  cyan(s: string): string
+  dim(s: string): string
+  bold(s: string): string
+}
+
+/** CI systems whose logs render color though the stream is not a terminal. */
+const COLOR_CI = ['GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'BUILDKITE']
+
+/** Whether to color output: FORCE_COLOR wins, then NO_COLOR, then an interactive terminal or a CI log that shows color. */
+export function colorEnabled(env: Record<string, string | undefined>, isTTY: boolean): boolean {
+  if (env.FORCE_COLOR && env.FORCE_COLOR !== '0') return true
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false
+  if (COLOR_CI.some((k) => env[k] && env[k] !== 'false')) return true
+  return isTTY && env.TERM !== 'dumb'
+}
+
+export function createColors(enabled: boolean): Colors {
+  const wrap = (open: number, close: number) => (s: string) =>
+    enabled ? `\u001b[${open}m${s}\u001b[${close}m` : s
+  return {
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    cyan: wrap(36, 39),
+    dim: wrap(2, 22),
+    bold: wrap(1, 22),
+  }
+}

package/src/reporters/envelope.ts

@@ -0,0 +1,63 @@
+// The JSON report: the results with what a monitoring system needs to know about the run around them.
+
+import type { RunResult } from '../types'
+import type { CiInfo } from './ci'
+
+export interface ReportMeta {
+  env: string
+  /** version of the specbook that ran it */
+  specbook?: string
+  node?: string
+  os?: string
+  git?: { sha?: string; branch?: string }
+  ci?: CiInfo
+  /** `bundle.json` details when run from a bundle */
+  bundle?: { sha?: string; createdAt?: string }
+  /** service → origin of the address its calls went to */
+  services?: Record<string, string>
+  startedAt: string
+  finishedAt: string
+}
+
+export interface ReportTotals {
+  flows: { passed: number; failed: number; errored: number; flaky: number }
+  steps: { passed: number; failed: number; skipped: number }
+  assertions: { passed: number; failed: number }
+}
+
+export interface RunReport extends ReportMeta {
+  schemaVersion: 2
+  durationMs: number
+  totals: ReportTotals
+  results: RunResult[]
+}
+
+export function reportTotals(results: RunResult[]): ReportTotals {
+  const t: ReportTotals = {
+    flows: { passed: 0, failed: 0, errored: 0, flaky: 0 },
+    steps: { passed: 0, failed: 0, skipped: 0 },
+    assertions: { passed: 0, failed: 0 },
+  }
+  for (const r of results) {
+    if (r.status === 'pass') t.flows.passed++
+    else if (r.status === 'error') t.flows.errored++
+    else t.flows.failed++
+    if (r.flaky) t.flows.flaky++
+    t.steps.passed += r.totals.passed
+    t.steps.failed += r.totals.failed
+    t.steps.skipped += r.totals.skipped
+    t.assertions.passed += r.totals.assertions.passed
+    t.assertions.failed += r.totals.assertions.failed
+  }
+  return t
+}
+
+export function buildReport(results: RunResult[], meta: ReportMeta): RunReport {
+  return {
+    schemaVersion: 2,
+    ...meta,
+    durationMs: Math.max(0, Date.parse(meta.finishedAt) - Date.parse(meta.startedAt)),
+    totals: reportTotals(results),
+    results,
+  }
+}

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 }