Rust 2026 经验谈 - 测试策略全景

测试是工程质量的底线。Rust 的测试体系在 2024-2026 年间已经形成了从单元测试到属性测试、从 mock 到 benchmark 的完整工具链。本文覆盖测试组织、属性测试、参数化、mock、异步测试、benchmark、覆盖率七大主题，给出实战中的踩坑经验。

单元/集成/Doc Test 组织与惯例#

单元测试#

Rust 的单元测试与代码放在同一文件，这是语言的惯用法：

1
pub fn parse_header(input: &[u8]) -> Result<Header, ParseError> {
2
    if input.len() < 4 {
3
        return Err(ParseError::TooShort);
4
    }
5
    let magic = &input[0..4];
6
    if magic != b"ABCD" {
7
        return Err(ParseError::BadMagic);
8
    }
9
    Ok(Header { version: input[4] })
10
}
11

12
#[cfg(test)]
13
mod tests {
14
    use super::*;
15
    use core::assert_matches;
16

17
    #[test]
18
    fn parse_valid_header() {
19
        let input = b"ABCD\x01";
20
        let header = parse_header(input).unwrap();
21
        assert_eq!(header.version, 1);
22
    }
23

24
    #[test]
25
    fn parse_too_short() {
26
        let result = parse_header(b"AB");
27
        assert_matches!(result, Err(ParseError::TooShort));
28
    }
29

30
    #[test]
31
    fn parse_bad_magic() {
32
        let result = parse_header(b"XXXX\x01");
33
        assert_matches!(result, Err(ParseError::BadMagic));
34
    }
35
}

惯用法要点：

测试模块用 #[cfg(test)] + mod tests
use super::* 导入被测代码
测试函数用 #[test] 标注
私有函数也可以测试（同一模块内）
Rust 1.96+ 可用 assert_matches! 替代 assert!(matches!(..))，需 use core::assert_matches

集成测试#

集成测试放在 tests/ 目录，每个文件是独立的 crate：

1
my-project/
2
├── src/
3
│   └── lib.rs
4
└── tests/
5
    ├── common/
6
    │   └── mod.rs      // 共享辅助（不是独立测试）
7
    ├── api.rs          // API 集成测试
8
    └── database.rs     // 数据库集成测试

1
use my_project::Client;
2

3
#[tokio::test]
4
async fn test_create_and_get_user() {
5
    let client = Client::new("http://localhost:8080");
6
    let user = client.create_user("Alice").await.unwrap();
7
    let fetched = client.get_user(user.id).await.unwrap();
8
    assert_eq!(fetched.name, "Alice");
9
}

1
// 共享辅助代码，不会被 cargo test 当作测试运行
2
pub fn setup_test_db() -> PgPool {
3
    // ...
4
}
5

6
pub fn create_test_app() -> TestApp {
7
    // ...
8
}

Doc Test#

文档中的代码示例也是测试：

1
/// 将字节切片解析为无符号整数。
2
///
3
/// # Examples
4
///
5
/// ```
6
/// use mylib::parse_u32;
7
///
8
/// let result = parse_u32(&[0x12, 0x34, 0x56, 0x78]);
9
/// assert_eq!(result, 0x12345678);
10
/// ```
11
///
12
/// 空切片返回 0：
13
///
14
/// ```
15
/// use mylib::parse_u32;
16
/// assert_eq!(parse_u32(&[]), 0);
17
/// ```
18
pub fn parse_u32(bytes: &[u8]) -> u32 { /* ... */ }
19

20
/// 内部函数，不运行 doc test：
21
///
22
/// ```ignore
23
/// // ignore：这段代码不编译（依赖外部状态）
24
/// let db = connect();
25
/// ```
26
fn internal() {}

doc test 的 no_run 和 compile_fail：

1
/// ```no_run
2
/// // 编译但不运行（如需要网络）
3
/// let server = mylib::Server::bind("0.0.0.0:8080").await.unwrap();
4
/// server.run().await.unwrap();
5
/// ```
6
///
7
/// ```compile_fail
8
/// // 期望编译失败——验证类型安全
9
/// let x: i32 = "hello"; // 类型不匹配
10
/// ```
11
fn documented() {}

踩坑：测试组织常见问题#

1
问题 1：单元测试测了私有实现细节
2
  → 重构时测试全崩
3
  → 原则：单元测试测公开 API，只在必要时测关键内部逻辑
4

5
问题 2：集成测试没有共享 setup
6
  → 每个测试重复创建资源
7
  → 解决：tests/common/mod.rs 或 test fixtures crate
8

9
问题 3：doc test 依赖外部状态
10
  → CI 中 doc test 失败
11
  → 解决：用 no_run 或 ignore
12

13
问题 4：测试间有隐式顺序依赖
14
  → cargo test 并行运行导致间歇性失败
15
  → 解决：每个测试独立，或用 serial_test crate

proptest 属性测试#

proptest 不测”某个输入对不对”，而测”所有输入是否满足某个属性”：

1
[dev-dependencies]
2
proptest = "1.5"

基本用法#

1
use proptest::prelude::*;
2

3
// 测试属性：sort 之后长度不变且有序
4
proptest! {
5
    #[test]
6
    fn sort_preserves_length_and_ordered(ref input in prop::collection::vec(any::<i32>(), 0..100)) {
7
        let mut sorted = input.clone();
8
        sorted.sort();
9

10
        // 长度不变
11
        assert_eq!(sorted.len(), input.len());
12

13
        // 有序
14
        for window in sorted.windows(2) {
15
            assert!(window[0] <= window[1]);
16
        }
17

18
        // 相同元素（排序是排列）
19
        let mut input_sorted = input.clone();
20
        input_sorted.sort();
21
        assert_eq!(sorted, input_sorted);
22
    }
23
}

自定义策略（Strategy）#

1
use proptest::prelude::*;
2

3
// 自定义策略：合法的邮箱格式
4
fn email_strategy() -> impl Strategy<Value = String> {
5
    "[a-z]{3,10}".prop_flat_map(|local| {
6
        ("[a-z]{3,8}", "[a-z]{2,4}").prop_map(move |(domain, tld)| {
7
            format!("{}@{}.{}", local, domain, tld)
8
        })
9
    })
10
}
11

12
proptest! {
13
    #[test]
14
    fn test_parse_email(ref email in email_strategy()) {
15
        let result = parse_email(email);
16
        assert!(result.is_ok(), "Failed to parse valid email: {}", email);
17
    }
18
}
19

20
// 更简单的自定义策略
21
proptest! {
22
    #[test]
23
    fn test_non_empty_string(ref s in "[a-zA-Z0-9]{1,50}") {
24
        assert!(!s.is_empty());
25
        assert!(s.len() <= 50);
26
    }
27
}

Shrink：失败用例的最小化#

proptest 发现失败后，会自动收缩（shrink）输入，找到最小失败用例：

1
proptest! {
2
    #[test]
3
    fn test_addition_commutative(a in any::<i32>(), b in any::<i32>()) {
4
        // 如果这个测试失败，proptest 会尝试更小的 a 和 b
5
        assert_eq!(a + b, b + a);
6
    }
7
}

失败输出示例：

1
thread 'main' panicked at 'assertion failed: `(left == right)`
2
  left: `-1`,
3
 right: `1`
4

5
minimal failing input:
6
  a = -1
7
  b = 0

踩坑：proptest 与 async#

1
// ❌ proptest! 宏不支持 async
2
proptest! {
3
    #[test]
4
    async fn bad_async_test(input in ".*") {  // 编译错误
5
        async_work(input).await;
6
    }
7
}
8

9
// ✓ 方案 1：用 proptest! + tokio::runtime
10
proptest! {
11
    #[test]
12
    fn test_async_with_proptest(input in ".*") {
13
        let rt = tokio::runtime::Runtime::new().unwrap();
14
        rt.block_on(async {
15
            async_work(&input).await;
16
        });
17
    }
18
}
19

20
// ✓ 方案 2：用 tokio::test + 手动策略
21
#[tokio::test]
22
async fn test_async_property() {
23
    let strategy = proptest::strategy::Strategy::prop_map(
24
        "[a-zA-Z]{1,20}",
25
        |s| s
26
    );
27
    proptest::proptest!(|(input in "[a-zA-Z]{1,20}")| {
28
        let result = tokio::runtime::Handle::current().block_on(async_work(&input));
29
        assert!(result.is_ok());
30
    });
31
}

rstest：Fixture 与参数化#

1
[dev-dependencies]
2
rstest = "0.23"

Fixture#

1
use rstest::*;
2
use sqlx::PgPool;
3

4
// 定义 fixture
5
#[fixture]
6
async fn test_pool() -> PgPool {
7
    let pool = PgPool::connect("postgres://test:test@localhost/test_db")
8
        .await
9
        .unwrap();
10
    // 运行 migration
11
    sqlx::migrate!("./migrations").run(&pool).await.unwrap();
12
    pool
13
}
14

15
// 使用 fixture
16
#[rstest]
17
#[tokio::test]
18
async fn test_create_user(#[future] test_pool: PgPool) {
19
    let pool = test_pool.await;
20
    let user = create_user(&pool, "Alice").await.unwrap();
21
    assert_eq!(user.name, "Alice");
22
}
23

24
// 多个 fixture 组合
25
#[fixture]
26
fn config() -> Config {
27
    Config::load("test.toml").unwrap()
28
}
29

30
#[rstest]
31
#[tokio::test]
32
async fn test_with_fixtures(
33
    #[future] test_pool: PgPool,
34
    config: Config,
35
) {
36
    let pool = test_pool.await;
37
    let service = Service::new(pool, config);
38
    // ...
39
}

参数化测试#

1
use rstest::*;
2

3
// 简单参数化
4
#[rstest]
5
#[case(0, 0, 0)]
6
#[case(1, 2, 3)]
7
#[case(-1, 1, 0)]
8
#[case(100, -50, 50)]
9
fn test_addition(#[case] a: i32, #[case] b: i32, #[case] expected: i32) {
10
    assert_eq!(a + b, expected);
11
}
12

13
// 带描述的参数化
14
#[rstest]
15
#[case::empty("", 0)]
16
#[case::single("a", 1)]
17
#[case::unicode("你好世界", 4)]  // 4 个 Unicode 标量值
18
fn test_char_count(#[case] input: &str, #[case] expected: usize) {
19
    assert_eq!(input.chars().count(), expected);
20
}
21

22
// 值列表参数化
23
#[rstest]
24
#[values(i32::MIN, -1, 0, 1, i32::MAX)]
25
fn test_abs_non_negative(x: i32) {
26
    assert!(x.abs() >= 0);
27
}

mockall：Mock 框架#

1
[dev-dependencies]
2
mockall = "0.13"

基本 Mock#

1
use mockall::{automock, mock, predicate::*};
2

3
// 方式 1：automock 自动为 trait 生成 mock
4
#[automock]
5
trait Database {
6
    fn get_user(&self, id: u64) -> Result<User, Error>;
7
    fn save_user(&self, user: &User) -> Result<(), Error>;
8
}
9

10
#[test]
11
fn test_service_with_mock_db() {
12
    let mut mock_db = MockDatabase::new();
13

14
    // 设置期望
15
    mock_db
16
        .expect_get_user()
17
        .with(eq(42))
18
        .times(1)
19
        .returning(|id| Ok(User { id, name: "Alice".into() }));
20

21
    let service = Service::new(mock_db);
22
    let user = service.get_user(42).unwrap();
23
    assert_eq!(user.name, "Alice");
24
}
25

26
// 方式 2：手动定义 mock（更灵活）
27
mock! {
28
    ExternalApi {}
29
    impl ExternalApiTrait for ExternalApi {
30
        fn fetch_data(&self, key: &str) -> Result<Vec<u8>, Error>;
31
        async fn send_notification(&self, msg: &str) -> Result<(), Error>;
32
    }
33
}
34

35
#[tokio::test]
36
async fn test_async_mock() {
37
    let mut mock_api = MockExternalApi::new();
38

39
    mock_api
40
        .expect_send_notification()
41
        .with(eq("hello"))
42
        .times(1)
43
        .returning(|_| Ok(()));
44

45
    let service = Service::with_api(mock_api);
46
    service.notify("hello").await.unwrap();
47
}

Mock 的序列与上下文#

1
use mockall::{automock, Sequence};
2
use mockall::predicate::*;
3

4
#[automock]
5
trait Repository {
6
    fn insert(&self, item: &Item) -> Result<(), Error>;
7
    fn commit(&self) -> Result<(), Error>;
8
}
9

10
#[test]
11
fn test_transaction_ordering() {
12
    let mut mock_repo = MockRepository::new();
13
    let mut seq = Sequence::new();
14

15
    // 保证调用顺序：先 insert，再 commit
16
    mock_repo
17
        .expect_insert()
18
        .in_sequence(&mut seq)
19
        .returning(|_| Ok(()));
20

21
    mock_repo
22
        .expect_commit()
23
        .in_sequence(&mut seq)
24
        .returning(|| Ok(()));
25

26
    let service = Service::new(mock_repo);
27
    service.save_transaction(&item).unwrap();
28
}

踩坑：mock 与所有权#

1
// ❌ returning 闭包的签名必须匹配 trait 方法
2
// 如果 trait 返回 owned 类型，闭包不能返回引用
3
mock_db.expect_get_user()
4
    .returning(|id| {
5
        // ❌ 不能返回临时值的引用
6
        Ok(User { id, name: String::from("Alice") }) // ✓ 返回 owned
7
    });
8

9
// ❌ expect 设置次数不匹配 → 测试 panic
10
mock_db.expect_get_user().times(2); // 期望调用 2 次
11
// 但实际只调用了 1 次 → panic: mockall: Expectation called fewer than 2 times

测试异步代码#

tokio::test 基本用法#

1
#[tokio::test]
2
async fn test_async_function() {
3
    let result = fetch_data("http://example.com").await;
4
    assert!(result.is_ok());
5
}
6

7
// 指定 runtime 配置
8
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
9
async fn test_with_multi_thread() {
10
    // 需要 multi_thread 的场景（如 spawn + block_in_place）
11
    let handle = tokio::spawn(async { 42 });
12
    assert_eq!(handle.await.unwrap(), 42);
13
}

手动 Poll 测试#

某些场景需要直接操作 Future 的 poll：

1
use std::future::Future;
2
use std::pin::Pin;
3
use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
4

5
fn dummy_waker() -> Waker {
6
    fn no_op(_: *const ()) {}
7
    fn clone(_: *const ()) -> RawWaker {
8
        RawWaker::new(std::ptr::null(), &VTABLE)
9
    }
10
    static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, no_op, no_op, no_op);
11
    unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) }
12
}
13

14
#[test]
15
fn test_future_poll_manually() {
16
    let mut future = some_future();
17
    let waker = dummy_waker();
18
    let mut cx = Context::from_waker(&waker);
19

20
    // 第一次 poll
21
    let pinned = unsafe { Pin::new_unchecked(&mut future) };
22
    match pinned.poll(&mut cx) {
23
        Poll::Ready(val) => assert_eq!(val, 42),
24
        Poll::Pending => { /* 继续推进 */ }
25
    }
26
}

实际中更常见的是用 futures::poll! 宏：

1
use futures::poll!;
2
use std::task::Poll;
3

4
#[test]
5
fn test_poll_macro() {
6
    let mut future = Box::pin(some_future());
7
    let waker = futures::task::noop_waker_ref();
8
    let mut cx = std::task::Context::from_waker(waker);
9

10
    match poll!(future.as_mut(), cx) {
11
        Poll::Ready(val) => assert_eq!(val, 42),
12
        Poll::Pending => {}
13
    }
14
}

踩坑：时间相关异步测试#

1
use tokio::time::{sleep, Duration, pause, advance};
2

3
// ❌ 真实等待——测试极慢
4
#[tokio::test]
5
async fn bad_slow_test() {
6
    sleep(Duration::from_secs(5)).await;
7
    // 等 5 秒！
8
}
9

10
// ✓ 使用 tokio 时间模拟
11
#[tokio::test(start_paused = true)]
12
async fn good_fast_test() {
13
    // start_paused = true 自动暂停时间
14
    let handle = tokio::spawn(async {
15
        sleep(Duration::from_secs(5)).await;
16
        42
17
    });
18

19
    // 手动推进时间
20
    tokio::time::advance(Duration::from_secs(5)).await;
21

22
    let result = handle.await.unwrap();
23
    assert_eq!(result, 42);
24
}

criterion Benchmark 实操#

1
[dev-dependencies]
2
criterion = { version = "0.5", features = ["html_reports"] }
3

4
[[bench]]
5
name = "my_benchmark"
6
harness = false

基本 Benchmark#

1
use criterion::{criterion_group, criterion_main, Criterion, BenchmarkId, Throughput};
2
use std::time::Duration;
3

4
fn bench_parse(c: &mut Criterion) {
5
    let input = "some complex input string";
6

7
    c.bench_function("parse_header", |b| {
8
        b.iter(|| parse_header(black_box(input.as_bytes())))
9
    });
10
}
11

12
criterion_group! {
13
    name = benches;
14
    config = Criterion::default().measurement_time(Duration::from_secs(10));
15
    targets = bench_parse
16
}
17
criterion_main!(benches);

参数化 Benchmark#

1
fn bench_sort_by_size(c: &mut Criterion) {
2
    let mut group = c.benchmark_group("sort");
3

4
    for size in [10, 100, 1_000, 10_000, 100_000] {
5
        group.throughput(Throughput::Elements(size as u64));
6

7
        group.bench_with_input(BenchmarkId::from_parameter(size), &size, |b, &size| {
8
            b.iter_batched(
9
                || {
10
                    // 每次迭代前生成随机输入
11
                    let mut rng = rand::thread_rng();
12
                    (0..size).map(|_| rng.gen::<u64>()).collect::<Vec<_>>()
13
                },
14
                |mut data| {
15
                    data.sort();
16
                    data
17
                },
18
                criterion::BatchSize::SmallInput,
19
            )
20
        });
21
    }
22

23
    group.finish();
24
}

比较两种实现#

1
fn bench_hash_comparison(c: &mut Criterion) {
2
    let mut group = c.benchmark_group("hash");
3

4
    let data: Vec<u8> = (0..1024).map(|i| i as u8).collect();
5

6
    group.bench_function("sha256", |b| {
7
        b.iter(|| sha256_hash(black_box(&data)))
8
    });
9

10
    group.bench_function("blake3", |b| {
11
        b.iter(|| blake3_hash(black_box(&data)))
12
    });
13

14
    group.finish();
15
}

Throughput 设置#

1
fn bench_io_throughput(c: &mut Criterion) {
2
    let mut group = c.benchmark_group("file_read");
3

4
    for size in [1024, 8192, 65536, 1_048_576] {
5
        group.throughput(Throughput::Bytes(size as u64));
6

7
        group.bench_with_input(BenchmarkId::from_parameter(size), &size, |b, &size| {
8
            let data = vec![0u8; size];
9
            b.iter(|| {
10
                let mut buf = vec![0u8; size];
11
                buf.copy_from_slice(black_box(&data));
12
                buf
13
            })
14
        });
15
    }
16

17
    group.finish();
18
}

踩坑：benchmark 中的优化逃逸#

1
use std::hint::black_box;
2

3
// ❌ 编译器可能优化掉整个计算
4
fn bad_bench(c: &mut Criterion) {
5
    c.bench_function("compute", |b| {
6
        b.iter(|| {
7
            let x = 1 + 1; // 编译器直接常量折叠，什么都测不到
8
            x
9
        })
10
    });
11
}
12

13
// ✓ 用 black_box 阻止优化
14
fn good_bench(c: &mut Criterion) {
15
    c.bench_function("compute", |b| {
16
        b.iter(|| {
17
            let x = 1 + 1;
18
            black_box(x) // 强制编译器认为 x 被使用了
19
        })
20
    });
21
}

测试覆盖率：cargo-llvm-cov#

安装与基本用法#

1
# 安装
2
cargo install cargo-llvm-cov
3

4
# 运行覆盖率分析
5
cargo llvm-cov
6

7
# 生成 HTML 报告
8
cargo llvm-cov --html
9

10
# 只看特定 crate
11
cargo llvm-cov --package my-crate
12

13
# 忽略特定文件
14
cargo llvm-cov --ignore-filename-regex "tests/|benches/"

CI 集成#

1
name: Coverage
2
on: [push, pull_request]
3
jobs:
4
  coverage:
5
    runs-on: ubuntu-latest
6
    steps:
7
      - uses: actions/checkout@v4
8
      - uses: dtolnay/rust-toolchain@stable
9
        with:
10
          components: llvm-tools-preview
11
      - uses: taiki-e/install-action@cargo-llvm-cov
12
      - name: Generate coverage
13
        run: cargo llvm-cov --lcov --output-path lcov.info
14
      - uses: codecov/codecov-action@v4
15
        with:
16
          files: lcov.info

踸踩坑#

1
# 问题 1：nightly 才能生成覆盖率
2
# 解决：cargo llvm-cov 自动处理，但需要 llvm-tools-preview
3
rustup component add llvm-tools-preview
4

5
# 问题 2：doc test 覆盖率噪声
6
# 解决：只跑 lib 和 tests
7
cargo llvm-cov --no-report -- --lib --tests
8

9
# 问题 3：多 crate workspace 的覆盖率合并
10
# 解决：在 workspace 根目录运行
11
cargo llvm-cov --workspace

覆盖率目标#

1
总体目标：
2
  核心逻辑（parser、协议实现）：≥ 90%
3
  业务逻辑（handler、service）：≥ 80%
4
  集成测试路径：≥ 60%
5
  不追求 100%——getter/setter、trivial 代码可以忽略
6

7
实践建议：
8
  1. 覆盖率是手段不是目的——不要为覆盖率写无用测试
9
  2. 优先覆盖错误分支（happy path 往往自然覆盖）
10
  3. 用 #[cfg(test)] 的辅助函数减少测试样板
11
  4. 定期在 CI 中跟踪覆盖率趋势，而不是追求绝对值

音乐

音乐