The Rust Programming Language

测试组织

正如本章开头所述，测试是一门复杂的学科，不同的人使用不同的术语和组织方式。Rust 社区从两个主要类别来考虑测试：单元测试和集成测试。单元测试较小且更集中，一次只测试一个模块，并且可以测试私有接口。集成测试完全位于你的库之外，以任何其他外部代码使用你代码的相同方式使用你的代码，仅使用公共接口，并且每个测试可能涉及多个模块。

编写这两种测试对于确保您的库的各个部分按预期工作，无论是单独还是共同工作，都非常重要。

单元测试

单元测试的目的是在与其他代码隔离的情况下测试每个代码单元，以便快速定位代码是否按预期工作。您将在 src 目录中的每个文件中放置单元测试，与它们测试的代码放在同一个文件中。惯例是在每个文件中创建一个名为 tests 的模块来包含测试函数，并使用 cfg(test) 注解该模块。

The Tests Module and #[cfg(test)]

#[cfg(test)] 注解在 tests 模块上告诉 Rust 只有在你运行 cargo test 时才编译和运行测试代码，而不是在你运行 cargo build 时。这在你只想构建库时节省了编译时间，并且在生成的编译产物中节省了空间，因为测试代码没有被包含。你会看到，由于集成测试位于不同的目录中，它们不需要 #[cfg(test)] 注解。然而，因为单元测试与代码位于同一文件中，你需要使用 #[cfg(test)] 来指定它们不应包含在编译结果中。

回想一下，当我们在本章第一部分生成新的adder项目时，Cargo 为我们生成了以下代码：

文件名: 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);
    }
}

在自动生成的 tests 模块中，属性 cfg 代表 配置，并告诉 Rust 只有在给定特定配置选项时才应包含以下项。在这种情况下，配置选项是 test，这是 Rust 为编译和运行测试提供的。通过使用 cfg 属性，Cargo 仅在我们使用 cargo test 主动运行测试时编译我们的测试代码。这包括可能在这个模块内的任何辅助函数，以及用 #[test] 注解的函数。

Testing Private Functions

测试社区内部对于是否应该直接测试私有函数存在争议，其他语言使得测试私有函数变得困难或不可能。无论你遵循哪种测试理念，Rust 的隐私规则确实允许你测试私有函数。考虑列表 11-12 中的代码，其中包含私有函数 internal_adder。

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

fn internal_adder(left: usize, right: usize) -> usize {
    left + right
}

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

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

请注意，internal_adder 函数没有标记为 pub。测试只是 Rust 代码，tests 模块也只是另一个模块。正如我们在 “模块树中引用项的路径” 部分讨论的那样，子模块中的项可以使用其祖先模块中的项。在这个测试中，我们使用 use super::* 将 tests 模块的父模块的所有项引入作用域，然后测试就可以调用 internal_adder。如果你认为不应该测试私有函数，Rust 中没有任何东西会强迫你这样做。

集成测试

在 Rust 中，集成测试完全独立于您的库。它们以与任何其他代码相同的方式使用您的库，这意味着它们只能调用您库的公共 API 中的函数。它们的目的是测试您的库的许多部分是否能正确协同工作。单独工作正常的代码单元在集成时可能会出现问题，因此集成代码的测试覆盖率也很重要。要创建集成测试，您首先需要一个 tests 目录。

The tests Directory

我们在项目的顶级目录中创建一个 tests 目录，与 src 并列。Cargo 知道在这个目录中查找集成测试文件。然后，我们可以创建任意数量的测试文件，Cargo 会将每个文件编译为一个单独的 crate。

让我们创建一个集成测试。在 src/lib.rs 文件中保留 Listing 11-12 的代码，创建一个 tests 目录，并在其中创建一个名为 tests/integration_test.rs 的新文件。你的目录结构应该如下所示：

adder
├── Cargo.lock
├── Cargo.toml
├── src
│   └── lib.rs
└── tests
    └── integration_test.rs

将清单 11-13 中的代码输入到 tests/integration_test.rs 文件中。

use adder::add_two;

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

tests 目录中的每个文件都是一个单独的 crate，因此我们需要将我们的库引入每个测试 crate 的作用域。为此，我们在代码的顶部添加 use adder::add_two;，而在单元测试中我们并不需要这样做。

我们不需要在 tests/integration_test.rs 中的任何代码上标注 #[cfg(test)]。Cargo 会特别处理 tests 目录，并且只在我们运行 cargo test 时编译该目录中的文件。现在运行 cargo test：

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

running 1 test
test tests::internal ... ok

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

     Running tests/integration_test.rs (target/debug/deps/integration_test-1082c4b063a8fbe6)

running 1 test
test it_adds_two ... ok

test result: ok. 1 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

输出的三个部分包括单元测试、集成测试和文档测试。请注意，如果某个部分中的任何测试失败，后续的部分将不会运行。例如，如果单元测试失败，将不会有集成测试和文档测试的输出，因为这些测试只有在所有单元测试通过的情况下才会运行。

单元测试的第一部分与我们之前看到的相同：每个单元测试一行（一个名为internal的测试，我们在清单11-12中添加了这个测试），然后是一行单元测试的总结。

集成测试部分从行Running tests/integration_test.rs开始。接下来，每个测试函数都有一个行， 在Doc-tests adder部分开始之前，还有一个总结行显示集成测试的结果。

每个集成测试文件都有其自己的部分，因此如果我们添加更多文件到tests目录中，将会有更多的集成测试部分。

我们仍然可以通过将测试函数的名称作为参数传递给cargo test来运行特定的集成测试函数。要运行特定集成测试文件中的所有测试，请使用cargo test的--test参数，后跟文件的名称：

$ cargo test --test integration_test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.64s
     Running tests/integration_test.rs (target/debug/deps/integration_test-82e7799c1bc62298)

running 1 test
test it_adds_two ... ok

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

这个命令只运行 tests/integration_test.rs 文件中的测试。

Submodules in Integration Tests

随着您添加更多的集成测试，您可能希望在 tests 目录中创建更多文件以帮助组织它们；例如，您可以按它们测试的功能将测试函数分组。如前所述，tests 目录中的每个文件都被编译为其自己的独立 crate，这对于创建独立的作用域以更接近地模拟最终用户使用您的 crate 的方式非常有用。然而，这意味着 tests 目录中的文件与 src 中的文件不共享相同的行为，正如您在第 7 章中学到的关于如何将代码分离到模块和文件中的内容。

tests 目录文件的不同行为在你有一组要在多个集成测试文件中使用的辅助函数，并尝试遵循第 7 章的 “将模块分离到不同的文件中” 部分中的步骤将它们提取到一个公共模块时最为明显。例如，如果我们创建 tests/common.rs 并在其中放置一个名为 setup 的函数，我们可以在 setup 中添加一些代码，这些代码我们希望从多个测试文件中的多个测试函数中调用：

文件名: tests/common.rs

pub fn setup() {
    // setup code specific to your library's tests would go here
}

当我们再次运行测试时，我们会在测试输出中看到一个针对 common.rs 文件的新部分，即使这个文件不包含任何测试函数，也没有从任何地方调用 setup 函数：

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

running 1 test
test tests::internal ... ok

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

     Running tests/common.rs (target/debug/deps/common-92948b65e88960b4)

running 0 tests

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

     Running tests/integration_test.rs (target/debug/deps/integration_test-92948b65e88960b4)

running 1 test
test it_adds_two ... ok

test result: ok. 1 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

在测试结果中看到 common 并显示 running 0 tests 并不是我们想要的。我们只是想与其他集成测试文件共享一些代码。为了避免 common 出现在测试输出中，我们将创建 tests/common/mod.rs 而不是 tests/common.rs。项目目录现在如下所示：

├── Cargo.lock
├── Cargo.toml
├── src
│   └── lib.rs
└── tests
    ├── common
    │   └── mod.rs
    └── integration_test.rs

这是我们在第 7 章“备用文件路径”部分提到的旧命名约定，Rust 也理解这一点。以这种方式命名文件告诉 Rust 不要将 common 模块视为集成测试文件。当我们把 setup 函数的代码移到 tests/common/mod.rs 并删除 tests/common.rs 文件时，测试输出中的部分将不再出现。tests 目录的子目录中的文件不会被编译为单独的 crate，也不会在测试输出中显示部分。

在我们创建了tests/common/mod.rs之后，我们可以在任何集成测试文件中将其用作模块。以下是从tests/integration_test.rs中的it_adds_two测试调用setup函数的示例：

文件名: tests/integration_test.rs

use adder::add_two;

mod common;

#[test]
fn it_adds_two() {
    common::setup();

    let result = add_two(2);
    assert_eq!(result, 4);
}

请注意，mod common; 声明与我们在清单 7-21 中演示的模块声明相同。然后，在测试函数中，我们可以调用 common::setup() 函数。

Integration Tests for Binary Crates

如果我们的项目是一个只包含 src/main.rs 文件的二进制 crate，并且没有 src/lib.rs 文件，我们无法在 tests 目录中创建集成测试，并将 src/main.rs 文件中定义的函数通过 use 语句引入作用域。只有库 crate 才能暴露其他 crate 可以使用的函数；二进制 crate 是为了独立运行而设计的。

这是提供二进制文件的 Rust 项目有一个直接的 src/main.rs 文件调用位于 src/lib.rs 文件中的逻辑的原因之一。使用这种结构，集成测试 可以 通过 use 使重要的功能可用，从而测试库 crate。如果重要的功能可以工作，src/main.rs 文件中的少量代码也会正常工作，这部分少量的代码不需要被测试。

摘要

Rust 的测试功能提供了一种指定代码应如何工作的方法，以确保即使在您进行更改时，代码仍能按预期工作。单元测试分别测试库的不同部分，并可以测试私有实现细节。集成测试检查库的许多部分是否能正确协同工作，并使用库的公共 API 以与外部代码使用相同的方式测试代码。即使 Rust 的类型系统和所有权规则有助于防止某些类型的错误，测试对于减少与代码预期行为相关的逻辑错误仍然很重要。

让我们结合你在本章和前几章中学到的知识来做一个项目！