Rust 测试生态的"机器可读"未来:libtest JSON 程序化输出 eRFC 深度解读
Rust 测试生态的"机器可读"未来:libtest JSON 程序化输出 eRFC 深度解读
本指南以 Rust RFC 仓库中的 libtest JSON 输出 eRFC 为核心,系统讲解 Rust 测试框架 libtest 的程序化(JSON)输出为何需要稳定化、官方规划的实验路径、功能对等性要求与格式演进考量,并结合仓库内的 Testing 团队 RFC、自定义测试框架 eRFC 以及历年 Project Goals 文档,还原这一从"实验"走向"稳定化"的完整技术路线。读完本文,你将理解 cargo test -- --format json 背后的设计约束、测试 runner 与测试 harness 的职责划分,以及 cargo、IDE、CI 工具如何受益于稳定的程序化输出。
1. 背景:libtest 与"程序化输出"的困境
1.1 libtest 是什么
libtest 是 cargo 项目中默认使用的测试 harness(test harness)。它的职责包括:
- 提供 cargo 调用测试二进制所需的 CLI 接口;
- 枚举并运行二进制中被发现(discover)的测试;
- 随 rustup 一起分发,并享有与标准库相同的兼容性保证(compatibility guarantees)。
所谓"程序化输出"(programmatic output),指 libtest 以结构化格式(如 JSON)输出测试运行结果,而不是只输出人类可读的文本。这样的输出可以被 cargo、IDE、CI 工具、自定义测试 runner 稳定地解析和使用。
1.2 Rust 1.70 的转折点:从"能用"到"必须 nightly"
本 eRFC 的关键动机来自一个真实的历史事件:在 Rust 1.70 之前,任何人都可以通过 --format json 获得 libtest 的 JSON 输出,尽管该功能当时并不稳定。Rust 1.70 修复了一个 bug,使得 cargo test -- --format json 这类不稳定测试特性与其他不稳定特性一样,必须使用 nightly 工具链才能启用。
这一修复在社区引发了广泛反响(本 eRFC 引用了相关讨论作为佐证),因为它恰好暴露了一个事实:有大量编辑器/IDE 与 CI 相关工具早已依赖此前"碰巧可用"的行为来程序化获取测试数据。该事件同时印证了 Testing 团队 RFC 中的观察:JSON、JUnit 等额外测试输出格式在 Stable Rust 上可用的请求由来已久,但 5 年间几乎没有进展。
换句话说,问题不在于"要不要 JSON 输出",而在于"既然生态已经依赖它,就应该把它以稳定、有保障的方式正式提供给所有人"。
2. 动机:Cargo 与工具链的程序化输出需求
2.1 Cargo 能从程序化输出中受益的场景
本 eRFC 详细列举了 cargo 在测试交互上的长期痛点,这些正是稳定化程序化输出的核心驱动力:
| 痛点 | 说明 |
|---|---|
| 并行运行测试二进制 | 希望像 cargo nextest 那样并行运行多个测试二进制 |
| 缺少跨二进制汇总 | 多测试二进制下没有统一的总结视图 |
| 测试输出噪音大 | 人类可读输出冗长,干扰关键信息 |
| 命令行交互令人困惑 | 测试相关的 CLI 交互设计混乱 |
| 过滤器不匹配时提示差 | 测试名过滤无匹配时给出的消息不够友好 |
| 更智能的测试执行顺序 | 希望按依赖/耗时等条件优化执行顺序 |
| JUnit 输出错误 | 运行多个测试二进制时 JUnit 输出不正确 |
| 测试二进制异常退出无感知 | 测试二进制非正常退出时缺少失败反馈 |
2.2 职责转移:从 harness 到 runner
大多数上述问题,本质上都涉及将职责从测试 harness(test harness)转移到测试 runner(test runner)。这一转移带来两个重要的生态效应:
- 让自定义测试 runner(如
cargo nextest)更强大:它们能获得更多可操作的结构化信息,从而可以做并行调度、智能排序、精确过滤等更高级的实验; - 降低自定义测试 harness 的准入门槛:由于 UI(人类可读输出)职责被转移到
cargo test一侧,类似libtest-mimic这样的自定义 harness 只需关注测试的收集与执行,不必再费力模拟 libtest 的输出格式。
这也是本 eRFC 将"自定义测试 harness"置于讨论中心的原因:它们既有现实需求(见 4.2 节清单),也是检验新格式扩展能力的重要试金石。
3. 实验目标与预期成果
3.1 直接成果
本 eRFC(实验性 RFC,eRFC)规划的预期成果有两条:
- 更新 libtest 的不稳定输出:针对现有
--format json不稳定输出进行迭代改进; - 向 T-libs-api(Library API 团队)提交稳定化请求:走该团队自己选择的流程,完成程序化输出的稳定化。
3.2 期望的额外成果
此外,还希望推动两项 cargo 侧的变更提案(change proposal):
- 由 T-cargo 提出
cargo test与cargo bench的 UX 改进提案,让 cargo 在程序化输出之上构建自己的用户体验; - 由 T-cargo 提出另一份变更提案,允许自定义测试 harness 的用户选择加入(opt-in) 新的 UX,即通过程序化输出协议接入。
值得一提的是,本 eRFC 明确承认:虽然"有演进计划"能减轻格式设计的压力,但仍需对格式本身做必要的尽职调查,确保它能在预期用途下良好工作。
4. 实验路径:四步验证计划
4.1 具体步骤
本 eRFC 给出了验证一个输出格式提案的粗略计划(rough plan),共四步:
- 创建实验性测试 harness:让每个
--format <mode>都成为公共内部serde结构之上的一层"皮肤"(skin),在小规模上模拟未来 libtest 与 cargo 的关系,从而加快迭代; - 将 libtest 迁移到这套提议的接口;
- 为 cargo 添加实验性支持,使其能通过不稳定的程序化输出与测试二进制交互;
- 编写稳定化报告:向 T-libs-api 提交程序化输出稳定化报告,并向 cargo 提交一份 RFC,允许自定义测试 harness 选择加入这一新协议。
4.2 功能对等性要求
实验性测试 harness 被期望与 libtest 功能对等(functional parity),至少包括:
- 忽略测试(ignored tests)的支持;
- 测试的并行运行;
- bench 同时既是 bench 又是 test(即 bench 可以被当作测试运行);
- 测试发现(test discovery)。
4.3 跨生态的评估清单
为确保格式具备足够的可扩展性,设计需要对照不同生态的测试 runner 能力进行评估,包括:
- 在同一个格式之上实现不同模式的能力,既包括测试运行模式,也包括
--list(仅列出测试)模式; - 并行运行多个测试 harness 的能力;
- 支持一次测试产生多个失败(multi-failure)的能力,例如 googletest 的
expect_that风格断言; - bench 支持;
- 静态与动态的参数化测试 / 测试夹具(如 rstest);
- 静态与动态的测试跳过(如 cargo 的
#[test]属性机制); - 测试标记(test markers),类似 pytest 的标记(mark)功能;
- doctests;
- 测试位置信息(供 IDE 使用);
- 与测试相关的指标收集:耗时(elapsed time)、临时目录大小(temp dir sizes)、RNG seed 等。
重要警告(原文措辞):这并不意味着上述能力都会在初次稳定化时全部支持,而只是说明设计团队对"格式能够支持它们"有信心。换句话说,评估目标是"格式的可扩展性",而非"首版功能清单"。
5. 格式演进与自定义测试 harness 的生态考量
5.1 演进策略与编译时负担
本 eRFC 特别指出需要评估"如何支持格式的持续演进",并强调一个关键权衡:自定义测试 harness 承担编译时负担(compile-time burden)的大小,将直接影响人们是否愿意引入它们——因为 libtest 如今是随工具链预构建(pre-built)提供的,几乎零负担。
如果新格式给自定义 harness 带来过重的编译时成本,将显著抑制生态活力。
5.2 已有的自定义测试 harness 生态
自定义测试 harness 之所以重要,是因为今天已存在大量此类工具,它们有的直接基于 libtest,有的则是"借壳"运行在 libtest 之上。本 eRFC 列举的代表性项目包括:
- libtest-mimic:以兼容 libtest 方式运行测试的自定义 harness;
- criterion 与 divan:基准测试框架;
- cargo-test-support:cargo 自身的测试支撑库;
- rstest:参数化测试与测试夹具;
- trybuild:编译期测试工具。
同时,由于 libtest 本身的兼容性保证意味着其演进节奏较慢,通过自定义测试 harness 探索新想法反而更容易——这正是本 eRFC 强调自定义 harness 价值的另一层原因。相关背景可参见仓库内的 自定义测试框架 eRFC,该文档详述了自定义测试框架的动机、Cargo.toml 集成方式与 proc macro 设计备选方案。
6. 既有格式的参考与讨论资源
6.1 先例:既有测试输出格式
在设计新格式之前,值得考察既有生态中的成熟输出格式:
- JUnit:Java 生态事实标准的 XML 测试报告格式,被大量 CI 系统解析;
- subunit:Python 社区提出的流式测试协议,支持增量输出与跨进程合并;
- TAP(Test Anything Protocol):起源于 Perl 社区、被众多语言采纳的文本协议。
这些格式构成了"程序化测试输出"领域的先行者,也是评估新格式表达能力与扩展性时的对照样本。
6.2 对 libtest 既有格式的批评意见
本 eRFC 的参考级说明(Reference-level explanation)部分汇集了社区对 libtest 现有 JSON 格式的公开评论,可归纳为以下设计教训:
- 格式过于复杂:难以理解与实现;
- bench 支持不足:bench 相关输出需要更多关照;
type字段过载:单个字段承担了过多语义;- 缺少 suite/child 关系:无法表达测试套件与其子测试的层级关系;
- 缺少 suite 名称:导致 cargo 难以直接使用程序化输出;
- 格式规范不充分:underspecified,解析方难以达成一致;
- 缺少 ignored 原因(该问题后续已有解决进展);
- 缺少
rendered字段:工具难以同时拿到结构化数据与人类可读文本。
这些批评为"新格式该设计什么、避免什么"提供了直接依据,也是 4.3 节评估清单的源头之一。
7. 现状追踪:从 eRFC 到项目目标
本 eRFC 并非停留在纸面。在 RFC 仓库的历年项目目标文档中,可以追踪到这一实验被正式纳入 Rust 项目路线图并持续推进的轨迹:
- 2025H1 项目目标 中列有目标 "Finish the libtest json output experiment"(完成 libtest JSON 输出实验),由 Ed Page 负责,涉及 cargo、libs-api、testing-devex 三个团队;
- 2025H2 项目目标 中该目标延续,依旧由 Ed Page 牵头;
- 2026 项目目标 中该目标仍被列为 testing-devex 团队的小型目标(Small 级),并注明"设计讨论与评审"仍在进行。
这说明:libtest JSON 程序化输出从 eRFC 提出的"实验路径",已演变为 Rust 项目正式的持续目标,其最终形态仍在设计评审中逐步收敛。
8. 未来展望:自定义测试 harness 的一等公民化
8.1 减轻负担后的想象空间
本 eRFC 在"未来可能性"一节指出:一旦自定义测试 harness 承担的负担减轻(受益于职责向测试 runner 的转移),社区就能更轻松地探索如何让它们成为一等公民(first-class)体验。
8.2 相关参考
该方向与两项既有工作直接相关:
- 仓库内的 eRFC 2318:Custom Test Frameworks:为自定义测试框架铺路的实验性 RFC,讨论了
Cargo.toml中[testing.framework]/[[testing.frameworks]]配置、proc macro 生成main()、输出格式标准化等议题; - Ed Page 的博客文章《Iterating on Test》:记录了测试体验迭代的思考脉络(本 eRFC 原文引用,未在本仓库内)。
9. 总结
本 eRFC 围绕一个朴素但关键的事实展开:Rust 生态的工具链早已依赖 libtest 的程序化输出,但该能力迟迟未能稳定化。其价值在于:
- 系统梳理了 cargo、IDE、CI 工具对程序化输出的真实需求与既有痛点;
- 提出了一个"小步验证、逐步迁移、最终稳定化"的四步实验路径,并明确了功能对等性要求;
- 给出了跨生态的格式评估清单,为格式设计划定了能力边界与扩展性目标;
- 明确了自定义测试 harness 在整个生态中的战略地位,以及格式演进对它们的编译时负担影响。
对 Rust 测试工具链的开发者、cargo test 的使用者以及 CI/IDE 集成方案的设计者而言,这份 eRFC 既是一份现状诊断书,也是一份路线图——它揭示了"人类可读输出"与"机器可读输出"之间的分工重构,以及这一重构如何为 cargo nextest 式的并行 runner、rstest 式的参数化测试、IDE 测试浏览等能力打开空间。