@pmelab/gtd 59.0.0 → 60.0.0

package/src/gherkin/index.ts

@@ -1,6 +1,8 @@
 // Generic quickpickle steps over `testRepo`: they name no workflow, so any
 // workflow's `.feature` can use them. A workflow's own steps live beside it.
 import {
+  After,
+  AfterAll,
   Given,
   QuickPickleWorld,
   Then,
@@ -16,15 +18,38 @@ import { pathToFileURL } from "node:url"
 import {
   runsItsScript,
   testRepo,
-  type Actor,
   type CannedCommand,
+  type DriveOptions,
+  type ScriptedActor,
   type TestRepo,
   type WorkflowModule,
 } from "../testkit/index.js"
+import {
+  assertContains,
+  assertLacks,
+  assertRestsAt,
+  refusal,
+  refusedWith,
+  restDescription,
+  unreachedList,
+  type Unreached,
+} from "./messages.js"
+
+// Kept on quickpickle's per-feature `common`: which steps a Background scripted,
+// and whether any scenario reached each.
+const BACKGROUND_ACTORS = "gtdBackgroundActors"
+
+interface BackgroundActors {
+  readonly reached: Map<string, boolean>
+  // The feature file's vitest task, to tell whether every scenario ran.
+  file: { readonly tasks?: readonly unknown[] } | undefined
+}
 
 export class TestkitWorld extends QuickPickleWorld {
   // Re-declared: under `nodenext` a subclass loses the base's members from TS's view.
   declare info: QuickPickleWorldInterface["info"]
+  declare common: QuickPickleWorldInterface["common"]
+  declare context: TestContext
 
   constructor(context: TestContext, info: InfoConstructor) {
     super(context, info)
@@ -33,11 +58,16 @@ export class TestkitWorld extends QuickPickleWorld {
   private gtdConfig: WorkflowModule | undefined = undefined
   private env: Record<string, string> = {}
   private commands: CannedCommand[] = []
-  /** Per step, what its scripted actor does, in the order the scenario declared it. */
-  actions = new Map<string, Actor[]>()
-  verdicts = new Map<string, string>()
-  /** Per judge step, a verdict for each text its questions may contain; the first match answers. */
-  conditionalVerdicts = new Map<string, [text: string, verdict: string][]>()
+  private modules: Record<string, Readonly<Record<string, unknown>>> = {}
+  private actions = new Map<string, ScriptedActor[]>()
+  private verdicts = new Map<string, string>()
+  private conditionalVerdicts = new Map<string, [text: string, verdict: string][]>()
+  private prompts = new Map<string, string[]>()
+  private used = new Set<string>()
+  // A step a scenario step scripts is the scenario's, even if a Background scripted it too.
+  private origins = new Map<string, Unreached["origin"]>()
+  private backgroundScripted = new Set<string>()
+  private excused = new Set<string>()
   private created: TestRepo | undefined = undefined
 
   // The repository is created on first use and keeps the config and
@@ -66,6 +96,21 @@ export class TestkitWorld extends QuickPickleWorld {
     this.env[name] = value
   }
 
+  /** Unlike `setEnv`, also once the repository exists: gtd sees it from its next call on. */
+  changeEnv(name: string, value: string): void {
+    if (this.created === undefined) this.env[name] = value
+    else this.created.setEnv(name, value)
+  }
+
+  /**
+   * Lets a config given as source import `module` as `specifier`. A support
+   * file may call it for every scenario, e.g. from a `Before` hook.
+   */
+  importable(specifier: string, module: Readonly<Record<string, unknown>>): void {
+    this.assertNotCreated(`the module ${specifier}`)
+    this.modules[specifier] = module
+  }
+
   private assertNotCreated(what: string): void {
     if (this.created !== undefined) {
       throw new Error(`${what} must be set before any step that touches the repository`)
@@ -79,15 +124,87 @@ export class TestkitWorld extends QuickPickleWorld {
       workflow: this.gtdConfig,
       env: this.env,
       commands: this.commands,
+      modules: this.modules,
     }))
   }
 
-  act(step: string, action: Actor): void {
+  // quickpickle numbers a (Rule) Background's steps negatively.
+  private scripting(step: string, replace = false): void {
+    const fromBackground = (this.info.stepIdx ?? 0) < 0
+    if (fromBackground) this.backgroundScripted.add(step)
+    if (!fromBackground || replace || !this.origins.has(step))
+      this.origins.set(step, fromBackground ? "Background" : "scenario")
+  }
+
+  /** Adds `action` to what `step`'s actor does at every visit. */
+  act(step: string, action: ScriptedActor): void {
+    this.scripting(step)
     this.actions.set(step, [...(this.actions.get(step) ?? []), action])
   }
 
-  async drive(): Promise<void> {
-    const actors: Record<string, Actor> = {}
+  /** Drops every action and prompt queued for `step`, leaving `action` alone. */
+  rescript(step: string, action: ScriptedActor): void {
+    this.scripting(step, true)
+    this.actions.set(step, [action])
+    this.prompts.delete(step)
+  }
+
+  /** Drops every action and prompt queued for `step`, so a drive rests there. */
+  unscript(step: string): void {
+    this.actions.delete(step)
+    this.prompts.delete(step)
+  }
+
+  /**
+   * `step`'s beat content must contain `text`. A scripted step is checked at
+   * every visit, before its actor acts; a step with nothing else scripted is
+   * not scripted at all, so a drive rests there and checks it at the rest.
+   */
+  expectPrompt(step: string, text: string): void {
+    this.scripting(step)
+    this.prompts.set(step, [...(this.prompts.get(step) ?? []), text])
+  }
+
+  /** Judge step `step` answers `verdict`, a JSON array. */
+  answer(step: string, verdict: string): void {
+    this.scripting(step)
+    this.verdicts.set(step, verdict)
+  }
+
+  /** Judge step `step` answers `verdict` when its questions contain `text`; the first match answers. */
+  answerWhen(step: string, text: string, verdict: string): void {
+    this.scripting(step)
+    this.conditionalVerdicts.set(step, [
+      ...(this.conditionalVerdicts.get(step) ?? []),
+      [text, verdict],
+    ])
+  }
+
+  private scripted(): Set<string> {
+    return new Set([
+      ...this.actions.keys(),
+      ...this.verdicts.keys(),
+      ...this.conditionalVerdicts.keys(),
+      ...this.prompts.keys(),
+    ])
+  }
+
+  /** The steps the scenario scripted, or expects a prompt at, that no drive has reached. */
+  neverUsed(): Unreached[] {
+    return [...this.scripted()]
+      .filter((step) => !this.used.has(step))
+      .map((step) => ({ step, origin: this.origins.get(step) ?? "scenario" }))
+  }
+
+  private checkPrompts(step: string, content: string): void {
+    for (const text of this.prompts.get(step) ?? []) {
+      if (!content.includes(text))
+        throw new Error(`step "${step}" was not prompted with "${text}":\n${content}`)
+    }
+  }
+
+  private actors(): Record<string, ScriptedActor> {
+    const actors: Record<string, ScriptedActor> = {}
     for (const [step, actions] of this.actions) {
       actors[step] = async (beat, repo) => {
         for (const action of actions) await action(beat, repo)
@@ -115,15 +232,119 @@ export class TestkitWorld extends QuickPickleWorld {
         return hit[1]
       }
     }
-    await this.repo().drive(actors)
+    return actors
+  }
+
+  /**
+   * `strict: false` lets what a strict drive refuses pass. Every drive leaves
+   * scripted steps it never reached to `assertReached`: an earlier step may
+   * script one for a later drive.
+   */
+  async drive(options: DriveOptions = {}): Promise<void> {
+    try {
+      const actors = this.actors()
+      const tracked: Record<string, ScriptedActor> = {}
+      for (const [step, actor] of Object.entries(actors)) {
+        tracked[step] = (beat, repo) => {
+          this.used.add(step)
+          this.checkPrompts(step, beat.content)
+          return actor(beat, repo)
+        }
+      }
+      const rest = await this.repo().drive(tracked, { ...options, unreachedActors: "pass" })
+      if (rest.kind !== "stalled" && this.prompts.has(rest.state) && !(rest.state in actors)) {
+        this.used.add(rest.state)
+        this.checkPrompts(rest.state, rest.content)
+      }
+    } catch (error) {
+      // Where a refused drive would have gone is unknown, so every step it was handed is excused.
+      for (const step of this.scripted()) this.excused.add(step)
+      throw error
+    }
+  }
+
+  /**
+   * Fails on a step a scenario step scripted, or expects a prompt at, that no
+   * drive reached. Run at scenario end. A Background's steps are left to the
+   * feature's end, and the steps a refused drive was handed are excused.
+   */
+  async assertReached(): Promise<void> {
+    const never = this.neverUsed()
+    const dead = never.filter(
+      ({ step, origin }) => origin === "scenario" && !this.excused.has(step),
+    )
+    if (dead.length === 0) return
+    throw new Error(
+      `at scenario end, no drive reached the steps scripted for ${unreachedList(dead)} — script a step only for a drive that reaches it, or in the Background when only some scenarios reach it\n\n${await restDescription(() => this.repo(), never)}`,
+    )
+  }
+
+  /** Records, for the feature's end, which Background-scripted steps this scenario reached. */
+  recordBackground(): void {
+    const record = (this.common[BACKGROUND_ACTORS] ??= {
+      reached: new Map(),
+      file: undefined,
+    }) as BackgroundActors
+    record.file ??= (this.context as Partial<TestContext> | undefined)?.task?.file
+    // A failed scenario stopped early, so it cannot tell a dead actor from one it did not get to.
+    const failed = this.info.errors.length > 0
+    for (const step of this.backgroundScripted) {
+      record.reached.set(step, record.reached.get(step) === true || failed || this.used.has(step))
+    }
   }
 }
 
+After(async (world: QuickPickleWorldInterface) => {
+  if (!(world instanceof TestkitWorld)) return
+  world.recordBackground()
+  // Only for a scenario whose steps all passed: a failed one already reports.
+  if (world.info.errors.length === 0) await world.assertReached()
+})
+
+// vitest marks a test it filtered out, or skipped, as not run.
+const allRan = (tasks: readonly unknown[]): boolean =>
+  tasks.every((task) => {
+    const t = task as { mode?: string; result?: { state?: string }; tasks?: readonly unknown[] }
+    if (t.tasks !== undefined) return allRan(t.tasks)
+    return t.mode === "run" && t.result?.state !== "skip"
+  })
+
+// Per feature: a Background step no scenario reached scripts nothing. Left out
+// when a scenario did not run, since it may be the one that reaches it.
+AfterAll((common: QuickPickleWorldInterface["common"]) => {
+  const record = common[BACKGROUND_ACTORS] as BackgroundActors | undefined
+  if (record === undefined) return
+  if (record.file?.tasks !== undefined && !allRan(record.file.tasks)) return
+  const dead = [...record.reached].filter(([, reached]) => !reached)
+  if (dead.length === 0) return
+  throw new Error(
+    `${common.info.feature}: no scenario reached the steps scripted for ${unreachedList(dead.map(([step]) => ({ step, origin: "Background" })))} — script a step in the Background only when some scenario reaches it`,
+  )
+})
+
 setWorldConstructor(TestkitWorld)
 
 const withNewline = (content: string): string => (content.endsWith("\n") ? content : `${content}\n`)
 
-const args = (list: string): string[] => list.split(" ").filter((arg) => arg !== "")
+// Space-separated; a word that opens with a quote runs to its closing quote,
+// spaces included, so `--var 'title=a b'` is two arguments.
+const args = (list: string): string[] =>
+  [...list.matchAll(/(["'])(.*?)\1(?=\s|$)|\S+/g)].map(([word, quote, inner]) =>
+    quote === undefined ? word : inner!,
+  )
+
+/** An outcome step: a failure ends with where the process rests. */
+const outcome =
+  <A extends unknown[]>(check: (world: TestkitWorld, ...rest: A) => unknown) =>
+  async (world: TestkitWorld, ...rest: A): Promise<void> => {
+    try {
+      await check(world, ...rest)
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error))
+      failure.message += `\n\n${await restDescription(() => world.repo(), world.neverUsed())}`
+      throw failure
+    }
+  }
 
 Given("a gtd config with:", (world: TestkitWorld, source: string) => {
   world.configure(withNewline(source))
@@ -141,12 +362,27 @@ Given("the gtd config ends with:", (world: TestkitWorld, source: string) => {
 })
 
 Given(
-  "an environment variable {string} set to {string}",
+  "the environment variable {string} is {string}",
   (world: TestkitWorld, name: string, value: string) => {
     world.setEnv(name, value)
   },
 )
 
+Given(
+  "from now on the environment variable {string} is {string}",
+  (world: TestkitWorld, name: string, value: string) => {
+    world.changeEnv(name, value)
+  },
+)
+
+// Imported by the test runner, like `a gtd config from the module`.
+Given(
+  "the module {string} is importable as {string}",
+  async (world: TestkitWorld, path: string, specifier: string) => {
+    world.importable(specifier, { ...(await import(pathToFileURL(resolve(path)).href)) })
+  },
+)
+
 Given("the command {string} exits {int}", (world: TestkitWorld, run: string, exit: number) => {
   world.command({ run, exit })
 })
@@ -158,10 +394,28 @@ Given(
   },
 )
 
+Given(
+  "the command matching {string} exits {int}",
+  (world: TestkitWorld, pattern: string, exit: number) => {
+    world.command({ run: new RegExp(pattern), exit })
+  },
+)
+
+Given(
+  "the command matching {string} exits {int} with:",
+  (world: TestkitWorld, pattern: string, exit: number, output: string) => {
+    world.command({ run: new RegExp(pattern), exit, output: withNewline(output) })
+  },
+)
+
 Given("a branch {string}", (world: TestkitWorld, name: string) => {
   world.repo().branch(name)
 })
 
+Given("a branch {string} at {string}", (world: TestkitWorld, name: string, ref: string) => {
+  world.repo().branch(name, ref)
+})
+
 Given("{string} is checked out", (world: TestkitWorld, name: string) => {
   world.repo().checkout(name)
 })
@@ -191,7 +445,7 @@ Given(
   },
 )
 
-Given("{string} gets appended:", (world: TestkitWorld, path: string, text: string) => {
+Given("text is appended to {string}:", (world: TestkitWorld, path: string, text: string) => {
   const content = world.repo().read(path) ?? ""
   world.repo().write(path, `${content.trimEnd()}\n\n${text}\n`)
 })
@@ -210,12 +464,12 @@ Given("step {string} changes nothing", (world: TestkitWorld, step: string) => {
 
 // Unlike `changes nothing`, this drops every action already queued for the step.
 Given("step {string} from now on changes nothing", (world: TestkitWorld, step: string) => {
-  world.actions.set(step, [() => undefined])
+  world.rescript(step, () => undefined)
 })
 
 // Lets a later visit rest at a step an earlier one had scripted.
 Given("step {string} is no longer scripted", (world: TestkitWorld, step: string) => {
-  world.actions.delete(step)
+  world.unscript(step)
 })
 
 Given(
@@ -263,23 +517,19 @@ Given("step {string} deletes {string}", (world: TestkitWorld, step: string, path
   world.act(step, (_, repo) => repo.remove(path))
 })
 
-// A standing assertion like any queued action: it applies on every later visit
-// to the step until `from now on` clears the list.
+// A standing assertion: it applies on every later visit to the step until
+// `from now on` or `no longer scripted` clears it.
 Given(
   "step {string} is prompted with {string}",
   (world: TestkitWorld, step: string, text: string) => {
-    world.act(step, (beat) => {
-      if (!beat.content.includes(text)) {
-        throw new Error(`step "${step}" was not prompted with "${text}":\n${beat.content}`)
-      }
-    })
+    world.expectPrompt(step, text)
   },
 )
 
 // A closing step deletes the file before its collecting turn runs, so this edit
 // leaves a closed turn changing nothing while still answering an in-gate one.
 Given(
-  "step {string} rewrites {string} with:",
+  "step {string} overwrites {string}, if it exists, with:",
   (world: TestkitWorld, step: string, path: string, content: string) => {
     world.act(step, (_, repo) => {
       if (repo.read(path) !== undefined) repo.write(path, withNewline(content))
@@ -291,17 +541,31 @@ Given("step {string} runs its script", (world: TestkitWorld, step: string) => {
   world.act(step, runsItsScript)
 })
 
+/** A check step's script, every command it runs answering as `command` does. */
+const checkRuns = (world: TestkitWorld, step: string, command: Omit<CannedCommand, "run">) => {
+  world.act(step, (beat, repo) => {
+    if (beat.actor !== "check")
+      throw new Error(`step "${step}" is no check step; its actor is ${beat.actor}`)
+    repo.runScript(beat.content, { commands: [{ ...command, run: /[\s\S]*/ }] })
+  })
+}
+
+Given("check step {string} passes", (world: TestkitWorld, step: string) => {
+  checkRuns(world, step, {})
+})
+
+Given("check step {string} fails with:", (world: TestkitWorld, step: string, output: string) => {
+  checkRuns(world, step, { exit: 1, output: withNewline(output) })
+})
+
 Given("judge step {string} answers:", (world: TestkitWorld, step: string, verdict: string) => {
-  world.verdicts.set(step, String(verdict))
+  world.answer(step, String(verdict))
 })
 
 Given(
   "judge step {string}, when its questions contain {string}, answers:",
   (world: TestkitWorld, step: string, text: string, verdict: string) => {
-    world.conditionalVerdicts.set(step, [
-      ...(world.conditionalVerdicts.get(step) ?? []),
-      [text, String(verdict)],
-    ])
+    world.answerWhen(step, text, String(verdict))
   },
 )
 
@@ -335,76 +599,172 @@ When("the process is driven", async (world: TestkitWorld) => {
   await world.drive()
 })
 
+When("the process is driven leniently", async (world: TestkitWorld) => {
+  await world.drive({ strict: false })
+})
+
 Then(
   "opening door {string} is refused with {string}",
-  async (world: TestkitWorld, door: string, message: string) => {
-    await assert.rejects(world.repo().door(door), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, door: string, message: string) => {
+    await refusedWith(world.repo().door(door), message)
+  }),
 )
 
 Then(
   "starting workflow {string} with {string} is refused with {string}",
-  async (world: TestkitWorld, workflow: string, list: string, message: string) => {
-    await assert.rejects(world.repo().start(workflow, ...args(list)), (error: Error) =>
-      error.message.includes(message),
-    )
-  },
+  outcome(async (world, workflow: string, list: string, message: string) => {
+    await refusedWith(world.repo().start(workflow, ...args(list)), message)
+  }),
 )
 
-Then("landing is refused with {string}", async (world: TestkitWorld, message: string) => {
-  await assert.rejects(world.repo().land(), (error: Error) => error.message.includes(message))
-})
+Then(
+  "landing is refused with {string}",
+  outcome(async (world, message: string) => {
+    await refusedWith(world.repo().land(), message)
+  }),
+)
 
 Then(
   "driving the process is refused with {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    await refusedWith(world.drive(), message)
+  }),
 )
 
 Then(
   "driving the process is refused without {string}",
-  async (world: TestkitWorld, message: string) => {
-    await assert.rejects(world.drive(), (error: Error) => !error.message.includes(message))
-  },
+  outcome(async (world, message: string) => {
+    const got = await refusal(world.drive(), `without "${message}"`)
+    if (got.includes(message))
+      assert.fail(`expected a refusal without "${message}", but it was refused with:\n${got}`)
+  }),
 )
 
-Then("the process rests at {string}", async (world: TestkitWorld, step: string) => {
-  assert.strictEqual((await world.repo().next()).state, step)
-})
+Then(
+  "the process rests at {string}",
+  outcome(async (world, step: string) => {
+    assertRestsAt(await world.repo().next(), step)
+  }),
+)
 
-Then("the resting step's content contains {string}", async (world: TestkitWorld, text: string) => {
-  const { content } = await world.repo().next()
-  assert.ok(content.includes(text), content)
-})
+Then(
+  "the process stalls at {string}",
+  outcome(async (world, step: string) => {
+    const beat = await world.repo().next()
+    if (beat.kind !== "stalled" || beat.state !== step)
+      assert.fail(
+        `expected a stall at "${step}", but the process rests at "${beat.state}" (${beat.kind})`,
+      )
+  }),
+)
+
+/** A beat field by its dotted path (`model`, `access.write`), as text: a string as is, anything else as JSON. */
+const beatField = async (world: TestkitWorld, path: string): Promise<unknown> => {
+  let value: unknown = await world.repo().next()
+  for (const key of path.split(".")) {
+    value =
+      typeof value === "object" && value !== null
+        ? (value as Record<string, unknown>)[key]
+        : undefined
+  }
+  return value
+}
+
+const asText = (value: unknown): string =>
+  typeof value === "string" ? value : (JSON.stringify(value) ?? "undefined")
+
+Then(
+  "the resting step's {word} is {string}",
+  outcome(async (world, path: string, expected: string) => {
+    const value = asText(await beatField(world, path))
+    if (value !== expected)
+      assert.fail(`the resting step's ${path} is not "${expected}"; it is:\n${value}`)
+  }),
+)
+
+Then(
+  "the resting step's {word} includes {string}",
+  outcome(async (world, path: string, expected: string) => {
+    const value = await beatField(world, path)
+    const found = Array.isArray(value)
+      ? value.some((item) => asText(item) === expected)
+      : typeof value === "string" && value.includes(expected)
+    if (!found)
+      assert.fail(
+        `the resting step's ${path} does not include "${expected}"; it is:\n${asText(value)}`,
+      )
+  }),
+)
+
+Then(
+  "the resting step's content contains {string}",
+  outcome(async (world, text: string) => {
+    assertContains("the resting step's content", text, (await world.repo().next()).content)
+  }),
+)
 
 Then(
   "the resting step's content contains the hash of the commit {string}",
-  async (world: TestkitWorld, subject: string) => {
+  outcome(async (world, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    const { content } = await repo.next()
-    assert.ok(content.includes(hash), content)
-  },
+    assertContains("the resting step's content", hash, (await repo.next()).content)
+  }),
 )
 
 Then(
   "the resting step's content does not contain {string}",
-  async (world: TestkitWorld, text: string) => {
-    const { content } = await world.repo().next()
-    assert.ok(!content.includes(text), content)
-  },
+  outcome(async (world, text: string) => {
+    assertLacks("the resting step's content", text, (await world.repo().next()).content)
+  }),
 )
 
-Then("the last commit subject is {string}", (world: TestkitWorld, subject: string) => {
-  assert.strictEqual(world.repo().subjects().at(-1), subject)
-})
+Then(
+  "the last commit subject is {string}",
+  outcome((world, subject: string) => {
+    assert.strictEqual(world.repo().subjects().at(-1), subject)
+  }),
+)
 
-Then("the commit subjects end with:", (world: TestkitWorld, list: string) => {
-  const expected = list.split("\n").filter((line) => line.trim() !== "")
-  assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
-})
+Then(
+  "the commit subjects end with:",
+  outcome((world, list: string) => {
+    const expected = list.split("\n").filter((line) => line.trim() !== "")
+    assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected)
+  }),
+)
+
+Then(
+  "the last commit body contains {string}",
+  outcome((world, text: string) => {
+    assertContains("the last commit's message", text, world.repo().messages().at(-1))
+  }),
+)
+
+// Every commit with the subject, so a repeated step is not judged by its first match.
+Then(
+  "the commit {string} has a body containing {string}",
+  outcome((world, subject: string, text: string) => {
+    const matching = world
+      .repo()
+      .commits()
+      .filter((commit) => commit.subject === subject)
+    assert.ok(matching.length > 0, `no commit "${subject}"`)
+    for (const { message } of matching) assertContains(`the commit "${subject}"`, text, message)
+  }),
+)
+
+Then(
+  "no commit body contains {string}",
+  outcome((world, text: string) => {
+    const hit = world
+      .repo()
+      .messages()
+      .find((message) => message.includes(text))
+    if (hit !== undefined) assert.fail(`a commit's message contains "${text}":\n${hit}`)
+  }),
+)
 
 const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
   const result = await world.repo().gtd(...args(list))
@@ -414,61 +774,84 @@ const outputOf = async (world: TestkitWorld, list: string): Promise<string> => {
 
 Then(
   "the output of gtd {string} contains {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertContains(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output of gtd {string} does not contain {string}",
-  async (world: TestkitWorld, list: string, text: string) => {
-    const out = await outputOf(world, list)
-    assert.ok(!out.includes(text), out)
-  },
+  outcome(async (world, list: string, text: string) => {
+    assertLacks(`the output of gtd ${list}`, text, await outputOf(world, list))
+  }),
 )
 
 Then(
   "the output lines of gtd {string} start with:",
-  async (world: TestkitWorld, list: string, prefixes: string) => {
+  outcome(async (world, list: string, prefixes: string) => {
     const out = (await outputOf(world, list)).split("\n").filter((line) => line !== "")
     const expected = prefixes.split("\n").filter((line) => line.trim() !== "")
-    assert.strictEqual(out.length, expected.length, out.join("\n"))
-    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), out.join("\n")))
-  },
+    const sides = `expected lines starting with:\n${expected.join("\n")}\ngot:\n${out.join("\n")}`
+    assert.strictEqual(out.length, expected.length, sides)
+    out.forEach((line, i) => assert.ok(line.startsWith(expected[i]!), sides))
+  }),
 )
 
-Then("{string} contains {string}", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains {string}",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} contains:", (world: TestkitWorld, path: string, text: string) => {
-  assert.ok(world.repo().read(path)?.includes(text), `${path}: ${world.repo().read(path)}`)
-})
+Then(
+  "{string} contains:",
+  outcome((world, path: string, text: string) => {
+    assertContains(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
 Then(
   "{string} contains the short hash of the commit {string}",
-  (world: TestkitWorld, path: string, subject: string) => {
+  outcome((world, path: string, subject: string) => {
     const repo = world.repo()
     const hash = repo.hashes()[repo.subjects().lastIndexOf(subject)]
     assert.ok(hash !== undefined, `no commit "${subject}"`)
-    assert.ok(repo.read(path)?.includes(hash.slice(0, 7)), `${path}: ${repo.read(path)}`)
-  },
+    assertContains(`"${path}"`, hash.slice(0, 7), repo.read(path))
+  }),
+)
+
+Then(
+  "{string} as committed at {string} contains {string}",
+  outcome((world, path: string, ref: string, text: string) => {
+    assertContains(`"${path}" at ${ref}`, text, world.repo().show(ref, path))
+  }),
 )
 
 Then(
   "{string} contains {string} exactly once",
-  (world: TestkitWorld, path: string, text: string) => {
+  outcome((world, path: string, text: string) => {
     const content = world.repo().read(path) ?? ""
-    assert.strictEqual(content.split(text).length - 1, 1, `${path}: ${content}`)
-  },
+    const times = content.split(text).length - 1
+    assert.strictEqual(
+      times,
+      1,
+      `"${path}" contains "${text}" ${times} times; it holds:\n${content}`,
+    )
+  }),
 )
 
-Then("{string} does not contain {string}", (world: TestkitWorld, path: string, text: string) => {
-  const content = world.repo().read(path)
-  assert.ok(content !== undefined && !content.includes(text), `${path}: ${content}`)
-})
+Then(
+  "{string} does not contain {string}",
+  outcome((world, path: string, text: string) => {
+    assertLacks(`"${path}"`, text, world.repo().read(path))
+  }),
+)
 
-Then("{string} does not exist", (world: TestkitWorld, path: string) => {
-  assert.strictEqual(world.repo().read(path), undefined)
-})
+Then(
+  "{string} does not exist",
+  outcome((world, path: string) => {
+    const content = world.repo().read(path)
+    assert.strictEqual(content, undefined, `"${path}" exists; it holds:\n${content}`)
+  }),
+)