rust-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rust Testing Patterns

Rust测试模式

Comprehensive Rust testing patterns for writing reliable, maintainable tests following TDD methodology.
这是一套全面的Rust测试模式,可用于编写遵循TDD方法论的可靠、可维护的测试。

When to Use

适用场景

  • Writing new Rust functions, methods, or traits
  • Adding test coverage to existing code
  • Creating benchmarks for performance-critical code
  • Implementing property-based tests for input validation
  • Following TDD workflow in Rust projects
  • 编写新的Rust函数、方法或trait
  • 为现有代码添加测试覆盖率
  • 为性能关键型代码创建基准测试
  • 为输入验证实现基于属性的测试
  • 在Rust项目中遵循TDD工作流

How It Works

工作流程

  1. Identify target code — Find the function, trait, or module to test
  2. Write a test — Use
    #[test]
    in a
    #[cfg(test)]
    module, rstest for parameterized tests, or proptest for property-based tests
  3. Mock dependencies — Use mockall to isolate the unit under test
  4. Run tests (RED) — Verify the test fails with the expected error
  5. Implement (GREEN) — Write minimal code to pass
  6. Refactor — Improve while keeping tests green
  7. Check coverage — Use cargo-llvm-cov, target 80%+
  1. 确定目标代码 — 找到要测试的函数、trait或模块
  2. 编写测试 — 在
    #[cfg(test)]
    模块中使用
    #[test]
    ,使用rstest实现参数化测试,或使用proptest实现基于属性的测试
  3. Mock依赖 — 使用mockall隔离被测单元
  4. 运行测试(红阶段) — 验证测试是否按预期失败
  5. 实现代码(绿阶段) — 编写最少代码使测试通过
  6. 重构 — 在保持测试通过的前提下优化代码
  7. 检查覆盖率 — 使用cargo-llvm-cov,目标覆盖率80%+

TDD Workflow for Rust

Rust中的TDD工作流

The RED-GREEN-REFACTOR Cycle

红-绿-重构循环

RED     → Write a failing test first
GREEN   → Write minimal code to pass the test
REFACTOR → Improve code while keeping tests green
REPEAT  → Continue with next requirement
RED     → 先编写失败的测试
GREEN   → 编写最少代码使测试通过
REFACTOR → 在保持测试通过的前提下优化代码
REPEAT  → 继续处理下一个需求

Step-by-Step TDD in Rust

Rust中TDD分步实践

rust
// RED: Write test first, use todo!() as placeholder
pub fn add(a: i32, b: i32) -> i32 { todo!() }

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_add() { assert_eq!(add(2, 3), 5); }
}
// cargo test → panics at 'not yet implemented'
rust
// GREEN: Replace todo!() with minimal implementation
pub fn add(a: i32, b: i32) -> i32 { a + b }
// cargo test → PASS, then REFACTOR while keeping tests green
rust
// RED: 先编写测试,用todo!()作为占位符
pub fn add(a: i32, b: i32) -> i32 { todo!() }

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_add() { assert_eq!(add(2, 3), 5); }
}
// cargo test → 会因'not yet implemented'触发panic
rust
// GREEN: 替换todo!()为最简实现
pub fn add(a: i32, b: i32) -> i32 { a + b }
// cargo test → 测试通过,之后在保持测试通过的前提下进行重构

Unit Tests

单元测试

Module-Level Test Organization

模块级测试组织

rust
// src/user.rs
pub struct User {
    pub name: String,
    pub email: String,
}

impl User {
    pub fn new(name: impl Into<String>, email: impl Into<String>) -> Result<Self, String> {
        let email = email.into();
        if !email.contains('@') {
            return Err(format!("invalid email: {email}"));
        }
        Ok(Self { name: name.into(), email })
    }

    pub fn display_name(&self) -> &str {
        &self.name
    }
}

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

    #[test]
    fn creates_user_with_valid_email() {
        let user = User::new("Alice", "alice@example.com").unwrap();
        assert_eq!(user.display_name(), "Alice");
        assert_eq!(user.email, "alice@example.com");
    }

    #[test]
    fn rejects_invalid_email() {
        let result = User::new("Bob", "not-an-email");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("invalid email"));
    }
}
rust
// src/user.rs
pub struct User {
    pub name: String,
    pub email: String,
}

impl User {
    pub fn new(name: impl Into<String>, email: impl Into<String>) -> Result<Self, String> {
        let email = email.into();
        if !email.contains('@') {
            return Err(format!("invalid email: {email}"));
        }
        Ok(Self { name: name.into(), email })
    }

    pub fn display_name(&self) -> &str {
        &self.name
    }
}

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

    #[test]
    fn creates_user_with_valid_email() {
        let user = User::new("Alice", "alice@example.com").unwrap();
        assert_eq!(user.display_name(), "Alice");
        assert_eq!(user.email, "alice@example.com");
    }

    #[test]
    fn rejects_invalid_email() {
        let result = User::new("Bob", "not-an-email");
        assert!(result.is_err());
        assert!(result.unwrap_err().contains("invalid email"));
    }
}

Assertion Macros

断言宏

rust
assert_eq!(2 + 2, 4);                                    // Equality
assert_ne!(2 + 2, 5);                                    // Inequality
assert!(vec![1, 2, 3].contains(&2));                     // Boolean
assert_eq!(value, 42, "expected 42 but got {value}");    // Custom message
assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON);   // Float comparison
rust
assert_eq!(2 + 2, 4);                                    // 相等断言
assert_ne!(2 + 2, 5);                                    // 不等断言
assert!(vec![1, 2, 3].contains(&2));                     // 布尔断言
assert_eq!(value, 42, "expected 42 but got {value}");    // 自定义提示信息的断言
assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON);   // 浮点数比较

Error and Panic Testing

错误与Panic测试

Testing
Result
Returns

测试
Result
返回值

rust
#[test]
fn parse_returns_error_for_invalid_input() {
    let result = parse_config("}{invalid");
    assert!(result.is_err());

    // Assert specific error variant
    let err = result.unwrap_err();
    assert!(matches!(err, ConfigError::ParseError(_)));
}

#[test]
fn parse_succeeds_for_valid_input() -> Result<(), Box<dyn std::error::Error>> {
    let config = parse_config(r#"{"port": 8080}"#)?;
    assert_eq!(config.port, 8080);
    Ok(()) // Test fails if any ? returns Err
}
rust
#[test]
fn parse_returns_error_for_invalid_input() {
    let result = parse_config("}{invalid");
    assert!(result.is_err());

    // 断言特定的错误变体
    let err = result.unwrap_err();
    assert!(matches!(err, ConfigError::ParseError(_)));
}

#[test]
fn parse_succeeds_for_valid_input() -> Result<(), Box<dyn std::error::Error>> {
    let config = parse_config(r#"{"port": 8080}"#)?;
    assert_eq!(config.port, 8080);
    Ok(()) // 如果任何?返回Err,测试会失败
}

Testing Panics

测试Panic场景

rust
#[test]
#[should_panic]
fn panics_on_empty_input() {
    process(&[]);
}

#[test]
#[should_panic(expected = "index out of bounds")]
fn panics_with_specific_message() {
    let v: Vec<i32> = vec![];
    let _ = v[0];
}
rust
#[test]
#[should_panic]
fn panics_on_empty_input() {
    process(&[]);
}

#[test]
#[should_panic(expected = "index out of bounds")]
fn panics_with_specific_message() {
    let v: Vec<i32> = vec![];
    let _ = v[0];
}

Integration Tests

集成测试

File Structure

文件结构

text
my_crate/
├── src/
│   └── lib.rs
├── tests/              # Integration tests
│   ├── api_test.rs     # Each file is a separate test binary
│   ├── db_test.rs
│   └── common/         # Shared test utilities
│       └── mod.rs
text
my_crate/
├── src/
│   └── lib.rs
├── tests/              # 集成测试目录
│   ├── api_test.rs     # 每个文件都是独立的测试二进制文件
│   ├── db_test.rs
│   └── common/         # 共享测试工具
│       └── mod.rs

Writing Integration Tests

编写集成测试

rust
// tests/api_test.rs
use my_crate::{App, Config};

#[test]
fn full_request_lifecycle() {
    let config = Config::test_default();
    let app = App::new(config);

    let response = app.handle_request("/health");
    assert_eq!(response.status, 200);
    assert_eq!(response.body, "OK");
}
rust
// tests/api_test.rs
use my_crate::{App, Config};

#[test]
fn full_request_lifecycle() {
    let config = Config::test_default();
    let app = App::new(config);

    let response = app.handle_request("/health");
    assert_eq!(response.status, 200);
    assert_eq!(response.body, "OK");
}

Async Tests

异步测试

With Tokio

基于Tokio的异步测试

rust
#[tokio::test]
async fn fetches_data_successfully() {
    let client = TestClient::new().await;
    let result = client.get("/data").await;
    assert!(result.is_ok());
    assert_eq!(result.unwrap().items.len(), 3);
}

#[tokio::test]
async fn handles_timeout() {
    use std::time::Duration;
    let result = tokio::time::timeout(
        Duration::from_millis(100),
        slow_operation(),
    ).await;

    assert!(result.is_err(), "should have timed out");
}
rust
#[tokio::test]
async fn fetches_data_successfully() {
    let client = TestClient::new().await;
    let result = client.get("/data").await;
    assert!(result.is_ok());
    assert_eq!(result.unwrap().items.len(), 3);
}

#[tokio::test]
async fn handles_timeout() {
    use std::time::Duration;
    let result = tokio::time::timeout(
        Duration::from_millis(100),
        slow_operation(),
    ).await;

    assert!(result.is_err(), "should have timed out");
}

Test Organization Patterns

测试组织模式

Parameterized Tests with
rstest

使用
rstest
实现参数化测试

rust
use rstest::{rstest, fixture};

#[rstest]
#[case("hello", 5)]
#[case("", 0)]
#[case("rust", 4)]
fn test_string_length(#[case] input: &str, #[case] expected: usize) {
    assert_eq!(input.len(), expected);
}

// Fixtures
#[fixture]
fn test_db() -> TestDb {
    TestDb::new_in_memory()
}

#[rstest]
fn test_insert(test_db: TestDb) {
    test_db.insert("key", "value");
    assert_eq!(test_db.get("key"), Some("value".into()));
}
rust
use rstest::{rstest, fixture};

#[rstest]
#[case("hello", 5)]
#[case("", 0)]
#[case("rust", 4)]
fn test_string_length(#[case] input: &str, #[case] expected: usize) {
    assert_eq!(input.len(), expected);
}

// 测试夹具(Fixtures)
#[fixture]
fn test_db() -> TestDb {
    TestDb::new_in_memory()
}

#[rstest]
fn test_insert(test_db: TestDb) {
    test_db.insert("key", "value");
    assert_eq!(test_db.get("key"), Some("value".into()));
}

Test Helpers

测试辅助函数

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

    /// Creates a test user with sensible defaults.
    fn make_user(name: &str) -> User {
        User::new(name, &format!("{name}@test.com")).unwrap()
    }

    #[test]
    fn user_display() {
        let user = make_user("alice");
        assert_eq!(user.display_name(), "alice");
    }
}
rust
#[cfg(test)]
mod tests {
    use super::*;

    /// 创建带有合理默认值的测试用户。
    fn make_user(name: &str) -> User {
        User::new(name, &format!("{name}@test.com")).unwrap()
    }

    #[test]
    fn user_display() {
        let user = make_user("alice");
        assert_eq!(user.display_name(), "alice");
    }
}

Property-Based Testing with
proptest

使用
proptest
进行基于属性的测试

Basic Property Tests

基础属性测试

rust
use proptest::prelude::*;

proptest! {
    #[test]
    fn encode_decode_roundtrip(input in ".*") {
        let encoded = encode(&input);
        let decoded = decode(&encoded).unwrap();
        assert_eq!(input, decoded);
    }

    #[test]
    fn sort_preserves_length(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        let original_len = vec.len();
        vec.sort();
        assert_eq!(vec.len(), original_len);
    }

    #[test]
    fn sort_produces_ordered_output(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        vec.sort();
        for window in vec.windows(2) {
            assert!(window[0] <= window[1]);
        }
    }
}
rust
use proptest::prelude::*;

proptest! {
    #[test]
    fn encode_decode_roundtrip(input in ".*") {
        let encoded = encode(&input);
        let decoded = decode(&encoded).unwrap();
        assert_eq!(input, decoded);
    }

    #[test]
    fn sort_preserves_length(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        let original_len = vec.len();
        vec.sort();
        assert_eq!(vec.len(), original_len);
    }

    #[test]
    fn sort_produces_ordered_output(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {
        vec.sort();
        for window in vec.windows(2) {
            assert!(window[0] <= window[1]);
        }
    }
}

Custom Strategies

自定义策略

rust
use proptest::prelude::*;

fn valid_email() -> impl Strategy<Value = String> {
    ("[a-z]{1,10}", "[a-z]{1,5}")
        .prop_map(|(user, domain)| format!("{user}@{domain}.com"))
}

proptest! {
    #[test]
    fn accepts_valid_emails(email in valid_email()) {
        assert!(User::new("Test", &email).is_ok());
    }
}
rust
use proptest::prelude::*;

fn valid_email() -> impl Strategy<Value = String> {
    ("[a-z]{1,10}", "[a-z]{1,5}")
        .prop_map(|(user, domain)| format!("{user}@{domain}.com"))
}

proptest! {
    #[test]
    fn accepts_valid_emails(email in valid_email()) {
        assert!(User::new("Test", &email).is_ok());
    }
}

Mocking with
mockall

使用
mockall
进行Mocking测试

Trait-Based Mocking

基于Trait的Mocking

rust
use mockall::{automock, predicate::eq};

#[automock]
trait UserRepository {
    fn find_by_id(&self, id: u64) -> Option<User>;
    fn save(&self, user: &User) -> Result<(), StorageError>;
}

#[test]
fn service_returns_user_when_found() {
    let mut mock = MockUserRepository::new();
    mock.expect_find_by_id()
        .with(eq(42))
        .times(1)
        .returning(|_| Some(User { id: 42, name: "Alice".into() }));

    let service = UserService::new(Box::new(mock));
    let user = service.get_user(42).unwrap();
    assert_eq!(user.name, "Alice");
}

#[test]
fn service_returns_none_when_not_found() {
    let mut mock = MockUserRepository::new();
    mock.expect_find_by_id()
        .returning(|_| None);

    let service = UserService::new(Box::new(mock));
    assert!(service.get_user(99).is_none());
}
rust
use mockall::{automock, predicate::eq};

#[automock]
trait UserRepository {
    fn find_by_id(&self, id: u64) -> Option<User>;
    fn save(&self, user: &User) -> Result<(), StorageError>;
}

#[test]
fn service_returns_user_when_found() {
    let mut mock = MockUserRepository::new();
    mock.expect_find_by_id()
        .with(eq(42))
        .times(1)
        .returning(|_| Some(User { id: 42, name: "Alice".into() }));

    let service = UserService::new(Box::new(mock));
    let user = service.get_user(42).unwrap();
    assert_eq!(user.name, "Alice");
}

#[test]
fn service_returns_none_when_not_found() {
    let mut mock = MockUserRepository::new();
    mock.expect_find_by_id()
        .returning(|_| None);

    let service = UserService::new(Box::new(mock));
    assert!(service.get_user(99).is_none());
}

Doc Tests

文档测试

Executable Documentation

可执行文档

rust
/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// use my_crate::add;
///
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// Parses a config string.
///
/// # Errors
///
/// Returns `Err` if the input is not valid TOML.
///
/// ```no_run
/// use my_crate::parse_config;
///
/// let config = parse_config(r#"port = 8080"#).unwrap();
/// assert_eq!(config.port, 8080);
/// ```
///
/// ```no_run
/// use my_crate::parse_config;
///
/// assert!(parse_config("}{invalid").is_err());
/// ```
pub fn parse_config(input: &str) -> Result<Config, ParseError> {
    todo!()
}
rust
/// 将两个数字相加。
///
/// # 示例
///
/// ```
/// use my_crate::add;
///
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(-1, 1), 0);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

/// 解析配置字符串。
///
/// # 错误
///
/// 如果输入不是有效的TOML格式,返回`Err`。
///
/// ```no_run
/// use my_crate::parse_config;
///
/// let config = parse_config(r#"port = 8080"#).unwrap();
/// assert_eq!(config.port, 8080);
/// ```
///
/// ```no_run
/// use my_crate::parse_config;
///
/// assert!(parse_config("}{invalid").is_err());
/// ```
pub fn parse_config(input: &str) -> Result<Config, ParseError> {
    todo!()
}

Benchmarking with Criterion

使用Criterion进行基准测试

toml
undefined
toml
undefined

Cargo.toml

Cargo.toml

[dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] }
[[bench]] name = "benchmark" harness = false

```rust
// benches/benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 | 1 => n,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

fn bench_fibonacci(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, bench_fibonacci);
criterion_main!(benches);
[dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] }
[[bench]] name = "benchmark" harness = false

```rust
// benches/benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 | 1 => n,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

fn bench_fibonacci(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, bench_fibonacci);
criterion_main!(benches);

Test Coverage

测试覆盖率

Running Coverage

运行覆盖率检测

bash
undefined
bash
undefined

Install: cargo install cargo-llvm-cov (or use taiki-e/install-action in CI)

安装:cargo install cargo-llvm-cov(或在CI中使用taiki-e/install-action)

cargo llvm-cov # Summary cargo llvm-cov --html # HTML report cargo llvm-cov --lcov > lcov.info # LCOV format for CI cargo llvm-cov --fail-under-lines 80 # Fail if below threshold
undefined
cargo llvm-cov # 生成摘要 cargo llvm-cov --html # 生成HTML报告 cargo llvm-cov --lcov > lcov.info # 生成CI可用的LCOV格式报告 cargo llvm-cov --fail-under-lines 80 # 如果覆盖率低于阈值则失败
undefined

Coverage Targets

覆盖率目标

Code TypeTarget
Critical business logic100%
Public API90%+
General code80%+
Generated / FFI bindingsExclude
代码类型目标覆盖率
核心业务逻辑100%
公共API90%+
通用代码80%+
自动生成/FFI绑定代码排除检测

Testing Commands

测试命令汇总

bash
cargo test                        # Run all tests
cargo test -- --nocapture         # Show println output
cargo test test_name              # Run tests matching pattern
cargo test --lib                  # Unit tests only
cargo test --test api_test        # Integration tests only
cargo test --doc                  # Doc tests only
cargo test --no-fail-fast         # Don't stop on first failure
cargo test -- --ignored           # Run ignored tests
bash
cargo test                        # 运行所有测试
cargo test -- --nocapture         # 显示println输出内容
cargo test test_name              # 运行匹配指定名称的测试
cargo test --lib                  # 仅运行单元测试
cargo test --test api_test        # 仅运行指定的集成测试
cargo test --doc                  # 仅运行文档测试
cargo test --no-fail-fast         # 不因为第一个失败就停止测试
cargo test -- --ignored           # 运行被标记为忽略的测试

Best Practices

最佳实践

DO:
  • Write tests FIRST (TDD)
  • Use
    #[cfg(test)]
    modules for unit tests
  • Test behavior, not implementation
  • Use descriptive test names that explain the scenario
  • Prefer
    assert_eq!
    over
    assert!
    for better error messages
  • Use
    ?
    in tests that return
    Result
    for cleaner error output
  • Keep tests independent — no shared mutable state
DON'T:
  • Use
    #[should_panic]
    when you can test
    Result::is_err()
    instead
  • Mock everything — prefer integration tests when feasible
  • Ignore flaky tests — fix or quarantine them
  • Use
    sleep()
    in tests — use channels, barriers, or
    tokio::time::pause()
  • Skip error path testing
建议:
  • 先编写测试(TDD)
  • 使用
    #[cfg(test)]
    模块组织单元测试
  • 测试行为而非实现细节
  • 使用描述性的测试名称来解释测试场景
  • 优先使用
    assert_eq!
    而非
    assert!
    以获得更清晰的错误信息
  • 在返回
    Result
    的测试中使用
    ?
    以简化错误输出
  • 保持测试独立 — 不要共享可变状态
避免:
  • 当可以测试
    Result::is_err()
    时,不要使用
    #[should_panic]
  • 不要Mock所有依赖 — 在可行时优先使用集成测试
  • 不要忽略不稳定的测试 — 修复或隔离它们
  • 不要在测试中使用
    sleep()
    — 使用通道、屏障或
    tokio::time::pause()
  • 不要跳过错误路径的测试

CI Integration

CI集成示例

yaml
undefined
yaml
undefined

GitHub Actions

GitHub Actions

test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable with: components: clippy, rustfmt
- name: Check formatting
  run: cargo fmt --check

- name: Clippy
  run: cargo clippy -- -D warnings

- name: Run tests
  run: cargo test

- uses: taiki-e/install-action@cargo-llvm-cov

- name: Coverage
  run: cargo llvm-cov --fail-under-lines 80

**Remember**: Tests are documentation. They show how your code is meant to be used. Write them clearly and keep them up to date.
test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable with: components: clippy, rustfmt
- name: 检查代码格式
  run: cargo fmt --check

- name: 运行Clippy检查
  run: cargo clippy -- -D warnings

- name: 运行测试
  run: cargo test

- uses: taiki-e/install-action@cargo-llvm-cov

- name: 检测测试覆盖率
  run: cargo llvm-cov --fail-under-lines 80

**注意**:测试也是文档。它们展示了代码的预期使用方式。请清晰编写并保持测试更新。