编程语言编译器语言运行时开发工具【免费下载链接】unisonA friendly programming language from the future项目地址https://gitcode.com/gh_mirrors/un/unison点击查看免费下载本文深入解析 Unison 代码库转录Transcript测试体系中用于标记已知缺陷的特殊指令:bug。它让开发者能够把当前仍未修复的 bug 固化为可重复的回归用例并借助 UCM 命令行实现故障语义的验证与自动化跟踪读者将掌握:bug与:error的协作规则、解析与判定机制以及如何在日常开发中用最小成本维护已知缺陷清单。一、背景Unison 的转录测试体系Unison 是一门前瞻性编程语言A friendly programming language from the future其命令行工具 UCMUnison Codebase Manager围绕代码库提供了编辑、查询与重构能力。为了确保 UCM 的行为长期稳定项目维护了大量转录transcript测试它们以 Markdown 文档为载体文档中内嵌若干 fenced code block代码围栏块每个代码块就是一段待执行/待校验的小节stanza。转录文件的解析与执行逻辑位于 unison-cli/src/Unison/Codebase/Transcript/Parser.hs 与 unison-cli/src/Unison/Codebase/Transcript/Runner.hs 中。从源码结构看转录文档的 Markdown 节点会被逐个解析为Stanza每个 stanza 依据围栏语言标记ucm、unison、api等分派给对应的执行通道并把 UCM 的真实输出与文档中预先写好的期望输出比对不一致即判定失败。在此基础上围栏的 info string 可以附加若干行为指令例如:error声明该小节预期失败期望遇到错误输出:added-by-ucm声明该小节是 UCM 运行过程中自动生成的见 Parser.hs:bug声明该小节当前正处于一个已知缺陷状态失败是被允许、甚至被期待的。二、:bug指令的语义与:error的对照unison-src/transcripts/idempotent/bug.md 这份文档只有两个用例却精准地刻画了:bug的核心语义原文描述为This tests that:bugbehaves similarly to:errorwhen the stanza fails.该测试验证当小节失败时:bug的行为与:error类似。2.1 单独使用:bug允许失败、标记缺陷 do.something ⚠️ I dont know how to do.something. Type help or ? to get help.这里do.something是一个不存在的标识符UCM 必然报出我不知道如何 do.something的解析错误。如果没有任何指令这个 stanza 会因输出与预期不符或干脆无法产生预期输出而让转录失败但加上:bug后该失败被宽容处理——相当于把这个错误登记为一个已知缺陷转录运行器不会因此终止整个测试流程。从实现上看Runner 在开始处理每个 block 时都会执行writeIORef expectFailure $ hasBug infoTags即把:bug的存在与否写入expectFailure这个 IORef见 Runner.hsUcm、Unison、API三类 block 的处理分支一致。随后在dieUnexpectedSuccess意外成功处理中读取该标志case (errOk, expectBug, hasErr) of (False, True, False) - do fixedBug ... The stanza above with :bug is now passing! You can remove :bug and close any appropriate Github \ \issues. (_, _, _) - pure ()见 Runner.hs。也就是说带:bug的小节没有出错hasErr False时运行器反而会生成一个 You fixed a bug!的失败报告提示你缺陷已修复、可以移除:bug并关闭对应的 GitHub issue带:bug的小节确实出错时属于预期内的失败测试继续不报错。2.2 与:error组合使用验证成功场景 help edit edit edit foo prepends the definition of foo to the top of the most recently saved file. edit without arguments invokes a search to select a definition for editing, which requires that fzf can be found within your PATH.help edit是一条必然成功的命令它输出edit命令的帮助文本包括edit foo的行为描述、以及不带参数时依赖fzf的搜索交互。组合:error :bug后语义变为即使预期错误该小节依然通过。结合 Runner.hs 的maybeDieWithMsg与dieUnexpectedSuccess的分支逻辑可以看清完整的真值表:errorerrOk:bugexpectBug小节实际出错运行器行为无无是转录失败报告错误信息有无否期望错误但未遇到→ 转录失败无有是允许失败当作已知缺陷继续运行无有否You fixed a bug!→ 转录失败提示可移除:bug有有是因errOk与expectBug同时为真走预期失败通道宽容处理有有否同上仍然宽容处理参见(_, _) - pure ()关键结论allowErrors由:error设置与expectFailure由:bug设置是两个独立的布尔标志组合使用时只要至少一个成立小节失败就不会中断转录dieUnexpectedSuccess只在没有任何失败预期或仅:error却成功两种情况下才真正报错。三、解析与格式化hasBug的实现细节Parser.hs中与:bug直接相关的代码极为精简formatHasBug :: HasBug - Maybe Text formatHasBug bool Nothing $ pure :bug hasBug :: P HasBug hasBug isJust $ optional (word :bug)见 Parser.hs。其中word是一个整词匹配的解析器word :: Text - P Text word text P.chunk text * P.notFollowedBy P.alphaNumChar见 Parser.hs。这意味着:bug必须作为独立标记出现后面不能紧跟字母或数字例如:bugx不会被误识别hasBug返回的是Maybe类型Just即表示存在:bug同理formatHasBug在重新序列化转录文档时会依据该布尔值决定是否把:bug写回围栏 info string保证转录文件的往返一致这正是idempotent目录名称的含义转录文档应能被原样重写而不改变语义。值得注意unison类型的围栏同样支持:bug。例如 fix5337.md 中testDoc : Doc2 testDoc {{ key: {{ docWord value }}. }}这段代码在ucm 0.5.26上解析失败I was surprised to find a . here.而同样的代码在0.5.25上可以正常通过类型检查——这是一个典型的行为回退regression尚未修复用例用:bug把缺陷现场固化下来待修复后运行器会主动提醒移除标记。四、fixedBug缺陷被修复时的自动报告当带:bug的小节意外通过时运行器调用fixedBug生成专门的失败报告fixedBug :: Aeson.Value - IORef (Seq Stanza) - Text - IO b fixedBug frontmatter out body do texts - readIORef out let CMark.Node _ _DOCUMENT bodyNodes CMark.commonmarkToNode [CMark.optNormalize] body 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 )见 Runner.hs。报告以和 You fixed a bug! 二级标题开头正文则来自调用方传入的提示文本。这些失败报告最终通过RunFailure异常抛出转录工具会将其追加到输出文档中。类似地当同时标记:error :bug的小节出乎意料地失败即错误信息与预期不一致时maybeDieWithMsg会走(True, True)分支提示The stanza above marked with:error :bugis now failing with..., so you can remove:bugand 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.见 Runner.hs。这里的提示同时给出了两条工作流指引错误一致 → 移除:bug并关闭 issue错误不一致 → 重新开 issue 并在转录中引用。五、与其他指令的协作与组合技巧5.1:added-by-ucm与:hide转录文档中常常出现由 UCM 自动生成的 block例如fix5337.md中紧随:bug代码块之后的ucm :added-by-ucm块其中记录了真实出错时 UCM 的输出。这类块由运行器在检测到 scratch 文件变更后自动回填相关队列与回填逻辑见 Runner.hs保证输入小节 期望输出成对出现、可复现。此外:hide/:hide-all/:show指令控制输出是否回显到转录文档中解析与格式化实现见 Parser.hs它们与:bug正交可按需组合。5.2 实践中推荐的最小组合未修复缺陷在围栏标记:bug并将当前的真实错误输出以:added-by-ucm或手工写入形式记录在文档中缺陷恰好也在触发错误路径用:error :bug同时声明这里既预期错误、又处于已知缺陷状态缺陷已修复移除:bug必要时也移除:error让转录恢复为普通断言。六、源码索引速查关注点位置转录文档解析、围栏 info string 指令解析:bug/:error/:added-by-ucm等unison-cli/src/Unison/Codebase/Transcript/Parser.hs转录运行器、expectFailure/allowErrors标志、fixedBug报告与RunFailure异常unison-cli/src/Unison/Codebase/Transcript/Runner.hs:bug语义核心测试用例unison-src/transcripts/idempotent/bug.md:bug用于unison代码块的真实缺陷案例unison-src/transcripts/idempotent/fix5337.md七、小结:bug是 Unison 转录测试体系中一个轻量但实用的状态标记它把已知缺陷从口头备注变成可执行的测试断言失败时静默通过、修复后主动告警从而避免缺陷清单无人维护与回归悄悄混入两个极端。理解Parser.hs的hasBug解析与Runner.hs的expectFailure/fixedBug判定逻辑后你就能在自己的转录文件中准确使用:bug、:error及其组合让每一条已知缺陷都有据可查、有证可循。赞分享编程语言编译器语言运行时开发工具【免费下载链接】unisonA friendly programming language from the future项目地址https://gitcode.com/gh_mirrors/un/unison点击查看免费下载相关推荐Unison 的 delete.project 命令项目删除语义与实现原理完全指南Unison 的 delete.project 命令项目删除语义与实现原理完全指南 本指南基于 Unison 代码库管理工具UCM的行为转录文档 dele编程语言编译器语言运行时开发工具Unison 并发原语 MVar 实战从 io2.MVar 语义到 base 库测试与运行时实现Unison 并发原语 MVar 实战从 io2.MVar 语义到 base 库测试与运行时实现 io2.MVar 是 Unison 标准库中的核心并发原语编程语言编译器语言运行时开发工具Unison 转录测试中的 obsolete-bug 模式用 :bug 标记追踪已被修复的缺陷Unison 转录测试中的 obsolete bug 模式用 :bug 标记追踪已被修复的缺陷 这篇技术指南围绕 Unison 代码库中 unison src编程语言编译器语言运行时开发工具上一篇Frog核心功能详解如何高效提取YouTube视频、网页截图和PDF中的文字下一篇OpenSpeedy贡献指南如何参与开源游戏加速项目的10个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考