在 Unison 中使用 `:bug` 标记管理已知缺陷:transcript 测试系统的回归防护与“修复确认”机制
在 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>.mdfile provided this executes the transcript and creates<transcript>.output.mdif 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
)
该函数在输出尾部追加:
- 一个 🎉 段落;
- 一个二级标题
You fixed a bug!; - 一个说明性质的代码块正文。
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:bugand close any appropriate Github issues)。这印证了:bug不依赖:error即可独立生效; - unison-src/transcripts/idempotent/bug.md:这是一条仍然有效的
:bug测试。其内容直接点明设计意图—— “This tests that:bugbehaves similarly to:errorwhen 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 框架的代码库)中登记已知缺陷的标准流程如下:
- 登记:在
unison-src/transcripts/下新建.md文件,写出能复现缺陷的命令或 Unison 代码块,并叠加:bug标记;若该缺陷以“报错”形式呈现,可同时叠加:error。示例:``` ucm :error :bug > do.something - 执行:运行
ucm transcript <file>.md(或在仓库内通过 scripts/check.sh 等脚本批量执行)。只要命令确实失败,transcript 便通过,其失败输出会被记录进.output.md作为缺陷快照。 - 修复确认:当缺陷被修复后,重新执行同一 transcript——命令不再失败,Runner 命中
(False, True, False)分支,生成 🎉 与You fixed a bug!段落,并把整个 transcript 判定为失败以强制人工介入。 - 清理:按照 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 代码库中,用同样的方式为每一个已知缺陷建立自动化回归防线。