cargo-test(1)

名称

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

概要

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

描述

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

测试过滤参数 TESTNAME 以及紧随两个破折号 (--) 之后的所有参数都被传递给测试二进制文件，进而传递给 libtest（rustc 内置的单元测试和微基准测试框架）。如果您同时向 Cargo 和二进制文件传递参数，-- 之后的参数将传递给二进制文件，-- 之前的参数则传递给 Cargo。有关 libtest 参数的详细信息，请参阅 cargo test -- --help 的输出，并在 rustc 图书中查看有关测试工作原理的章节：https://doc.rust-lang.net.cn/rustc/tests/index.html。

例如，这将过滤名称中包含 foo 的测试并在 3 个线程中并行运行它们

cargo test foo -- --test-threads 3

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

如果包包含多个测试目标，则每个目标都会如上所述编译成一个特殊的执行文件，然后依次运行。

可以通过在目标清单设置中设置 harness = false 来禁用 libtest 测试运行器（harness），在这种情况下，您的代码需要提供自己的 main 函数来处理测试运行。

文档测试

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

与普通测试目标不同，每个代码块都会在运行时通过 rustc 编译成一个文档测试执行文件。这些执行文件在单独的进程中并行运行。代码块的编译实际上是 libtest 控制的测试函数的一部分，因此某些选项（例如 --jobs）可能不会生效。请注意，文档测试的这种执行模型不保证不变，将来可能会更改；请注意不要依赖它。

有关如何编写文档测试的更多信息，请参阅rustdoc 图书。

测试的工作目录

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

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

选项

测试选项

--no-run
只编译，不运行测试。
--no-fail-fast
无论测试是否失败，都运行所有测试。如果没有此标志，Cargo 会在第一个可执行文件失败后退出。Rust 测试运行器会运行可执行文件内的所有测试直至完成，此标志仅适用于整个可执行文件。

包选择

默认情况下，如果没有给出包选择选项，选择的包取决于所选的清单文件（如果未给出 --manifest-path，则基于当前工作目录）。如果清单是工作区的根目录，则选择工作区的默认成员，否则只选择清单定义的包。

工作区的默认成员可以在根清单中通过 workspace.default-members 键显式设置。如果未设置此项，虚拟工作区将包含所有工作区成员（相当于传递 --workspace），非虚拟工作区将只包含根 crate 本身。

-p 规格…
--package 规格…
仅测试指定的包。有关 SPEC 格式，请参阅cargo-pkgid(1)。此标志可以指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为避免您的 shell 在 Cargo 处理 glob 模式之前意外展开它们，您必须在每个模式周围使用单引号或双引号。
--workspace
测试工作区中的所有成员。
--all
--workspace 的已弃用别名。
--exclude 规格…
排除指定的包。必须与 --workspace 标志结合使用。此标志可以指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为避免您的 shell 在 Cargo 处理 glob 模式之前意外展开它们，您必须在每个模式周围使用单引号或双引号。

目标选择

如果未给出目标选择选项，cargo test 将构建所选包的以下目标

  • lib — 用于与二进制文件、示例、集成测试和文档测试链接
  • bins（仅在构建集成测试且必需功能可用时）
  • examples — 确保它们能编译
  • lib 作为单元测试
  • bins 作为单元测试
  • 集成测试
  • lib 目标的文档测试

可以通过在清单设置中为目标设置 test 标志来更改默认行为。将示例的 test 设置为 true 将构建并运行示例作为测试，用 libtest 运行器替换示例的 main 函数。如果您不想替换 main 函数，同时包含 harness = false，在这种情况下，示例将按原样构建和执行。

将目标的 test 设置为 false 将阻止它们在默认情况下被测试。按名称指定目标的选项（例如 --example foo）会忽略 test 标志，并且总是会测试给定的目标。

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

有关每个目标设置的更多信息，请参阅配置目标。

如果选择了集成测试或基准测试进行测试，二进制目标会自动构建。这允许集成测试执行二进制文件来演练和测试其行为。集成测试构建时会设置 CARGO_BIN_EXE_<name> 环境变量，以便它可以使用 env 宏来定位可执行文件。

传递目标选择标志将仅测试指定的目标。

请注意，--bin、--example、--test 和 --bench 标志也支持常见的 Unix glob 模式，如 *、? 和 []。但是，为避免您的 shell 在 Cargo 处理 glob 模式之前意外展开它们，您必须在每个 glob 模式周围使用单引号或双引号。

--lib
测试包的库。
--bin 名称…
测试指定的二进制文件。此标志可以指定多次，并支持常见的 Unix glob 模式。
--bins
测试所有二进制目标。
--example 名称…
测试指定的示例。此标志可以指定多次，并支持常见的 Unix glob 模式。
--examples
测试所有示例目标。
--test 名称…
测试指定的集成测试。此标志可以指定多次，并支持常见的 Unix glob 模式。
--tests
测试所有清单中设置了 test = true 标志的目标。默认情况下，这包括作为单元测试构建的库和二进制文件，以及集成测试。请注意，这也会构建任何必需的依赖项，因此 lib 目标可能会构建两次（一次作为单元测试，一次作为二进制文件、集成测试等的依赖项）。可以通过在目标的清单设置中设置 test 标志来启用或禁用目标。
--bench 名称…
测试指定的基准测试。此标志可以指定多次，并支持常见的 Unix glob 模式。
--benches
测试所有清单中设置了 bench = true 标志的目标。默认情况下，这包括作为基准测试构建的库和二进制文件，以及基准测试目标。请注意，这也会构建任何必需的依赖项，因此 lib 目标可能会构建两次（一次作为基准测试，一次作为二进制文件、基准测试等的依赖项）。可以通过在目标的清单设置中设置 bench 标志来启用或禁用目标。
--all-targets
测试所有目标。这相当于指定 --lib --bins --tests --benches --examples。
--doc
仅测试库的文档。此选项不能与其他目标选项混合使用。

功能选择

功能标志允许您控制启用哪些功能。如果没有给出功能选项，则为每个选定的包激活 default 功能。

有关详细信息，请参阅功能文档。

-F 功能
--features 功能
以空格或逗号分隔的要激活的功能列表。工作区成员的功能可以使用 包名/功能名 语法启用。此标志可以指定多次，这将启用所有指定的功能。
--all-features
激活所有选定包的所有可用功能。
--no-default-features
不激活选定包的 default 功能。

编译选项

--target 三元组
为给定的架构进行测试。默认为主机架构。三元组的一般格式是 <arch><sub>-<vendor>-<sys>-<abi>。运行 rustc --print target-list 查看支持的目标列表。此标志可以指定多次。

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

请注意，指定此标志会使 Cargo 在不同的模式下运行，目标工件会被放置在单独的目录中。有关详细信息，请参阅构建缓存文档。

-r
--release
使用 release 配置文件测试优化后的工件。另请参阅 --profile 选项，用于按名称选择特定的配置文件。
--profile 名称
使用给定的配置文件进行测试。有关配置文件的更多详细信息，请参阅参考。
--timings=格式
输出关于每个编译耗时以及随时间跟踪并发信息的信息。接受一个可选的逗号分隔的输出格式列表；不带参数的 --timings 将默认使用 --timings=html。指定输出格式（而非默认格式）是不稳定的，需要 -Zunstable-options。有效的输出格式：

  • html（不稳定，需要 -Zunstable-options）：将人类可读的 cargo-timing.html 文件写入 target/cargo-timings 目录，其中包含编译报告。如果您想查看较早的运行，也会将报告写入同一目录，文件名带有时间戳。HTML 输出仅适用于人类阅读，不提供机器可读的计时数据。
  • json（不稳定，需要 -Zunstable-options）：输出机器可读的 JSON 格式的计时信息。

输出选项

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

显示选项

默认情况下，Rust 测试运行器会隐藏测试执行的输出，以保持结果的可读性。可以通过向测试二进制文件传递 --nocapture 来恢复测试输出（例如，用于调试）。

cargo test -- --nocapture
-v
--verbose
使用详细输出。可以指定两次以获得“非常详细”的输出，其中包括依赖项警告和构建脚本输出等额外信息。也可以通过 term.verbose 配置值指定。
-q
--quiet
不打印 cargo 日志消息。也可以通过 term.quiet 配置值指定。
--color 何时
控制何时使用彩色输出。有效值：

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

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

--message-format 格式
诊断消息的输出格式。可以指定多次，由逗号分隔的值组成。有效值：

  • human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
  • short：输出更短的、人类可读的文本消息。与 human 和 json 冲突。
  • json：向标准输出发送 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-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。
--lockfile-path 路径
将锁定文件的路径从默认路径（<工作区根目录>/Cargo.lock）更改为 路径。路径 必须以 Cargo.lock 结尾（例如 --lockfile-path /tmp/temporary-lockfile/Cargo.lock）。请注意，提供 --lockfile-path 将忽略默认路径下现有的锁定文件，而是使用指定 路径 下的锁定文件，如果不存在，则将新的锁定文件写入提供的 路径。此标志可用于在只读目录中运行大多数命令，将锁定文件写入提供的 路径。

此选项仅在每夜构建版本（nightly channel）中可用，并且需要 -Z unstable-options 标志才能启用（参见 #14421）。

通用选项

+工具链
如果 Cargo 是通过 rustup 安装的，并且 cargo 的第一个参数以 + 开头，它将被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖工作原理的更多信息，请参阅 rustup 文档。
--config 键=值 或 路径
覆盖 Cargo 配置值。参数应采用 键=值 的 TOML 语法，或提供额外配置文件的路径。此标志可以指定多次。有关详细信息，请参阅命令行覆盖章节。
-C 路径
在执行任何指定操作之前更改当前工作目录。这会影响 Cargo 默认查找项目清单 (Cargo.toml) 的位置，以及搜索发现 .cargo/config.toml 等文件的目录。此选项必须出现在命令名称之前，例如 cargo -C path/to/my-project build。

此选项仅在每夜构建版本（nightly channel）中可用，并且需要 -Z unstable-options 标志才能启用（参见 #10098）。

-h
--help
打印帮助信息。
-Z 标志
Cargo 的不稳定（仅限每夜构建版本）标志。运行 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), 测试类型, 如何编写测试