rust-testing

Rust 测试与基准测试

基于 The Rust Programming Language 第 11 章和《Rust 程序设计语言》。

能力边界

✅ 优势

1. 单元测试（使用 #[test]，通过 #[cfg(test)] 组织测试模块）
2. 断言宏（assert!、assert_eq!、assert_ne!、debug_assert!）
3. 测试属性（#[should_panic]、#[ignore]、#[cfg(test)]）
4. 集成测试（tests/ 目录和共享模块）
5. 文档测试（代码块、使用 # 隐藏行，以及 should_panic/no_run/ignore 标记）
6. cargo test 运行器（筛选、--nocapture、--test-threads、--include-ignored 选项）
7. 稳定版 Criterion 基准测试；明确区分稳定版 Criterion 与仅限 nightly 的 libtest #[bench] 属性
8. 使用 cargo-llvm-cov 进行代码覆盖率检查
9. 异步竞态条件、背压、超时、进程/守护进程模型、平台矩阵，以及资源受限测试

⚠️ 前置条件

1. 了解 Rust 模块系统（rust-workspace）

❌ 不在范围内

1. 基于属性的测试（proptest）→ 目前未涵盖
2. Mock 对象 → 目前未涵盖
3. Rust 基础语法 → 请改用 rust-stable 技能

适用场景

• “编写单元测试”
• “集成测试应该放在哪里？”
• “如何编写文档测试？”
• “性能基准测试”
• “检查代码覆盖率”

---

路由边界

当测试需要判定源 Java 测试套件的处置方式、区分镜像测试与黄金/实时差分证据、添加特定于目标的所有权/异步/错误/组件义务、审查追逐覆盖率的测试，或验证迁移生命周期/适配器/宿主验收时，请使用 rust-java-migration-testing。此技能专注于通用 Rust 测试机制和 Rust 原生测试架构。

单元测试

// src/lib.rs
pub fn add(a: i32, b: i32) -> i32 { a + b }
pub fn divide(a: i32, b: i32) -> i32 {
    if b == 0 { panic!("divide by zero"); }
    a / b
}

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

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

    #[test]
    fn test_add_negative() {
        assert_eq!(add(-1, 1), 0, "addition with negative");
    }

    #[test]
    #[should_panic(expected = "divide by zero")]
    fn test_divide_by_zero() {
        divide(1, 0);
    }

    #[test]
    #[ignore = "not implemented"]
    fn test_future() { unimplemented!() }
}

集成测试

my-project/
├── Cargo.toml
├── src/lib.rs
└── tests/
    ├── common/          # Test shared modules
    │   └── mod.rs
    ├── integration_test.rs
    └── api_test.rs

// tests/integration_test.rs — Each file is an independent crate
use my_project::add;

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

// tests/common/mod.rs — Shared helper functions
pub fn setup() { /* ... */ }

文档测试（doctest）

/// Add two numbers.
///
/// ```
/// use my_crate::add;
/// assert_eq!(add(2, 3), 5);
/// ```
///
/// ```rust,should_panic
/// my_crate::divide(1, 0);
/// ```
///
/// ```rust,no_run
/// // Compile but do not run
/// loop {}
/// ```
pub fn add(a: i32, b: i32) -> i32 { a + b }

cargo test 命令

cargo test                    # Run all tests
cargo test test_name          # Filter by name
cargo test -- --nocapture     # Show println output
cargo test -- --test-threads=1 # Single thread
cargo test -- --skip test_name # Skip specific tests
cargo test -- --ignored       # Only run #[ignore] tests
cargo test -- --include-ignored # Include ignored tests
cargo test --doc              # Run only documentation tests
cargo test -p my-crate        # Specific package

基准测试

稳定版项目应优先使用 Criterion。内置的 libtest #[bench] 仍依赖 nightly 的 #![feature(test)]，不能作为稳定版默认解决方案。

// Nightly-only builtin approach (do not use for stable gatekeeping)
#![feature(test)]
extern crate test;

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

    #[bench]
    fn bench_add(b: &mut Bencher) {
        b.iter(|| add(1, 2));
    }
}

// Stable approach using criterion
// [dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] }
use criterion::{black_box, Criterion};

fn bench_add(c: &mut Criterion) {
    c.bench_function("add", |b| b.iter(|| add(black_box(1), black_box(2))));
}
criterion_group!(benches, bench_add);
criterion_main!(benches);

代码覆盖率

# Install
cargo install cargo-llvm-cov

# Usage
cargo llvm-cov                   # Run and report results
cargo llvm-cov --open            # Generate HTML reports
cargo llvm-cov --lcov --output-path lcov.info  # LCOV format output

工作流

1. 准备测试环境 — 确保 cargo test 可用，并确认测试类型（单元/集成/文档）
2. 编写单元测试 — 在 #[cfg(test)] 模块中实现 #[test] 函数
3. 添加集成测试 — 在 tests/ 目录中创建独立的 crate 类型文件
4. 添加文档测试 — 在 /// 注释中嵌入可执行代码块
5. 运行并调试 — 使用 cargo test；使用 --nocapture 定位问题；对于共享资源，优先采用资源隔离或测试分组，避免永久串行运行整个测试套件
6. 并发与平台验证 — 在真实目标平台上，对队列上限、慢速消费者、断开连接、取消、超时和优雅关闭实现有界断言；直接运行特定于平台的代码
7. 覆盖率检查 — 使用 cargo llvm-cov 验证覆盖率范围

注意事项

1. #[cfg(test)] 模块中的代码不会编译进 release 构建 — 辅助函数应放在 tests/common/mod.rs 中
2. 集成测试文件是独立的 crate — 其中不能使用 super:: 或 crate:: 前缀
3. 文档测试中的隐藏行（#）仍会执行，但对编译器不可见
4. cargo test 默认并行运行；共享资源冲突应通过使用唯一的临时目录/端口、进程隔离、nextest 测试组限制，或仅在必要时进行局部串行化来解决
5. #[bench] 需要 #![feature(test)] — 稳定版 Rust 必须改用 criterion
6. 为异步测试设置过宽的超时会掩盖死锁原因；还应断言中间状态、任务恢复情况和资源数量

按需资源

• 测试示例
• 宏命令和命令参考
• 并发、守护进程和平台测试：在读取时测试任务中的内存泄漏、慢速消费者、竞争条件、实际进程以及受资源限制的并行处理。
• examples/golden-tests/：CI 编译并运行 doctest 黄金示例

官方参考资料

• The Book 第 11 章
• Rustdoc Book — doctest 文档
• cargo test 命令参考
• criterion.rs 库文档