在 Unison 中使用 `:bug` 标记管理已知缺陷:transcript 测试系统的回归防护与“修复确认”机制

原创2026-10-08 19:46:31393 阅读
文章标签:编程语言编译器语言运行时开发工具

在 Unison 中使用 :bug 标记管理已知缺陷:transcript 测试系统的回归防护与“修复确认”机制

导读

本文围绕 Unison 代码仓库中的 unison-src/transcripts/errors/obsolete-error-bug.output.md 及其配套输入文件,深入讲解 Unison transcript 测试系统中 :error 与 :bug 标记的语义:如何把“已知 bug 的复现场景”固化为一条必须失败的测试,并在 bug 被修复后让测试自动宣告“You fixed a bug!”,从而完成从缺陷登记到回归确认的闭环。读完本文,你将理解 transcript 标记的解析与执行原理(对应 unison-cli/src/Unison/Codebase/Transcript/Parser.hs 与 Runner.hs 中的真实实现),并掌握在真实仓库中书写与维护此类测试的方法。

transcript 是什么:以 Markdown 为载体的可执行测试

在 Unison 仓库中,transcript 是一类以 Markdown 编写的可执行文档测试。CLI 通过 ucm transcript <file>.md 执行其中的命令块,并生成对应的 <file>.output.md 输出文件。该命令的定义位于 unison-cli/src/ArgParse.hs,其帮助文本明确说明:

For each <transcript>.md file provided this executes the transcript and creates <transcript>.output.md if successful.

同一代码库还提供 transcript.fork(在沙箱代码库中执行)与 transcript.in-place(直接在指定代码库上执行)两种变体,三者共享同一套执行引擎。

transcript 文件内部包含多种代码块类型,其中以 ``` 围栏包裹的代码块携带**信息字符串(info string)**来声明行为预期:

信息字符串 含义
ucm 内容为要发给 UCM(Unison Codebase Manager)的命令行
unison 内容为一段 Unison 源代码
api 内容为对 codeserver 的 HTTP API 请求
:error 附加标记:该代码块预期产生错误
:bug 附加标记:该代码块预期失败(作为已知 bug 的占位)
:hide-all / :hide / :show 附加标记:控制输出可见性
:added-by-ucm 附加标记:表示该块由 UCM 自动生成

其中 :error 与 :bug 的解析实现位于 Parser.hs:

formatExpectingError :: ExpectingError -> Maybe Text
formatExpectingError = bool Nothing $ pure ":error"

expectingError :: P ExpectingError
expectingError = isJust <$> optional (word ":error")

formatHasBug :: HasBug -> Maybe Text
formatHasBug = bool Nothing $ pure ":bug"

hasBug :: P HasBug
hasBug = isJust <$> optional (word ":bug")

可以看到 :error 与 :bug 都是独立可选(optional)的词法标记,可以被任意组合使用,例如 ucm :error :bug 或 unison :bug。

obsolete-error-bug 场景:一个“过时”的缺陷标记

本文核心关联文档 obsolete-error-bug.output.md 对应的输入文件是 obsolete-error-bug.md,内容如下:

This transcript will fail, because we’re claiming that the stanza has a bug, but `do.something` errors as expected.

``` ucm :error :bug
> do.something

这段输入描述了一个非常典型的“标记过时”场景:

- 作者曾在代码库中记录了一个 bug:执行 `do.something` 时 UCM 会报错;
- 于是用 `:bug` 标记该代码块,表示“这里存在已知缺陷,测试应当失败”;
- 同时叠加 `:error`,表示“若它失败,失败方式应当是报出错误,而非静默崩溃”;
- 但在编写这条测试时,该缺陷实际上**已经被修复**——`do.something` 现在如预期地报错,而不是产生异常结果。

因此标题中的 `obsolete`(过时)指的就是:`:bug` 标记已经完成了历史使命,不再有意义。执行这条 transcript 后生成的 output 文件给出了完整证据:

```ucm
> do.something

  ⚠️
  I don't know how to do.something. Type `help` or `?` to get
  help.

do.something 正常报出 UCM 的“未知命令”错误(I don't know how to ...),这正是预期行为,说明 bug 已不存在。

执行语义::error 与 :bug 如何决定测试成败

transcript 执行器把信息字符串翻译成两个运行时开关,见 Runner.hs:

writeIORef allowErrors $ expectingError infoTags
writeIORef expectFailure $ hasBug infoTags
  • allowErrors(允许出错)来自 :error:块内命令出现错误是可接受的;
  • expectFailure(预期失败)来自 :bug:块内命令应当失败,用于登记已知 bug。

注意二者会被写进 IORef,并在执行过程中被持续读取。每个 stanza 执行完毕后,Runner 通过一个 case 表达式对三者(errOk、expectBug、hasErr)的组合进行判定,见 Runner.hs:

:error(errOk) :bug(expectBug) 实际出错(hasErr) 结果
True False False 失败:提示 “The transcript was expecting an error ... but did not encounter one.”
False True False 触发 fixedBug:生成 🎉 与 “You fixed a bug!” 段落
其余组合 — — 正常通过

再结合 obsolete-error-bug 的场景对照:do.something 错误地(仍然)出错,hasErr = True,属于“其余组合”,测试不会被判定为失败——这正是输入文件第一句话 “This transcript will fail” 的原因:这条 transcript 本身并不报错,而是会一路执行到底并输出 🎉 提示。obsolete 文件被归入 unison-src/transcripts/errors/ 目录并保留其 output,正是为了向后来的维护者证明“该 bug 已修复,可移除 :bug 并关闭对应的 GitHub issue”。

成功修复时会发生什么:🎉 与 “You fixed a bug!”

当一条 :bug 标记的 stanza 由“失败”变为“成功”(即 expectFailure = True 但命令不再出错)时,Runner 调用 fixedBug 函数,其实现位于 Runner.hs:

fixedBug frontmatter out body = do
  texts <- readIORef out
  ...
  UnliftIO.throwIO . RunFailure . Transcript frontmatter $
    toList texts
      <> ( Left
             <$> [ CMark.Node Nothing CMark.PARAGRAPH [CMark.Node Nothing (CMark.TEXT "🎉") []],
                   CMark.Node Nothing (CMark.HEADING 2) [CMark.Node Nothing (CMark.TEXT "You fixed a bug!") []]
                 ]
               <> bodyNodes
         )

该函数在输出尾部追加:

  1. 一个 🎉 段落;
  2. 一个二级标题 You fixed a bug!;
  3. 一个说明性质的代码块正文。

obsolete-error-bug.output.md 中对应的部分完全一致:

🎉

## You fixed a bug!

The stanza above marked with `:error :bug` is now failing with

⚠️ I don't know how to do.something. Type help or ? to get help.


so you can remove `:bug` and close any appropriate Github issues. If the error message is different from the expected error message, open a new issue and reference it in this transcript.

这段自动生成的收尾文案实际上是一份标准的维护指引:

  • 先展示当前的实际错误输出,便于与预期比对;
  • 指引维护者移除 :bug 标记并关闭相关 GitHub issue;
  • 若实际错误信息与预期不一致,则要求新开 issue 并在该 transcript 中引用。

注意 fixedBug 是通过 RunFailure 抛出的——换言之,对 Runner 来说 “bug 被修复”本身就是一条必须人工处理的测试失败信号,强制触发代码审查与清理流程,这正是 transcript 系统将回归防护落到实处的设计。

对照阅读:obsolete-bug 与 idempotent/bug

为了更完整地理解 :bug 的语义,仓库中还提供了另外两个对照样本:

  • obsolete-bug.md 与其 output:单独使用 :bug(不带 :error),测试 help edit 正常工作。由于该命令同样如预期成功,输出中也出现了 🎉 与 “You fixed a bug!”,并给出同款的清理建议(remove :bug and close any appropriate Github issues)。这印证了 :bug 不依赖 :error 即可独立生效;
  • unison-src/transcripts/idempotent/bug.md:这是一条仍然有效的 :bug 测试。其内容直接点明设计意图—— “This tests that :bug behaves similarly to :error when the stanza fails.”,并且:
    • ucm :bug 块中的 do.something 仍然会失败并输出 I don't know how to do.something ...,表示缺陷尚未修复,测试如实通过;
    • 同时给出 ucm :error :bug 组合块,验证组合标记在“命令正常成功”时应表现为预期成功。

将两个目录下的文件放在一起即可得出完整图景:errors/obsolete-*.md 是历史遗留的“已修复”标记,idempotent/bug.md 是仍在生效的“现存缺陷”标记;errors/ 目录整体用于固化错误输出快照,而 idempotent/ 目录用于保证命令在重复执行时行为一致。

实战:如何用 :error :bug 登记与清理一个已知缺陷

综合源码与上述示例,在 Unison 仓库(或任何使用该 transcript 框架的代码库)中登记已知缺陷的标准流程如下:

  1. 登记:在 unison-src/transcripts/ 下新建 .md 文件,写出能复现缺陷的命令或 Unison 代码块,并叠加 :bug 标记;若该缺陷以“报错”形式呈现,可同时叠加 :error。示例:
    ``` ucm :error :bug
    > do.something
    
  2. 执行:运行 ucm transcript <file>.md(或在仓库内通过 scripts/check.sh 等脚本批量执行)。只要命令确实失败,transcript 便通过,其失败输出会被记录进 .output.md 作为缺陷快照。
  3. 修复确认:当缺陷被修复后,重新执行同一 transcript——命令不再失败,Runner 命中 (False, True, False) 分支,生成 🎉 与 You fixed a bug! 段落,并把整个 transcript 判定为失败以强制人工介入。
  4. 清理:按照 output 中自动生成的指引,移除 :bug(若错误信息与预期一致),关闭对应的 GitHub issue;若错误信息与预期不符,则新开 issue 并在 transcript 中引用。

这套机制的实质,是把“已知 bug”从一个模糊的认知状态,转译成一条语义精确、可自动判定、可留档审计的测试断言:bug 未修复时测试静默通过、bug 修复后测试显式报警——从而让回归永远不可能在无人察觉的情况下发生。

小结

obsolete-error-bug.output.md 虽然只是一份极简的输出快照,但它串联起了 Unison transcript 测试体系的完整链路:

  • 解析层(Parser.hs)负责把 :error、:bug 解析为可选标记;
  • 执行层(Runner.hs)负责把标记翻译成 allowErrors/expectFailure 两个运行时开关,并依据“标记 × 实际结果”的组合矩阵判定成败;
  • 输出层(fixedBug)在缺陷修复时自动生成 🎉 与 “You fixed a bug!” 段落,把“修复确认”变成一段带操作指引的审计记录。

理解这套机制后,你不仅能读懂 unison-src/transcripts/errors/ 与 idempotent/ 下大量 .md/.output.md 文件对的语义,还能在自己维护的 Unison 代码库中,用同样的方式为每一个已知缺陷建立自动化回归防线。

登录后查看全文
unison