@specbook/core 0.2.0 → 0.3.0

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
+}

package/src/request.ts

@@ -2,6 +2,7 @@ import { deepMerge } from './template'
 import type {
   AnyOp,
   Init,
+  MockHook,
   Operation,
   OpMeta,
   OpTypes,
@@ -15,6 +16,7 @@ function make<T extends OpTypes, I extends Init, C>(
   input: RequestInput<T, I, C>,
   dataPatches: readonly unknown[],
   varOverrides: Readonly<Record<string, unknown>> = {},
+  mockHook?: MockHook<T, I>,
 ): RequestDef<T, I, C> {
   return {
     kind: 'request',
@@ -22,6 +24,7 @@ function make<T extends OpTypes, I extends Init, C>(
     input,
     dataPatches,
     varOverrides,
+    mockHook,
     with<C2>(o: RequestOverrides<T, I, C2>) {
       const next: RequestInput<T, any, any> = { ...input }
       if (o.path) next.path = deepMerge(input.path as any, o.path) as any
@@ -29,16 +32,31 @@ function make<T extends OpTypes, I extends Init, C>(
       if (o.headers) next.headers = { ...(input.headers ?? {}), ...o.headers }
       if (o.capture) next.capture = { ...(input.capture ?? {}), ...o.capture } as any
       if (o.assert) next.assert = o.assert
-      if (o.mock) next.mock = { ...(input.mock ?? {}), ...o.mock } as any
       if (o.auth !== undefined) next.auth = o.auth
       if (o.assertMode) next.assertMode = o.assertMode
+      if (o.tags) next.tags = [...new Set([...(input.tags ?? []), ...o.tags])]
       const patches = o.data !== undefined ? [...dataPatches, o.data] : dataPatches
       const overrides = o.vars ? { ...varOverrides, ...o.vars } : varOverrides
-      return make(op, next, patches, overrides) as RequestDef<T, I, C & C2>
+      return make(op, next, patches, overrides, mockHook) as RequestDef<T, I, C & C2>
     },
   }
 }
 
+/**
+ * How the `mock` environment answers this request, when the generated example (filled from the request) is not enough.
+ * Rarely needed; `req` and `res` are typed from the operation. Returns the request, so it is the file's one export:
+ *
+ *     export default withMock(GetOrder.request({ ... }), (req, res) => {
+ *       if (res.status === 200) res.data.status = 'placed'
+ *     })
+ */
+export function withMock<T extends OpTypes, I extends Init, C>(
+  def: RequestDef<T, I, C>,
+  hook: MockHook<T, I>,
+): RequestDef<T, I, C> {
+  return make(def.op, def.input, def.dataPatches, def.varOverrides, hook)
+}
+
 /** Generated code calls this once per operation. */
 export function defineOperation<T extends OpTypes = AnyOp>(meta: OpMeta): Operation<T> {
   return {

package/src/runner/index.ts

@@ -1,3 +1,4 @@
 export * from './encode'
 export * from './run'
+export * from './suite'
 export * from './transport'

package/src/runner/run.ts

@@ -23,7 +23,12 @@ import type {
   VarUse,
 } from '../types'
 import { describeFiles, isBlob } from './encode'
-import type { PreparedRequest, RawResponse, Transport } from './transport'
+import {
+  DEFAULT_TIMEOUT_MS,
+  type PreparedRequest,
+  type RawResponse,
+  type Transport,
+} from './transport'
 
 // ---------------- public options ----------------
 
@@ -41,12 +46,22 @@ export interface AuthProfile {
   token?: (res: ApiResponse<number, any>) => Session
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
   retryOn401?: boolean
-  /** an interactive sign-in the UI can offer (authorization code with PKCE); the runner ignores it */
+  /**
+   * an interactive sign-in the UI can offer (authorization code with PKCE); the runner ignores it.
+   * `authorizationUrl`, `tokenUrl`, `openIdConnectUrl` and `clientId` may use environment variables
+   * (`'{{issuer}}/token'`).
+   */
   oauth?: OAuthSettings
 }
 
 export type RunEvent =
-  | { type: 'run:start'; id: string }
+  | {
+      type: 'run:start'
+      id: string
+      title?: string
+      kind?: 'request' | 'sequence'
+      tags?: string[]
+    }
   | { type: 'step:start'; name: string }
   | { type: 'auth:login'; profile: string }
   | { type: 'request'; name: string; request: RenderedRequest }
@@ -60,21 +75,31 @@ export type RunEvent =
 
 export interface RunOptions {
   env: string
-  /** config.vars merged with environments[env].vars. */
+  /** config.vars, then environments[env].vars, then the environment's file. */
   vars?: Record<string, unknown>
   /** Highest-precedence overrides (UI vars panel, CLI --var). */
   overrides?: Record<string, unknown>
-  /** Sequence param overrides. */
-  params?: Record<string, unknown>
+  /** Flow input values: the ones a person would set (UI controls, CLI --input). */
+  inputs?: Record<string, unknown>
   transport: Transport
   /** Resolved secret values, keyed by secret name. Not needed in the mock env. */
   secrets?: Record<string, string>
+  /**
+   * Refuse to send a request that may change data (anything but GET, HEAD and OPTIONS, a GraphQL mutation, or a request
+   * not marked `safe`). Auth logins are exempt. For runs against real environments that must not write.
+   */
+  readOnly?: boolean
+  /**
+   * A request with no `assert` of its own passes only on a 2xx response (recorded as the assertion `status is 2xx`);
+   * one with an `assert` is judged by that alone. Off, a request with no `assert` passes whatever the status.
+   */
+  implicitStatusCheck?: boolean
   /** Leave `{{secrets.*}}` placeholders in the wire request (a trusted server substitutes them). */
   deferSecrets?: boolean
   auth?: Record<string, AuthProfile>
   /** service -> default auth profile name. */
   serviceAuth?: Record<string, string>
-  /** Called at `input()` steps; omit for headless (params override > default > first option). */
+  /** Called at `input()` steps; omit for headless (inputs given > default > first option). */
   onInput?: (req: {
     name: string
     controls: ReturnType<typeof describeControls>
@@ -91,6 +116,13 @@ export interface RunOptions {
   example?: ExampleLoader
   /** Reads files named by upload fields (path relative to the example's `dir`). */
   readFile?: FileReader
+  /**
+   * How long each request waits for an answer, in milliseconds, when the request does not say (`timeoutMs` on the request
+   * wins). 0 waits for as long as it takes. Default: 30 seconds.
+   */
+  timeoutMs?: number
+  /** The `mock` environment answers with this status (the UI's "Respond with"). */
+  mockStatus?: number
 }
 
 // ---------------- internals ----------------
@@ -222,8 +254,22 @@ function substitute<T>(value: T, rt: Runtime, profile?: string): T {
   return walk(value) as T
 }
 
+/** Events are masked as they are emitted: a listener (a stream, a log) must never see a secret value. */
 function emit(rt: Runtime, e: RunEvent) {
-  rt.o.onEvent?.(e)
+  rt.o.onEvent?.(rt.mask.size ? maskDeep(e, rt.mask) : e)
+}
+
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/** True when the request cannot change data: a read method, a GraphQL query, or one marked `safe`. */
+function isReadOnly(def: RequestDef<any, any, any>, prepared: PreparedRequest): boolean {
+  if (def.input.safe) return true
+  if (READ_METHODS.has(prepared.method)) return true
+  if (prepared.encoding === 'graphql') {
+    const body = prepared.body as { query?: unknown } | undefined
+    return typeof body?.query === 'string' && !/(^|[\s}])mutation\b/.test(body.query)
+  }
+  return false
 }
 
 function profileFor(rt: Runtime, def: RequestDef<any, any, any>): string | undefined {
@@ -289,13 +335,13 @@ async function ensureSession(
 
 /** What earlier steps and the sequence hand to a request. */
 interface Flow {
-  params: Record<string, unknown>
+  inputs: Record<string, unknown>
   captured: Record<string, unknown>
   /** capture name -> the step that produced it */
   from: Record<string, string>
 }
 
-const NO_FLOW: Flow = { params: {}, captured: {}, from: {} }
+const NO_FLOW: Flow = { inputs: {}, captured: {}, from: {} }
 
 interface ExecOut {
   result: StepResult
@@ -328,7 +374,7 @@ async function execute(
     const layers: [VarUse['source'], Record<string, unknown>][] = [
       ['config', rt.o.vars ?? {}],
       ['init', evalInit(def.input.init)],
-      ['param', flow.params],
+      ['input', flow.inputs],
       ['capture', flow.captured],
       ['override', evalInit(def.varOverrides)],
       ['override', rt.o.overrides ?? {}],
@@ -388,12 +434,12 @@ async function execute(
       encoding,
       mediaType: encoding === 'binary' ? def.op.mediaType : undefined,
       formArrays: def.op.formArrays,
-      timeoutMs: def.input.timeoutMs,
-      mockStatus: rt.o.env === 'mock' ? def.input.mock?.status : undefined,
+      timeoutMs: def.input.timeoutMs ?? rt.o.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      mockStatus: rt.o.env === 'mock' ? rt.o.mockStatus : undefined,
       mock:
         rt.o.env === 'mock'
           ? {
-              config: def.input.mock,
+              hook: def.mockHook,
               vars: scope,
               pathParams,
               rawQuery: query,
@@ -412,6 +458,10 @@ async function execute(
       profile,
     }
     emit(rt, { type: 'request', name, request: result.request })
+    if (rt.o.readOnly && kind !== 'auth' && !isReadOnly(def, prepared))
+      throw new StepError(
+        `Refusing ${prepared.method} ${def.op.path} in "${rt.o.env}": this is a --safe run, which only reads.`,
+      )
 
     const send = async () => {
       if (profile) await ensureSession(rt, profile, authResults)
@@ -458,6 +508,17 @@ async function execute(
       for (const r of a.results) {
         emit(rt, { type: r.pass ? 'assert:pass' : 'assert:fail', name, assertion: r })
       }
+    } else if (rt.o.implicitStatusCheck && kind === 'request') {
+      const pass = response.status >= 200 && response.status < 300
+      const implicit: AssertionResult = {
+        label: 'status is 2xx',
+        operator: 'status',
+        pass,
+        actual: response.status,
+        expected: '2xx',
+      }
+      result.assertions = [implicit]
+      emit(rt, { type: pass ? 'assert:pass' : 'assert:fail', name, assertion: implicit })
     }
     if (result.status === 'pass' && result.assertions.some((r) => !r.pass)) result.status = 'fail'
   } catch (e: any) {
@@ -583,7 +644,13 @@ export async function collectSecretNames(
 }
 
 function newRuntime(o: RunOptions): Runtime {
-  return { o, sessions: new Map(), inflight: new Map(), mask: new Set() }
+  // every resolved secret is masked from the start, not only once it has been substituted into a request
+  return {
+    o,
+    sessions: new Map(),
+    inflight: new Map(),
+    mask: new Set(Object.values(o.secrets ?? {})),
+  }
 }
 
 export async function runRequest(
@@ -592,10 +659,22 @@ export async function runRequest(
 ): Promise<RunResult> {
   const rt = newRuntime(o)
   const t0 = o.now?.() ?? now0()
-  emit(rt, { type: 'run:start', id: def.op.id })
+  emit(rt, {
+    type: 'run:start',
+    id: def.op.id,
+    title: def.input.name ?? def.op.id,
+    kind: 'request',
+    tags: def.input.tags,
+  })
   const name = def.input.name ?? def.op.id
   const { result, authResults } = await execute(rt, def, name, NO_FLOW)
-  return finish(rt, 'request', { id: def.op.id, title: name }, [...authResults, result], t0)
+  return finish(
+    rt,
+    'request',
+    { id: def.op.id, title: name, tags: def.input.tags },
+    [...authResults, result],
+    t0,
+  )
 }
 
 export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promise<RunResult> {
@@ -603,7 +682,13 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
   rt.seqAuth = seq.meta.auth
   rt.seqAssertMode = seq.meta.assertMode
   const t0 = o.now?.() ?? now0()
-  emit(rt, { type: 'run:start', id: seq.meta.id })
+  emit(rt, {
+    type: 'run:start',
+    id: seq.meta.id,
+    title: seq.meta.title,
+    kind: 'sequence',
+    tags: seq.meta.tags,
+  })
   const steps: StepResult[] = []
   const captured: Record<string, any> = {}
   const from: Record<string, string> = {}
@@ -611,12 +696,12 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
     Object.assign(captured, values)
     for (const k of Object.keys(values)) from[k] = step
   }
-  let params: Record<string, unknown>
+  let inputs: Record<string, unknown>
   try {
-    params = resolveControls(seq.meta.params ?? {}, o.params)
+    inputs = resolveControls(seq.meta.inputs ?? {}, o.inputs)
   } catch (e: any) {
     steps.push({
-      name: 'params',
+      name: 'inputs',
       kind: 'input',
       status: 'error',
       assertions: [],
@@ -628,7 +713,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
   }
   const vars = o.vars ?? {}
   const ctx = (): StepCtx<any, any> => ({
-    params,
+    inputs,
     captured,
     vars: { ...vars, ...(o.overrides ?? {}) },
     env: o.env,
@@ -652,7 +737,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
       if (node.kind === 'step') {
         const def = typeof node.def === 'function' ? node.def(ctx()) : node.def
         const { result, authResults } = await execute(rt, def, node.name, {
-          params,
+          inputs,
           captured,
           from,
         })
@@ -675,7 +760,7 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
         for (let i = 0; i < items.length; i++) {
           const def = node.def(items[i], ctx(), i)
           const { result, authResults } = await execute(rt, def, `${node.name} #${i + 1}`, {
-            params,
+            inputs,
             captured,
             from,
           })
@@ -700,9 +785,9 @@ export async function runSequence(seq: Sequence<any, any>, o: RunOptions): Promi
         emit(rt, { type: 'input:required', name: node.name, controls: described })
         const given = o.onInput
           ? await o.onInput({ name: node.name, controls: described })
-          : (o.params ?? {})
+          : (o.inputs ?? {})
         const values = resolveControls(controls, given)
-        params = { ...params, ...values }
+        inputs = { ...inputs, ...values }
         steps.push({
           name: node.name,
           kind: 'input',

package/src/runner/suite.ts

@@ -0,0 +1,122 @@
+// Running a list of requests and flows the way `specbook test` does: in order, retrying a failure, stopping at a number of
+// failures or at a global deadline. The CLI and the docs site's terminal share it, so what the page shows is what a
+// terminal does. Nothing here touches files or the process.
+
+import type { Colors } from '../reporters/color'
+import type { Sequence } from '../sequence'
+import type { RequestDef, RunResult } from '../types'
+import { type RunOptions, runRequest, runSequence } from './run'
+
+export interface SuiteTarget {
+  title: string
+  /** project file, shown in reports */
+  file?: string
+  tags: string[]
+  run: RequestDef<any, any, any> | Sequence<any, any>
+}
+
+export interface SuiteOptions {
+  /** what every run is given; `signal` is the suite's own */
+  run: Omit<RunOptions, 'signal'>
+  /** extra tries for a failing target (0 = one try) */
+  retries?: number
+  /** stop after this many failed targets */
+  bail?: number
+  /** milliseconds after which no further target starts, and a running one is aborted */
+  globalTimeoutMs?: number
+  /** called before each try, e.g. to seed faker again */
+  beforeAttempt?: () => void
+  /** called when a failing target is about to be tried again */
+  onRetry?: (target: SuiteTarget, attempt: number, allowed: number) => void
+}
+
+export interface SuiteResult {
+  results: RunResult[]
+  failures: number
+  /** targets that did not start */
+  notRun: number
+  /** why the suite stopped early; empty when it did not */
+  stopped: string
+}
+
+export async function runSuite(targets: SuiteTarget[], o: SuiteOptions): Promise<SuiteResult> {
+  const controller = new AbortController()
+  const deadline = o.globalTimeoutMs
+    ? setTimeout(() => controller.abort(), o.globalTimeoutMs)
+    : undefined
+  const results: RunResult[] = []
+  const allowed = 1 + Math.max(0, o.retries ?? 0)
+  let failures = 0
+  let notRun = 0
+  let stopped = ''
+  for (const [i, t] of targets.entries()) {
+    if (controller.signal.aborted) {
+      notRun = targets.length - i
+      stopped = `stopped: the global timeout of ${o.globalTimeoutMs}ms passed`
+      break
+    }
+    let result: RunResult | undefined
+    let attempt = 0
+    while (attempt < allowed) {
+      attempt++
+      o.beforeAttempt?.()
+      const opts = { ...o.run, signal: controller.signal }
+      result =
+        t.run.kind === 'sequence' ? await runSequence(t.run, opts) : await runRequest(t.run, opts)
+      if (result.status === 'pass' || controller.signal.aborted) break
+      if (attempt < allowed) o.onRetry?.(t, attempt + 1, allowed)
+    }
+    const final = result as RunResult
+    results.push({
+      ...final,
+      file: t.file,
+      attempts: attempt,
+      flaky: final.status === 'pass' && attempt > 1,
+      tags: final.tags.length ? final.tags : t.tags,
+    })
+    if (final.status !== 'pass') failures++
+    if (o.bail && failures >= o.bail && i < targets.length - 1) {
+      notRun = targets.length - i - 1
+      stopped = `stopped after ${failures} failed ${failures === 1 ? 'flow' : 'flows'} (--bail)`
+      break
+    }
+  }
+  if (deadline) clearTimeout(deadline)
+  return { results, failures, notRun, stopped }
+}
+
+/** The line a run opens with: the tool and version, then what is being run and where. */
+export function headerLine(
+  h: {
+    version: string
+    env: string
+    picked: number
+    total: number
+    /** `main@abc1234`, `bundle <sha> built <date>` */
+    where?: string[]
+  },
+  colors: Colors,
+): string {
+  return `${colors.bold(`specbook test ${h.version}`)}  ${colors.dim(
+    [
+      `env ${h.env}`,
+      `${h.picked}${h.picked < h.total ? `/${h.total}` : ''} tests`,
+      ...(h.where ?? []),
+    ].join('  ·  '),
+  )}\n\n`
+}
+
+/** What a retry looks like in a terminal. */
+export const retryLine = (colors: Colors, title: string, attempt: number, allowed: number) =>
+  `  ${colors.yellow('↻')} retrying ${title} (attempt ${attempt} of ${allowed})\n`
+
+/** A bundle's assertions point into the bundled file, which tells a reader nothing. */
+export function withoutLocations(results: RunResult[]): RunResult[] {
+  const strip = (steps: RunResult['steps']): RunResult['steps'] =>
+    steps.map((s) => ({
+      ...s,
+      assertions: s.assertions.map((a) => ({ ...a, location: undefined })),
+      ...(s.children ? { children: strip(s.children) } : {}),
+    }))
+  return results.map((r) => ({ ...r, steps: strip(r.steps) }))
+}