测试
rustc
具有内置的功能,用于构建和运行箱子的测试。有关编写和运行测试的更多信息,请参阅 Rust 编程语言手册的 测试章节。
测试被编写为带有 #[test]
属性 的自由函数。例如
#[test]
fn it_works() {
assert_eq!(2 + 2, 4);
}
如果测试在没有错误的情况下返回,则测试“通过”。如果测试 恐慌,或者返回一个类型(例如 Result
)它实现了 Termination
特性,并且具有非零值,则测试“失败”。
通过将 --test
选项 传递给 rustc
,编译器将以特殊模式构建箱子,以构建一个可执行文件,该可执行文件将运行箱子中的测试。--test
标志将进行以下更改
- 箱子将被构建为一个
bin
箱子类型,强制它成为一个可执行文件。 - 将可执行文件与
libtest
链接,libtest
是标准库的一部分,用于处理运行测试。 - 合成一个
main
函数,它将处理命令行参数并运行测试。这个新的main
函数将替换任何现有的main
函数作为可执行文件的入口点,尽管现有的main
仍然会被编译。 - 启用
test
cfg 选项,它允许您的代码使用条件编译来检测它是否正在被构建为测试。 - 启用使用
test
和bench
属性注释的函数的构建,这些函数将由测试工具运行。
创建可执行文件后,您可以运行它来执行测试并接收有关通过和失败的报告。如果您使用 Cargo 来管理您的项目,它有一个内置的 cargo test
命令,它会自动处理所有这些操作。输出示例如下
running 4 tests
test it_works ... ok
test check_valid_args ... ok
test invalid_characters ... ok
test walks_the_dog ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
注意:测试必须使用
unwind
恐慌策略 构建。这是因为所有测试都在同一个进程中运行,并且它们旨在捕获恐慌,而使用abort
策略则无法做到这一点。有关通过在单独的进程中生成测试来实验性支持abort
策略的更多信息,请参阅不稳定的-Z panic-abort-tests
选项。
测试属性
测试使用自由函数上的属性来指示。以下属性用于测试,有关更多详细信息,请参阅链接的文档
#[test]
— 指示一个函数是一个要运行的测试。#[bench]
— 指示一个函数是一个要运行的基准测试。基准测试目前不稳定,并且仅在 nightly 通道中可用,有关更多详细信息,请参阅 不稳定文档。#[should_panic]
— 指示测试函数只有在函数 恐慌 时才会通过。#[ignore]
— 指示测试函数将被编译,但默认情况下不会运行。请参阅--ignored
和--include-ignored
选项以运行这些测试。
CLI 参数
libtest 工具具有多个命令行参数来控制其行为。
注意:当使用
cargo test
运行时,libtest CLI 参数必须在--
参数之后传递,以区分 Cargo 的标志和工具的标志。例如:cargo test -- --nocapture
过滤器
位置参数(没有 -
前缀的参数)被视为过滤器,它将仅运行名称与这些字符串之一匹配的测试。过滤器将匹配在测试函数的完整路径中找到的任何子字符串。例如,如果测试函数 it_works
位于模块 utils::paths::tests
中,那么任何过滤器 works
、path
、utils::
或 utils::paths::tests::it_works
都将匹配该测试。
请参阅 选择选项,以了解有关控制运行哪些测试的更多选项。
操作选项
以下选项执行除运行测试之外的不同操作。
--list
打印所有测试和基准测试的列表。不运行任何测试。可以使用 过滤器 来仅列出匹配的测试。
-h
, --help
显示使用信息和命令行选项。
选择选项
以下选项更改测试的选择方式。
--test
这是默认模式,所有测试都将运行,并且所有基准测试都将运行,但只有一次迭代(以确保基准测试有效,而无需花费时间实际执行基准测试)。这可以与 --bench
标志结合使用,以同时运行测试和执行完整的基准测试。
--bench
这以一种模式运行,其中测试被忽略,并且只运行基准测试。这可以与 --test
标志结合使用,以同时运行基准测试和测试。
--exact
这强制 过滤器 精确匹配测试的完整路径。例如,如果测试 it_works
位于模块 utils::paths::tests
中,那么只有字符串 utils::paths::tests::it_works
将匹配该测试。
--skip
FILTER
跳过名称包含给定 FILTER 字符串的任何测试。此标志可以多次传递。
--ignored
仅运行使用 ignore
属性 标记的测试。
--include-ignored
同时运行 忽略的 和未忽略的测试。
--exclude-should-panic
排除使用 should_panic
属性 标记的测试。
⚠️ 🚧 此选项 不稳定,并且需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #82348。
执行选项
以下选项影响测试的执行方式。
--test-threads
NUM_THREADS
设置用于并行运行测试的线程数。默认情况下,使用 available_parallelism
所指示的硬件上可用的并发量。
这也可以使用 RUST_TEST_THREADS
环境变量指定。
--force-run-in-process
强制测试在使用 abort
恐慌策略 时在一个进程中运行。
⚠️ 🚧 这仅适用于不稳定的 -Z panic-abort-tests
选项,并且需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #67650。
--ensure-time
⚠️ 🚧 此选项 不稳定,并且需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #64888 和 不稳定文档。
--shuffle
以随机顺序运行测试,而不是默认的字母顺序。
这也可以通过将 RUST_TEST_SHUFFLE
环境变量设置为除 0
之外的任何值来指定。
输出的随机数生成器种子可以传递给 --shuffle-seed
以再次以相同的顺序运行测试。
请注意,--shuffle
不会影响测试是否并行运行。要按随机顺序依次运行测试,请使用 --shuffle --test-threads 1
。
⚠️ 🚧 此选项为 不稳定,需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #89583。
--shuffle-seed
SEED
与 --shuffle
相似,但使用 SEED 对随机数生成器进行播种。因此,两次使用 --shuffle-seed
SEED 调用测试工具将以相同的顺序运行测试。
SEED 是任何 64 位无符号整数,例如,由 --shuffle
生成的整数。
也可以通过 RUST_TEST_SHUFFLE_SEED
环境变量指定。
⚠️ 🚧 此选项为 不稳定,需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #89583。
输出选项
以下选项会影响输出行为。
-q
, --quiet
每个测试显示一个字符,而不是每行一个测试。这是 --format=terse
的别名。
--nocapture
不捕获测试的 stdout 和 stderr,并允许测试打印到控制台。通常会捕获输出,并且仅在测试失败时显示。
也可以通过将 RUST_TEST_NOCAPTURE
环境变量设置为除 0
之外的任何值来指定。
--show-output
在所有测试运行后显示成功测试的 stdout 和 stderr。
将此与 --nocapture
进行对比,后者允许测试在运行时打印,如果有多个测试并行运行,这会导致输出交错,--show-output
确保输出是连续的,但需要等待所有测试完成。
--color
COLOR
控制何时使用彩色终端输出。有效选项
auto
:如果 stdout 是 tty 且未使用--nocapture
,则进行着色。这是默认值。always
:始终对输出进行着色。never
:从不为输出着色。
--format
FORMAT
控制输出的格式。有效选项
pretty
:这是默认格式,每个测试一行。terse
:每个测试仅显示一个字符。--quiet
是此选项的别名。json
:每行发出一个 JSON 对象。⚠️ 🚧 此选项为 不稳定,需要-Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #49359。
--logfile
PATH
将测试结果写入给定文件。
--report-time
⚠️ 🚧 此选项 不稳定,并且需要 -Z unstable-options
标志。有关更多信息,请参阅 跟踪问题 #64888 和 不稳定文档。
不稳定选项
某些 CLI 选项以“不稳定”状态添加,它们用于实验和测试,以确定选项是否正常工作、设计是否正确以及是否有用。选项可能无法正常工作、中断或随时更改。为了表明您承认正在使用不稳定选项,它们需要传递 -Z unstable-options
命令行标志。
基准测试
libtest 工具支持运行使用 #[bench]
属性注释的函数的基准测试。基准测试目前处于不稳定状态,并且仅在 nightly 通道 上可用。有关更多信息,请参阅 不稳定手册。
自定义测试框架
在 nightly 通道 上可以使用自定义测试工具的实验性支持。有关更多信息,请参阅 跟踪问题 #50297 和 custom_test_frameworks 文档。