Cargo test 怎么只运行文档测试

如果只想检查 Rust 文档注释里的代码示例，不必重复运行普通单元测试和集成测试。进入包含 Cargo.toml 的项目目录后，使用 cargo test --doc；它会把目标缩小到库目标的文档测试。工作区场景再配合 --workspace 或 -p，就能控制要检查哪些包。

官方地址：https://doc.rust-lang.org/cargo/commands/cargo-test.html

先分清 cargo test 默认会做什么

Cargo 的 test 命令默认可以编译并执行单元测试、集成测试和文档测试。文档测试由 rustdoc 从库目标的文档注释中提取代码块，再为代码块编译测试程序并执行。因此，文档示例接入 CI 后，单独跑 doctest 能让检查范围更清楚。

--doc 是目标选择参数，含义是“只测试库的文档”，不能和其它目标选择参数混用。它不是把普通测试按名字过滤，也不是让已有单元测试只保留某一类。

在项目入口选择文档测试

先把终端工作目录放到项目根目录，也就是能找到 Cargo.toml 的位置。然后执行最小命令：

# 在当前包中只编译并运行库文档里的 doctest
cargo test --doc

这里的 --doc 负责目标选择，前面的 cargo test 仍然使用 Cargo 的测试配置和依赖解析。命令成功时，输出会出现文档测试对应的编译或运行信息；如果示例代码编译失败，Cargo 会把失败位置和 rustdoc 编译错误返回出来。

在工作区里只选需要的包

如果根目录是 Cargo 工作区，先决定要检查全部成员，还是只检查其中一个成员。对整个工作区使用：

# 对当前工作区选定的成员只运行库文档测试
cargo test --workspace --doc

如果只想检查一个包，把包名替换成 Cargo.toml 中的真实名称：

# 只检查指定工作区成员的库文档；package_name 换成实际包名
cargo test --workspace -p package_name --doc

--workspace 和 -p 解决的是包选择问题，--doc 解决的是测试目标问题。三者不要混成一个“过滤测试名”的概念：如果你需要筛选普通测试函数，应使用另一套 libtest 参数，那已经超出本文的文档测试范围。

用可见状态判断范围是否正确

只运行文档测试时，可以按下面三点阅读输出和命令范围：

1. 命令中明确存在 --doc，说明目标选择已经指向库文档。
2. 文档代码块被单独编译和执行，错误通常来自 rustdoc 提取出的示例，而不是普通 #[test] 函数。
3. 命令没有同时指定 --lib、--tests、--example 等其它目标选项。

需要留意，文档测试的工作目录有自己的规则：调用 rustdoc 时使用工作区根目录，实际运行每个文档测试时又会回到所属包的根目录。文档示例如果读取相对路径，不要只凭当前终端所在目录猜测结果。

遇到空结果时先看包和目标

执行后没有看到预期的文档测试，不要立刻把它判断成 Cargo 没有工作，可以按范围逐项排查：

如果只是想验证文档示例，建议先保持命令最小，再逐步增加 --workspace 或 -p。这样更容易知道变化来自测试目标，还是来自包范围。

几个容易混淆的问题

cargo test --doc 会运行普通单元测试吗？

不会。它的目标是库文档测试；普通单元测试和集成测试需要其它目标选择或默认测试行为。

只有二进制包时能不能用 --doc？

本文命令针对库目标的文档。如果包没有可测试的库文档，应该先确认目标类型和文档注释位置，而不是用 --doc 去替代二进制测试。

可以把 --doc 和 --lib 一起写吗？

不建议这样组合。Cargo 文档说明 --doc 不能和其它目标选择参数混用；需要文档测试时保留 --doc，需要普通库单元测试时再单独执行相应命令。

总结一下：只检查文档示例就从 cargo test --doc 开始；工作区用 --workspace，单成员用 -p。看到异常时先确认库目标、包选择和 doctest 设置，再判断是范围没有选中，还是文档代码本身编译失败。