集成测试 tests/ ​

核心概念 ​

集成测试(integration test)放在项目根目录的 tests/ 文件夹中,每个文件是一个独立的 crate。与单元测试不同,集成测试从外部视角测试你的库——只能访问公共 API,不能访问私有函数。集成测试验证多个模块协同工作的行为是否正确。

集成测试只适用于库 crate(有 src/lib.rs)。纯二进制 crate(只有 src/main.rs)无法被集成测试直接导入,需要将逻辑提取到 src/lib.rs 中。

# 项目结构
my-project/
├── Cargo.toml
├── src/
│   ├── lib.rs          # 库代码
│   └── main.rs         # 可选的二进制入口
├── tests/              # 集成测试目录
│   ├── api_test.rs     # 每个文件是一个独立的测试 crate
│   ├── db_test.rs
│   └── common/         # 共享的辅助模块
│       └── mod.rs
rust
// src/lib.rs
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

pub struct Calculator {
    result: i32,
}

impl Calculator {
    pub fn new() -> Self {
        Calculator { result: 0 }
    }

    pub fn add(&mut self, value: i32) -> &mut Self {
        self.result += value;
        self
    }

    pub fn result(&self) -> i32 {
        self.result
    }
}
rust
// tests/basic_test.rs — 集成测试文件
// 每个文件自动是独立的 crate,不需要 #[cfg(test)]
use my_project::{add, multiply, Calculator};

#[test]
fn test_add() {
    assert_eq!(add(2, 3), 5);
}

#[test]
fn test_multiply() {
    assert_eq!(multiply(4, 5), 20);
}

#[test]
fn test_calculator_chain() {
    let mut calc = Calculator::new();
    calc.add(10).add(20).add(30);
    assert_eq!(calc.result(), 60);
}

共享辅助代码 ​

rust
// tests/common/mod.rs — 共享的测试辅助模块
// 注意:必须放在子目录的 mod.rs 中,否则会被当作独立测试文件

pub fn setup() {
    // 初始化测试环境
    println!("测试环境初始化完成");
}

pub fn create_test_data() -> Vec<i32> {
    vec![1, 2, 3, 4, 5]
}
rust
// tests/integration_test.rs
mod common;  // 导入共享模块

use my_project::add;

#[test]
fn test_with_setup() {
    common::setup();
    let data = common::create_test_data();
    let sum: i32 = data.iter().map(|&x| add(x, 1)).sum();
    assert_eq!(sum, 20); // (2+3+4+5+6) = 20
}

单元测试 vs 集成测试 ​

特性单元测试集成测试
位置src/ 中的 #[cfg(test)] 模块tests/ 目录
访问范围公共 + 私有 API只有公共 API
视角内部视角外部用户视角
编译方式与库代码一起编译独立 crate
#[cfg(test)]需要不需要
适用目标lib 和 bin只有 lib

基本示例 ​

rust
// src/lib.rs
pub mod parser {
    pub fn parse_csv_line(line: &str) -> Vec<String> {
        line.split(',')
            .map(|s| s.trim().to_string())
            .collect()
    }

    pub fn parse_csv(content: &str) -> Vec<Vec<String>> {
        content
            .lines()
            .filter(|line| !line.is_empty())
            .map(|line| parse_csv_line(line))
            .collect()
    }
}

pub mod formatter {
    pub fn to_csv_line(fields: &[String]) -> String {
        fields.join(",")
    }

    pub fn to_csv(rows: &[Vec<String>]) -> String {
        rows.iter()
            .map(|row| to_csv_line(row))
            .collect::<Vec<_>>()
            .join("\n")
    }
}
rust
// tests/csv_roundtrip.rs — 集成测试:验证解析和格式化的往返一致性
use my_project::{parser, formatter};

#[test]
fn test_csv_roundtrip() {
    let original = "name,age,city\nAlice,30,Beijing\nBob,25,Shanghai";

    // 解析
    let parsed = parser::parse_csv(original);
    assert_eq!(parsed.len(), 3);
    assert_eq!(parsed[0], vec!["name", "age", "city"]);

    // 格式化回来
    let formatted = formatter::to_csv(&parsed);
    assert_eq!(formatted, original);
}

#[test]
fn test_empty_csv() {
    let parsed = parser::parse_csv("");
    assert!(parsed.is_empty());

    let formatted = formatter::to_csv(&[]);
    assert_eq!(formatted, "");
}

#[test]
fn test_single_field() {
    let parsed = parser::parse_csv_line("hello");
    assert_eq!(parsed, vec!["hello"]);
}

常用命令 ​

bash
# 运行所有测试(单元 + 集成 + 文档)
# cargo test

# 只运行集成测试
# cargo test --test csv_roundtrip

# 运行特定集成测试文件中的特定函数
# cargo test --test csv_roundtrip test_empty_csv

# 运行所有集成测试(跳过单元测试和文档测试)
# cargo test --tests

# 只运行单元测试
# cargo test --lib

常见问题 ​

问题一:tests/ 下的文件都会被当作测试吗?

tests/ 下的每个 .rs 文件都是独立的测试 crate。子目录中的 mod.rs 不会被当作测试(用于共享辅助代码)。子目录中的其他 .rs 文件也不会被自动发现。

问题二:集成测试可以测试 binary crate 吗?

不能直接导入。解决方案是将业务逻辑放在 src/lib.rs 中,src/main.rs 只做入口调用。集成测试导入库 crate 进行测试。

问题三:集成测试的编译速度比单元测试慢?

是的。每个集成测试文件是独立的 crate,需要单独编译。如果有很多小测试文件,可以合并到一个文件中减少编译时间。

问题四:集成测试可以使用 dev-dependencies 吗?

可以。tests/ 中的代码可以使用 [dev-dependencies] 中声明的所有依赖。

适用场景 ​

  • API 契约验证:从用户角度测试公共 API
  • 模块协作测试:验证多个模块配合工作
  • 端到端流程:完整的业务流程测试
  • 回归测试:确保修改不影响外部行为

注意事项 ​

  • 集成测试只能测试库 crate 的公共 API
  • 每个文件是独立的 crate,不需要 #[cfg(test)]
  • 共享代码放在 tests/common/mod.rs 中
  • 集成测试可以使用 [dev-dependencies]
  • 太多小文件会增加编译时间
  • cargo test --test filename 运行特定文件

总结 ​

集成测试放在 tests/ 目录中,每个文件是独立的 crate,从外部用户的视角测试公共 API。不需要 #[cfg(test)],直接用 use crate_name::* 导入。共享的辅助代码放在 tests/common/mod.rs 中通过 mod common 引入。集成测试只适用于库 crate,binary crate 需要将逻辑提取到 lib.rs。cargo test --test name 运行特定文件,cargo test --tests 运行所有集成测试。