使用 Markdown 作为声明式测试规范：EndBASIC 的实践与权衡

测试代码的可读性与维护成本一直是工程团队的痛点。传统单元测试往往深陷于断言语法与嵌套结构的泥沼，当测试规模膨胀至数百个用例时，任何微小的实现变更都可能触发连锁式的测试代码重写。EndBASIC 项目近期开源的 Markdown 测试套件提供了一条值得借鉴的路径：将测试规范直接嵌入 Markdown 文档，让测试文件同时具备人类可读性与机器可执行性。

声明式测试的结构化表达

EndBASIC 的测试套件由 448 个测试用例组成，分散在 13,000 余行 Markdown 文件中。每个 .md 文件充当测试容器，内部通过一级标题划分独立测试用例。这种结构天然契合 "文档即代码" 的理念 —— 测试文件首先是一份可读的技术文档，其次才是可被驱动程序解析的执行指令。

单个测试用例遵循固定的区块约定：

• Source：以代码块形式嵌入待测源代码，驱动程序提取该区块内容喂给编译器
• Disassembly：记录编译后的字节码输出，用于验证编译器优化与指令生成
• Exit code / Output / Runtime errors：分别捕获程序退出码、标准输出流与运行时异常

当编译失败时，预期输出替换为 Compilation errors 区块，列出具体的错误信息。这种结构消除了传统测试中assert_eq!式的机械断言，转而采用完整的输入输出快照（snapshot）进行行为验证。

驱动机制与 Golden File 模式

测试驱动的实现保持了刻意的精简。驱动程序仅需解析 Markdown 的子集 —— 识别一级标题与特定命名的代码块 —— 即可提取测试用例。执行流程遵循经典的 Golden File 模式：驱动将每个 Source 区块喂给编译器与虚拟机，捕获所有副作用后生成一份全新的 Markdown 文件，再与版本控制中记录的 "金标准"（golden file）进行文本比对。

文本比对的优势在于 diff 的直观性。当测试失败时，开发者看到的不是堆栈跟踪中的行号偏移，而是与预期输出的逐行差异。EndBASIC 的作者 Julio Merino 特别指出，这种 diff 输出 "对人类而言极易理解"，甚至可以直接作为调试线索。

针对大规模变更场景，驱动程序支持 REGEN=true 环境变量。启用后，驱动不再执行比对，而是直接覆写 golden file。这一设计将批量更新测试预期从繁琐的手动编辑转化为可控的自动化流程 —— 开发者可以在 Git 的 diff 视图中审阅所有变更，确认无误后随代码改动一并提交。

工程实践中的权衡

Markdown 测试套件并非银弹，其适用边界需要在工程实践中审慎评估。

优势侧：编辑器生态对 Markdown 的一流支持使测试文件具备天然的浏览与编辑体验；代码块的语法高亮让测试场景一目了然；更重要的是，这种格式对 LLM 极为友好 ——EndBASIC 团队验证，将测试文件喂给 GPT 后，模型能够准确归纳出语言的方言特性与使用规则，这为 AI 辅助编程提供了高质量的训练素材。

风险侧：REGEN 的便利性是一把双刃剑。当更新 golden file 过于容易时，开发者可能在未经仔细审查的情况下批量接受变更，从而掩盖掉位置信息偏移或指令序列中的细微错误。此外，反汇编输出中的地址偏移会导致 diff 噪音 —— 任何新增或删除的指令都会使后续所有地址发生位移，使得变更审查变得困难。EndBASIC 选择保留地址信息以辅助手动验证跳转目标，但这也意味着需要建立更严格的 diff 审查流程。

另一个技术限制来自 Rust 的测试框架本身。由于 Rust 无法在运行时动态生成测试用例，单个 Markdown 文件内的多个测试用例无法被 cargo test 的过滤器单独识别。EndBASIC 的折中方案是将每个 Markdown 文件暴露为一个 Rust 原生测试用例，但这要求维护一个硬编码的文件列表，并辅以额外的交叉校验测试防止文件列表与实际目录脱节。

适用场景与决策框架

基于 EndBASIC 的实践经验，Markdown 声明式测试套件最适合以下场景：

• 端到端测试：测试范围跨越编译、执行、输出多个阶段，而非孤立的单元函数
• 执行成本低：测试运行速度快，能够支撑频繁的重跑与迭代
• 输出可文本化：预期结果适合以纯文本形式捕获与比对，而非二进制数据或复杂对象图
• 文档价值优先：测试用例本身具备作为示例文档的价值，需要被非开发者阅读

对于需要精确断言数值边界、依赖复杂 mocking 逻辑或涉及异步超时的场景，传统测试框架仍是更稳妥的选择。

结语

EndBASIC 的 Markdown 测试套件展示了声明式测试的一种可行形态：测试文件不再是代码仓库中的二等公民，而是与文档、示例平起平坐的一等资产。通过将输入输出关系以人类可读的方式固化在 Markdown 中，团队获得了版本控制友好的测试历史、低门槛的维护体验，以及面向 AI 的语义透明性。这一实践的核心启示在于 —— 测试的价值不仅在于捕获回归，更在于作为系统行为的活文档持续演进。

资料来源

• Julio Merino, "A Markdown-based test suite", Blog System/5, 2026-05-17. https://blogsystem5.substack.com/p/markdown-based-test-suite

web