Rust 测试组织指南：单元测试与集成测试

一、为什么要同时使用单元测试与集成测试

1. 单元测试：更为精细、聚焦某一逻辑单元；可以调用到私有函数，快速定位错误根源。
2. 集成测试：作为"外部代码"来使用库的公开接口，测试多个模块间的交互，确保整体功能正确。

Rust 的类型系统与所有权机制会在一定程度上减少潜在 Bug，但业务逻辑可能依旧存在错误。将这两种测试结合使用，能有效覆盖从单个函数到库全局的多层面需求，构建更健壮的项目。

二、单元测试（Unit Tests）

1. 放置位置与 #[cfg(test)]

在 Rust 中，单元测试一般放在与被测代码相同的文件中，并位于一个 #[cfg(test)] 模块里。例如，工程中有一个 src/lib.rs 文件，代码可以写成：

// src/lib.rs
pub fn add_two(x: i32) -> i32 {
    x + 2
}

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

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

• #[cfg(test)]：指定该模块在测试编译时才会被包含，避免在正式构建中编译测试代码。
• #[test]：标明此函数是一个测试函数，cargo test 会自动执行它。

2. 测试私有函数

与某些语言不同，Rust 并不禁止测试私有函数。原因是测试本质上只是另一个普通模块，可以通过 use super::* 访问父模块中的私有接口。例如：

fn internal_add(a: i32, b: i32) -> i32 {
    a + b
}

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

    #[test]
    fn it_adds_two_numbers() {
        assert_eq!(internal_add(3, 4), 7);
    }
}

如果你遵循"不测试私有函数"的原则，也可只在公开接口上编写测试。Rust 不作强制约束，一切由你和团队的测试理念决定。

三、集成测试（Integration Tests）

1. 测试文件放在 tests 目录

与单元测试不同，集成测试位于项目根目录下的 tests 文件夹，每个文件都会被当作独立的测试 crate 。只需创建该目录，即可让 cargo test 自动编译并执行其中所有测试。

目录结构示例：

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

一个简单的集成测试文件可能如下：

// tests/integration_test.rs
use my_project::add_two;

#[test]
fn test_add_two() {
    assert_eq!(add_two(2), 4);
}

要点：

• 集成测试文件必须 显式地 use 库（如 my_project::add_two）；
• 不需要加 #[cfg(test)]，因为该目录下文件仅在 cargo test 时被编译；
• 每个文件为一个独立 crate，彼此之间互不影响。

2. 运行与筛选集成测试

执行 cargo test 时，Rust 将依次运行单元测试 、集成测试 和（若存在）文档测试。如果只想运行某个集成测试文件，可以使用：

cargo test --test integration_test

其中 integration_test 为去掉 .rs 后的文件名（即 integration_test.rs）。

3. 在集成测试间共享辅助代码

有时，多个集成测试文件可能需要调用同样的初始化或辅助逻辑。这些代码可放在 tests/common/mod.rs 中，再在测试文件里 mod common; 引入并使用。例如：

tests
├── common
│   └── mod.rs
└── integration_test.rs

• common/mod.rs 中定义 pub fn setup() { ... } 等；
• integration_test.rs 中 mod common; 后，就可在测试内调用 common::setup()。

这样不会将 common 视为一个单独的测试文件，也不会在 cargo test 输出中显示 "running 0 tests"。

四、二进制项目的测试建议

如果你主要编写的是二进制 （只有 src/main.rs）而没有 src/lib.rs，那么集成测试就很难直接引用 main 函数中的内容。对此通常的推荐做法是：

1. 在 src/lib.rs 中放置核心逻辑；
2. src/main.rs 仅做轻量包装和调用；
3. 集成测试只需要引入 lib.rs 中的公共函数即可测试大部分逻辑。

这样可以保证你的主要业务功能既能被二进制入口 (main.rs) 调用，也能被测试模块引用。

五、结语

Rust 为单元测试和集成测试都提供了一套清晰的机制和约定，有效地帮助你分别聚焦模块内部和整体外部 API 的正确性。通常的建议是：

1. 单元测试 ：与实现代码同文件、写入 #[cfg(test)] 模块，用于快速检测单个函数或模块的正确性；可测试私有函数细节。
2. 集成测试 ：新建 tests/ 目录，用来模拟用户会如何使用你的库公共 API，确保跨模块协作行为正确。

通过同时使用这两种测试方法，你可以在细节层面和集成层面构建起更完备的测试体系。正如业界常言：没有测试的代码只能算是一次大胆的尝试。借助 Rust 强大的类型系统及其便利的测试组织方式，相信你能更轻松地写出安全、可靠的高质量程序！

祝你玩转 Rust 测试！