第47章 cargo test

名称

cargo-test — 运行包中的单元测试和集成测试

摘要

cargo test [选项] [测试名称] [-- 测试选项]

描述

编译并执行单元测试、集成测试和文档测试。

测试过滤参数 TESTNAME 以及双破折号（--）后的所有参数，都会传递给测试二进制文件，进而传递给 libtest（rustc 内置的单元测试和微基准测试框架）。如果你同时向 Cargo 和二进制文件传递参数，-- 之后的参数会传给二进制文件，之前的参数则传给 Cargo。关于 libtest 参数的详细信息，请查看 cargo test -- --help 的输出，并参阅 rustc 手册中关于测试工作机制的章节，地址为 https://doc.rust-lang.org/rustc/tests/index.html。

例如，以下命令会过滤出名称中包含 foo 的测试，并在 3 个线程中并行执行它们：

cargo test foo -- --test-threads 3

测试使用 rustc 的 --test 选项进行构建，它会通过链接代码与 libtest 来创建一个特殊的可执行文件。该可执行文件会自动在多个线程中运行所有带有 #[test] 属性的函数。带有 #[bench] 属性的函数也会被运行一次迭代，以验证其功能正常。

如果包包含多个测试目标，每个目标都会编译成前文所述的特殊可执行文件，然后按顺序串行运行。

通过在目标清单设置中配置 harness = false，可以禁用 libtest 测试框架。此时，你的代码需要提供自己的 main 函数来处理测试运行。

文档测试

默认情况下也会运行文档测试，这部分由 rustdoc 处理。它会从库目标的文档注释中提取代码示例，然后执行它们。

与普通测试目标不同，每个代码块会通过 rustc 即时编译为 doctest 可执行文件。这些可执行文件在独立的进程中并行运行。事实上，代码块的编译是受 libtest 控制的测试函数的一部分，因此某些选项（如 --jobs）可能不会生效。请注意，doctest 的这种执行模型并不保证长期稳定，未来可能会发生变化，请勿依赖此机制。

有关编写文档测试的更多信息，请参阅 rustdoc book。

测试的工作目录

运行每个单元和集成测试时，工作目录被设置为测试所属包的根目录。将测试的工作目录设为包根目录，使得测试可以可靠地通过相对路径访问包内的文件，无论 cargo test 是从何处执行的。

对于文档测试，调用 rustdoc 时的工作目录被设置为工作空间根目录，该目录也是 rustdoc 用于编译每个文档测试的目录。运行每个文档测试时，工作目录被设置为测试所属包的根目录，并通过 rustdoc 的 --test-run-directory 选项进行控制。

选项

测试选项

--no-run

仅编译，不运行测试。

--no-fail-fast

无论是否失败，都运行所有测试。如果没有此标志，Cargo 会在第一个可执行文件失败后退出。Rust 测试框架会运行该可执行文件内的所有测试直至完成，此标志仅针对整个可执行文件生效。

包选择

默认情况下，如果没有指定包选择选项，所选的包取决于所选择的 manifest 文件（如果未指定 --manifest-path，则以当前工作目录为准）。如果该 manifest 是一个 workspace 的根，则选中 workspace 的默认成员，否则只选中该 manifest 定义的包。

workspace 的默认成员可以在根 manifest 中通过 workspace.default-members 键显式设置。如果未设置，虚拟 workspace 会包含所有 workspace 成员（等同于传入 --workspace），而非虚拟 workspace 则只包含根 crate 本身。

-p spec…

--package spec…

只测试指定的包。SPEC 格式参见 cargo-pkgid(1)。该参数可多次指定，并支持 *、?、[] 等常见的 Unix glob 模式。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，每个模式都必须用单引号或双引号包裹。

--workspace

测试 workspace 中的所有成员。

--all

--workspace 的废弃别名。

--exclude SPEC…

排除指定的包。必须与 --workspace 参数配合使用。此参数可多次指定，支持 *、? 和 [] 等常见的 Unix 通配符模式。不过，为了防止 Shell 在 Cargo 处理之前意外展开通配符，请务必用单引号或双引号将每个模式括起来。

目标选择

在未指定任何目标选择选项时，cargo test 将构建所选包的以下目标：

• lib — 用于链接二进制文件、示例、集成测试和文档测试
• bins（仅当构建集成测试且所需特性可用时）
• examples — 确保其能编译通过
• 作为单元测试的 lib
• 作为单元测试的 bins
• 集成测试
• lib 目标的文档测试

通过在清单配置中为目标设置 test 标志，可以改变默认行为。将 examples 设为 test = true 会将其作为测试进行构建和运行，并用 libtest 框架替换示例的 main 函数。若不想替换 main 函数，请同时添加 harness = false，此时示例将按原样构建并执行。

将目标设为 test = false 会阻止默认情况下对其进行测试。通过名称指定目标的目标选择选项（例如 --example foo）会忽略 test 标志，始终测试给定的目标。

通过在清单中为库设置 doctest = false，可以禁用库的文档测试。

有关针对各个目标的设置详情，参见 配置目标。

如果选中了集成测试或基准测试，对应的 Binary target 会自动构建。这使得集成测试能够执行该二进制文件，从而验证和测试其行为。当集成测试被构建和运行时，会设置 CARGO_BIN_EXE_<name> 环境变量，以便测试通过 env 宏 或 var 函数 定位可执行文件。

传递 target 选择标志后，只会测试指定的 targets。

请注意，--bin、--example、--test 和 --bench 标志也支持常见的 Unix glob 模式，例如 *、? 和 []。但为了防止 Shell 在 Cargo 处理之前意外展开 glob 模式，必须使用单引号或双引号将每个 glob 模式包围起来。

--lib

测试包的库部分。

--bin name…

测试指定的 binary。该标志可以多次指定，并支持常见的 Unix glob 模式。

--bins

测试所有 binary targets。

--example name…

测试指定的 example。该标志可以多次指定，并支持常见的 Unix glob 模式。

--examples

测试所有 example targets。

--test name…

测试指定的集成测试。此标志可以多次指定，并支持常见的 Unix glob 模式。

--tests

测试所有设置了 test = true manifest 标志的目标。默认包括作为 unittest 构建的库和二进制文件，以及集成测试。注意这也会构建所需的依赖，因此 lib 目标可能会被构建两次（一次作为 unittest，一次作为二进制文件、集成测试等的依赖）。可以通过在 manifest 的目标设置中设置 test 标志来启用或禁用目标。

--bench name…

测试指定的基准测试。此标志可以多次指定，并支持常见的 Unix glob 模式。

--benches

测试所有设置了 bench = true manifest 标志的目标。默认包括作为基准测试构建的库和二进制文件，以及 bench 目标。注意这也会构建所需的依赖，因此 lib 目标可能会被构建两次（一次作为基准测试，一次作为二进制文件、基准测试等的依赖）。可以通过在 manifest 的目标设置中设置 bench 标志来启用或禁用目标。

--all-targets

测试所有目标。等同于同时指定 --lib --bins --tests --benches --examples。

--doc

仅测试库文档。此选项不能与其他 target 选项混用。

Feature 选择

Feature 标志允许你控制启用哪些功能。如果未指定任何 feature 选项，则所有选中的包都会激活 default 功能。

更多详情请参阅 features 文档。

-F features

--features features

由空格或逗号分隔的待激活功能列表。可以使用 package-name/feature-name 语法启用工作区成员的功能。可以多次指定此标志，将启用所有指定的功能。

--all-features

激活所有选中包的全部可用功能。

--no-default-features

不激活选中包的 default 功能。

编译选项

--target triple

为指定的目标架构运行测试。可以多次指定此标志。默认值为主机架构。triple 的通用格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的取值：

• rustc --print target-list 中列出的任何受支持的目标。
• "host-tuple"，内部会被替换为主机的目标三元组。在交叉编译多个 crate 且不指定主机作为目标时（例如共享项目中多人可能在不同主机上操作的 xtask），此功能尤为实用。
• 自定义目标规范的路径。详情请参见 自定义目标查找路径。

也可以通过 build.target 配置值指定。

请注意，指定此标志会使 Cargo 运行在不同模式下，目标产物会放置在独立目录中。更多细节请查阅构建缓存文档。

-r

--release

使用 release 配置文件测试优化后的产物。也可参见 --profile 选项以按名称选择特定配置文件。

--profile name

使用指定的配置文件进行测试。参考文档中有关于配置文件的更多细节。

--timings

输出每次编译的耗时信息，并跟踪随时间变化的并发情况。

构建结束后，会在 target/cargo-timings 目录下生成 cargo-timing.html 文件。如果文件名包含时间戳，也会额外生成一份报告，以便查看之前的运行记录。这些报告仅适合人工阅读，不提供机器可读的耗时数据。

输出选项

--target-dir directory

存放所有生成产物和中间文件的目录。也可以通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置项 来指定。默认为工作区根目录下的 target。

显示选项

默认情况下，Rust 测试框架会隐藏测试执行时的输出，以保证结果清晰易读。如需查看测试输出（例如用于调试），可以在测试二进制后传入 --no-capture：

cargo test -- --no-capture

-v

--verbose

使用详细输出。指定两次可获得“非常详细”的输出，包含依赖警告、构建脚本输出等额外信息。也可以通过 term.verbose 配置项 来指定。

-q

--quiet

不打印 cargo 的日志信息。也可以通过 term.quiet 配置项 来指定。

--color when

控制何时使用彩色输出。可选值：

• auto（默认）：自动检测终端是否支持彩色输出。
• always：总是显示颜色。
• never：从不显示颜色。

也可以通过 term.color 配置项 来指定。

--message-format fmt

诊断信息的输出格式。可多次指定，以逗号分隔。有效值包括：

• human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
• short：输出简短的人类可读文本信息。与 human 和 json 冲突。
• json：向标准输出（stdout）发送 JSON 格式信息。详见参考文档。与 human 和 short 冲突。
• json-diagnostic-short：确保 JSON 信息中的 rendered 字段包含 rustc 的“简短”渲染结果。不能与 human 或 short 一起使用。
• json-diagnostic-rendered-ansi：确保 JSON 信息中的 rendered 字段包含嵌入的 ANSI 颜色代码，以符合 rustc 的默认配色方案。不能与 human 或 short 一起使用。
• json-render-diagnostics：指示 Cargo 不在输出的 JSON 信息中包含 rustc 的诊断信息，而是由 Cargo 自行渲染来自 rustc 的 JSON 诊断信息。Cargo 自身的 JSON 诊断信息以及来自 rustc 的其他信息仍会正常输出。不能与 human 或 short 一起使用。

Manifest 选项

--manifest-path path

Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录或其父目录中查找 Cargo.toml 文件。

--ignore-rust-version

忽略包中的 rust-version 声明。

--locked

断言使用的依赖项及其版本与最初生成 Cargo.lock 文件时完全一致。如果发生以下任一情况，Cargo 将报错退出：

• 锁文件缺失。
• 由于依赖解析结果不同，Cargo 试图修改锁文件。

该选项适用于 CI 流水线等需要确定性构建的环境。

--offline

阻止 Cargo 因任何原因访问网络。如果不加此标志，Cargo 在需要访问网络但网络不可用时将报错停止；加上此标志后，Cargo 将在可能情况下尝试离线继续执行。

请注意，这可能导致与在线模式不同的依赖解析结果。Cargo 将仅限于使用本地已下载的 crate，即使本地索引副本显示存在更新版本。请参阅 cargo-fetch(1) 命令，在离线前下载依赖。

也可以通过配置项 net.offline 配置值 指定。

--frozen

等同于同时指定 --locked 和 --offline。

通用选项

+toolchain

如果 Cargo 是通过 rustup 安装的，且 cargo 的第一个参数以 + 开头，则该参数将被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖机制的更多信息，请参阅 rustup 文档。

--config KEY=VALUE 或 PATH

覆盖 Cargo 配置项。参数需为 TOML 语法的 KEY=VALUE 形式，或提供一个额外配置文件的路径。此标志可以多次指定。详见命令行覆盖一节。

-C PATH

在执行任何指定操作前切换当前工作目录。这会影响 Cargo 默认查找项目清单文件（Cargo.toml）的位置，以及搜索 .cargo/config.toml 的目录等。该选项必须出现在命令名之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly 渠道可用，且需要 -Z unstable-options 标志来启用（参见 #10098）。

-h

--help

打印帮助信息。

-Z flag

Cargo 的不稳定（仅 nightly）标志。运行 cargo -Z help 查看详情。

其他选项

--jobs 参数只影响测试可执行文件的构建，不影响运行测试时使用的线程数。Rust 测试框架自带控制线程数的选项：

cargo test -j 2 -- --test-threads=2

-j N

--jobs N

并行作业的数量。也可以通过 build.jobs 配置项 指定。默认值为逻辑 CPU 数量。若为负数，则将并行作业的最大数量设为逻辑 CPU 数量加上该数值。若提供字符串 default，则恢复为默认值。不得为 0。

--future-incompat-report

显示执行该命令时产生的任何未来不兼容警告的报告。

参见 cargo-report(1)

虽然 cargo test 涉及编译，但它不提供 --keep-going 标志。使用 --no-fail-fast 可尽可能多地运行测试，而不在首个失败处停止。若要尽可能多地“编译”测试，使用 --tests 单独构建测试二进制文件。例如：

cargo build --tests --keep-going
cargo test --tests --no-fail-fast

环境变量

关于 Cargo 读取的环境变量详情，参见参考文档。

退出状态

• 0：Cargo 成功。
• 101：Cargo 未能完成。

示例

1. 执行当前包的所有单元和集成测试：

   cargo test
   

2. 仅运行名称匹配过滤器字符串的测试：

   cargo test name_filter
   

3. 仅运行特定集成测试中的某个具体测试：

   cargo test --test int_test_name -- modname::test_name
   

另请参阅

cargo(1)、cargo-bench(1)、测试类型、如何编写测试