Rust 测试生态的"机器可读"未来:libtest JSON 程序化输出 eRFC 深度解读

原创2026-10-15 13:11:091,634 阅读
文章标签:文档

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)。这一转移带来两个重要的生态效应:

  1. 让自定义测试 runner(如 cargo nextest)更强大:它们能获得更多可操作的结构化信息,从而可以做并行调度、智能排序、精确过滤等更高级的实验;
  2. 降低自定义测试 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),共四步:

  1. 创建实验性测试 harness:让每个 --format <mode> 都成为公共内部 serde 结构之上的一层"皮肤"(skin),在小规模上模拟未来 libtest 与 cargo 的关系,从而加快迭代;
  2. 将 libtest 迁移到这套提议的接口;
  3. 为 cargo 添加实验性支持,使其能通过不稳定的程序化输出与测试二进制交互;
  4. 编写稳定化报告:向 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 的程序化输出,但该能力迟迟未能稳定化。其价值在于:

  1. 系统梳理了 cargo、IDE、CI 工具对程序化输出的真实需求与既有痛点;
  2. 提出了一个"小步验证、逐步迁移、最终稳定化"的四步实验路径,并明确了功能对等性要求;
  3. 给出了跨生态的格式评估清单,为格式设计划定了能力边界与扩展性目标;
  4. 明确了自定义测试 harness 在整个生态中的战略地位,以及格式演进对它们的编译时负担影响。

对 Rust 测试工具链的开发者、cargo test 的使用者以及 CI/IDE 集成方案的设计者而言,这份 eRFC 既是一份现状诊断书,也是一份路线图——它揭示了"人类可读输出"与"机器可读输出"之间的分工重构,以及这一重构如何为 cargo nextest 式的并行 runner、rstest 式的参数化测试、IDE 测试浏览等能力打开空间。

登录后查看全文
rfcs