The Rust Programming Language

控制测试的运行方式

正如 cargo run 编译您的代码并运行生成的二进制文件一样，cargo test 以测试模式编译您的代码并运行生成的测试二进制文件。由 cargo test 生成的二进制文件的默认行为是并行运行所有测试，并捕获测试运行期间生成的输出，防止输出显示，从而使与测试结果相关的输出更容易阅读。但是，您可以指定命令行选项来更改此默认行为。

一些命令行选项传递给cargo test，而另一些则传递给生成的测试二进制文件。为了区分这两种类型的参数，您需要先列出传递给cargo test的参数，然后是分隔符--，接着是传递给测试二进制文件的参数。运行cargo test --help会显示您可以与cargo test一起使用的选项，而运行cargo test -- --help会显示分隔符后可以使用的选项。这些选项也在“测试”部分的rustc手册中有文档说明。

并行或顺序运行测试

当你运行多个测试时，默认情况下它们会使用线程并行运行，这意味着它们会更快完成运行，你也能更快地获得反馈。因为测试是同时运行的，你必须确保你的测试之间不互相依赖，也不依赖任何共享状态，包括共享的环境，如当前工作目录或环境变量。

例如，假设每个测试运行的代码都会在磁盘上创建一个名为test-output.txt的文件，并向该文件写入一些数据。然后每个测试读取该文件中的数据，并断言文件包含特定的值，每个测试的值都不同。因为测试同时运行，一个测试可能在另一个测试写入和读取文件之间的时间内覆盖该文件。第二个测试将失败，不是因为代码错误，而是因为测试在并行运行时相互干扰。一种解决方案是确保每个测试写入不同的文件；另一种解决方案是依次运行测试。

如果你不想并行运行测试，或者想要对使用的线程数量进行更细粒度的控制，可以向测试二进制文件发送 --test-threads 标志和你想要使用的线程数量。看看以下示例：

$ cargo test -- --test-threads=1

我们将测试线程的数量设置为1，告诉程序不要使用任何并行性。使用一个线程运行测试会比并行运行花费更长时间，但如果测试共享状态，它们不会相互干扰。

显示函数输出

默认情况下，如果测试通过，Rust 的测试库会捕获打印到标准输出的任何内容。例如，如果我们在测试中调用 println! 并且测试通过，我们不会在终端中看到 println! 的输出；我们只会看到表示测试通过的那行。如果测试失败，我们会看到打印到标准输出的内容以及其余的失败信息。

例如，列表 11-10 有一个愚蠢的函数，它打印其参数的值并返回 10，以及一个通过的测试和一个失败的测试。

fn prints_and_returns_10(a: i32) -> i32 {
    println!("I got the value {a}");
    10
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn this_test_will_pass() {
        let value = prints_and_returns_10(4);
        assert_eq!(value, 10);
    }

    #[test]
    fn this_test_will_fail() {
        let value = prints_and_returns_10(8);
        assert_eq!(value, 5);
    }
}

当我们使用 cargo test 运行这些测试时，我们将看到以下输出：

$ cargo test
   Compiling silly-function v0.1.0 (file:///projects/silly-function)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running unittests src/lib.rs (target/debug/deps/silly_function-160869f38cff9166)

running 2 tests
test tests::this_test_will_fail ... FAILED
test tests::this_test_will_pass ... ok

failures:

---- tests::this_test_will_fail stdout ----
I got the value 8

thread 'tests::this_test_will_fail' panicked at src/lib.rs:19:9:
assertion `left == right` failed
  left: 10
 right: 5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::this_test_will_fail

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

请注意，在此输出中我们 nowhere in this output do we see 我得到了值 4，这是在通过的测试运行时打印的。该输出已被捕获。失败测试的输出，我得到了值 8，出现在测试摘要输出的部分，该部分还显示了测试失败的原因。

如果我们还想查看通过测试的打印值，可以告诉 Rust 使用 --show-output 也显示成功测试的输出：

$ cargo test -- --show-output

当我们再次使用 --show-output 标志运行列表 11-10 中的测试时，我们看到以下输出：

$ cargo test -- --show-output
   Compiling silly-function v0.1.0 (file:///projects/silly-function)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.60s
     Running unittests src/lib.rs (target/debug/deps/silly_function-160869f38cff9166)

running 2 tests
test tests::this_test_will_fail ... FAILED
test tests::this_test_will_pass ... ok

successes:

---- tests::this_test_will_pass stdout ----
I got the value 4


successes:
    tests::this_test_will_pass

failures:

---- tests::this_test_will_fail stdout ----
I got the value 8

thread 'tests::this_test_will_fail' panicked at src/lib.rs:19:9:
assertion `left == right` failed
  left: 10
 right: 5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace


failures:
    tests::this_test_will_fail

test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

按名称运行测试子集

有时，运行完整的测试套件可能需要很长时间。如果你正在处理特定区域的代码，你可能只想运行与该代码相关的测试。你可以通过将你想要运行的测试的名称或名称列表作为参数传递给cargo test来选择要运行的测试。

为了演示如何运行测试的子集，我们首先为我们的add_two函数创建三个测试，如列表11-11所示，并选择要运行的测试。

pub fn add_two(a: usize) -> usize {
    a + 2
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn add_two_and_two() {
        let result = add_two(2);
        assert_eq!(result, 4);
    }

    #[test]
    fn add_three_and_two() {
        let result = add_two(3);
        assert_eq!(result, 5);
    }

    #[test]
    fn one_hundred() {
        let result = add_two(100);
        assert_eq!(result, 102);
    }
}

如果我们不传递任何参数就运行测试，正如我们之前所见，所有测试将并行运行：

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.62s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 3 tests
test tests::add_three_and_two ... ok
test tests::add_two_and_two ... ok
test tests::one_hundred ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

运行单个测试

我们可以将任何测试函数的名称传递给cargo test来仅运行该测试：

$ cargo test one_hundred
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.69s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test tests::one_hundred ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.00s

只有名为one_hundred的测试运行了；其他两个测试不符合该名称。测试输出通过显示2 filtered out告诉我们有更多未运行的测试。

我们不能以这种方式指定多个测试的名称；只有给 cargo test 的第一个值会被使用。但有一种方法可以运行多个测试。

筛选以运行多个测试

我们可以指定测试名称的一部分，任何名称与该值匹配的测试都会运行。例如，因为我们的两个测试名称中包含add，我们可以通过运行cargo test add来运行这两个测试：

$ cargo test add
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 2 tests
test tests::add_three_and_two ... ok
test tests::add_two_and_two ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

这个命令运行了所有名称中包含 add 的测试，并过滤掉了名为 one_hundred 的测试。还请注意，测试出现的模块成为测试名称的一部分，因此我们可以通过过滤模块名称来运行模块中的所有测试。

除非特别要求，否则忽略某些测试

有时一些特定的测试执行起来非常耗时，因此你可能希望在大多数 cargo test 运行中排除它们。与其列出所有你想要运行的测试作为参数，不如使用 ignore 属性标注这些耗时的测试以排除它们，如下所示：

文件名: src/lib.rs

pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }

    #[test]
    #[ignore]
    fn expensive_test() {
        // code that takes an hour to run
    }
}

在 #[test] 之后，我们向要排除的测试添加 #[ignore] 行。 现在当我们运行测试时，it_works 运行，但 expensive_test 不运行：

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.60s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 2 tests
test tests::expensive_test ... ignored
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

expensive_test 函数被列为 ignored。如果我们只想运行被忽略的测试，可以使用 cargo test -- --ignored：

$ cargo test -- --ignored
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test expensive_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

   Doc-tests adder

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

通过控制运行哪些测试，您可以确保 cargo test 的结果能够快速返回。当您认为检查 ignored 测试的结果是有意义的，并且有时间等待结果时，可以运行 cargo test -- --ignored。如果您想运行所有测试，无论它们是否被忽略，可以运行 cargo test -- --include-ignored。