Rust Testing

1---2name: rust-testing3description: Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. Follows TDD methodology.4origin: ECC5---6 7# Rust Testing Patterns8 9Comprehensive Rust testing patterns for writing reliable, maintainable tests following TDD methodology.10 11## When to Use12 13- Writing new Rust functions, methods, or traits14- Adding test coverage to existing code15- Creating benchmarks for performance-critical code16- Implementing property-based tests for input validation17- Following TDD workflow in Rust projects18 19## How It Works20 211. **Identify target code** — Find the function, trait, or module to test222. **Write a test** — Use `#[test]` in a `#[cfg(test)]` module, rstest for parameterized tests, or proptest for property-based tests233. **Mock dependencies** — Use mockall to isolate the unit under test244. **Run tests (RED)** — Verify the test fails with the expected error255. **Implement (GREEN)** — Write minimal code to pass266. **Refactor** — Improve while keeping tests green277. **Check coverage** — Use cargo-llvm-cov, target 80%+28 29## TDD Workflow for Rust30 31### The RED-GREEN-REFACTOR Cycle32 33```34RED     → Write a failing test first35GREEN   → Write minimal code to pass the test36REFACTOR → Improve code while keeping tests green37REPEAT  → Continue with next requirement38```39 40### Step-by-Step TDD in Rust41 42```rust43// RED: Write test first, use todo!() as placeholder44pub fn add(a: i32, b: i32) -> i32 { todo!() }45 46#[cfg(test)]47mod tests {48    use super::*;49    #[test]50    fn test_add() { assert_eq!(add(2, 3), 5); }51}52// cargo test → panics at 'not yet implemented'53```54 55```rust56// GREEN: Replace todo!() with minimal implementation57pub fn add(a: i32, b: i32) -> i32 { a + b }58// cargo test → PASS, then REFACTOR while keeping tests green59```60 61## Unit Tests62 63### Module-Level Test Organization64 65```rust66// src/user.rs67pub struct User {68    pub name: String,69    pub email: String,70}71 72impl User {73    pub fn new(name: impl Into<String>, email: impl Into<String>) -> Result<Self, String> {74        let email = email.into();75        if !email.contains('@') {76            return Err(format!("invalid email: {email}"));77        }78        Ok(Self { name: name.into(), email })79    }80 81    pub fn display_name(&self) -> &str {82        &self.name83    }84}85 86#[cfg(test)]87mod tests {88    use super::*;89 90    #[test]91    fn creates_user_with_valid_email() {92        let user = User::new("Alice", "alice@example.com").unwrap();93        assert_eq!(user.display_name(), "Alice");94        assert_eq!(user.email, "alice@example.com");95    }96 97    #[test]98    fn rejects_invalid_email() {99        let result = User::new("Bob", "not-an-email");100        assert!(result.is_err());101        assert!(result.unwrap_err().contains("invalid email"));102    }103}104```105 106### Assertion Macros107 108```rust109assert_eq!(2 + 2, 4);                                    // Equality110assert_ne!(2 + 2, 5);                                    // Inequality111assert!(vec![1, 2, 3].contains(&2));                     // Boolean112assert_eq!(value, 42, "expected 42 but got {value}");    // Custom message113assert!((0.1_f64 + 0.2 - 0.3).abs() < f64::EPSILON);   // Float comparison114```115 116## Error and Panic Testing117 118### Testing `Result` Returns119 120```rust121#[test]122fn parse_returns_error_for_invalid_input() {123    let result = parse_config("}{invalid");124    assert!(result.is_err());125 126    // Assert specific error variant127    let err = result.unwrap_err();128    assert!(matches!(err, ConfigError::ParseError(_)));129}130 131#[test]132fn parse_succeeds_for_valid_input() -> Result<(), Box<dyn std::error::Error>> {133    let config = parse_config(r#"{"port": 8080}"#)?;134    assert_eq!(config.port, 8080);135    Ok(()) // Test fails if any ? returns Err136}137```138 139### Testing Panics140 141```rust142#[test]143#[should_panic]144fn panics_on_empty_input() {145    process(&[]);146}147 148#[test]149#[should_panic(expected = "index out of bounds")]150fn panics_with_specific_message() {151    let v: Vec<i32> = vec![];152    let _ = v[0];153}154```155 156## Integration Tests157 158### File Structure159 160```text161my_crate/162├── src/163│   └── lib.rs164├── tests/              # Integration tests165│   ├── api_test.rs     # Each file is a separate test binary166│   ├── db_test.rs167│   └── common/         # Shared test utilities168│       └── mod.rs169```170 171### Writing Integration Tests172 173```rust174// tests/api_test.rs175use my_crate::{App, Config};176 177#[test]178fn full_request_lifecycle() {179    let config = Config::test_default();180    let app = App::new(config);181 182    let response = app.handle_request("/health");183    assert_eq!(response.status, 200);184    assert_eq!(response.body, "OK");185}186```187 188## Async Tests189 190### With Tokio191 192```rust193#[tokio::test]194async fn fetches_data_successfully() {195    let client = TestClient::new().await;196    let result = client.get("/data").await;197    assert!(result.is_ok());198    assert_eq!(result.unwrap().items.len(), 3);199}200 201#[tokio::test]202async fn handles_timeout() {203    use std::time::Duration;204    let result = tokio::time::timeout(205        Duration::from_millis(100),206        slow_operation(),207    ).await;208 209    assert!(result.is_err(), "should have timed out");210}211```212 213## Test Organization Patterns214 215### Parameterized Tests with `rstest`216 217```rust218use rstest::{rstest, fixture};219 220#[rstest]221#[case("hello", 5)]222#[case("", 0)]223#[case("rust", 4)]224fn test_string_length(#[case] input: &str, #[case] expected: usize) {225    assert_eq!(input.len(), expected);226}227 228// Fixtures229#[fixture]230fn test_db() -> TestDb {231    TestDb::new_in_memory()232}233 234#[rstest]235fn test_insert(test_db: TestDb) {236    test_db.insert("key", "value");237    assert_eq!(test_db.get("key"), Some("value".into()));238}239```240 241### Test Helpers242 243```rust244#[cfg(test)]245mod tests {246    use super::*;247 248    /// Creates a test user with sensible defaults.249    fn make_user(name: &str) -> User {250        User::new(name, &format!("{name}@test.com")).unwrap()251    }252 253    #[test]254    fn user_display() {255        let user = make_user("alice");256        assert_eq!(user.display_name(), "alice");257    }258}259```260 261## Property-Based Testing with `proptest`262 263### Basic Property Tests264 265```rust266use proptest::prelude::*;267 268proptest! {269    #[test]270    fn encode_decode_roundtrip(input in ".*") {271        let encoded = encode(&input);272        let decoded = decode(&encoded).unwrap();273        assert_eq!(input, decoded);274    }275 276    #[test]277    fn sort_preserves_length(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {278        let original_len = vec.len();279        vec.sort();280        assert_eq!(vec.len(), original_len);281    }282 283    #[test]284    fn sort_produces_ordered_output(mut vec in prop::collection::vec(any::<i32>(), 0..100)) {285        vec.sort();286        for window in vec.windows(2) {287            assert!(window[0] <= window[1]);288        }289    }290}291```292 293### Custom Strategies294 295```rust296use proptest::prelude::*;297 298fn valid_email() -> impl Strategy<Value = String> {299    ("[a-z]{1,10}", "[a-z]{1,5}")300        .prop_map(|(user, domain)| format!("{user}@{domain}.com"))301}302 303proptest! {304    #[test]305    fn accepts_valid_emails(email in valid_email()) {306        assert!(User::new("Test", &email).is_ok());307    }308}309```310 311## Mocking with `mockall`312 313### Trait-Based Mocking314 315```rust316use mockall::{automock, predicate::eq};317 318#[automock]319trait UserRepository {320    fn find_by_id(&self, id: u64) -> Option<User>;321    fn save(&self, user: &User) -> Result<(), StorageError>;322}323 324#[test]325fn service_returns_user_when_found() {326    let mut mock = MockUserRepository::new();327    mock.expect_find_by_id()328        .with(eq(42))329        .times(1)330        .returning(|_| Some(User { id: 42, name: "Alice".into() }));331 332    let service = UserService::new(Box::new(mock));333    let user = service.get_user(42).unwrap();334    assert_eq!(user.name, "Alice");335}336 337#[test]338fn service_returns_none_when_not_found() {339    let mut mock = MockUserRepository::new();340    mock.expect_find_by_id()341        .returning(|_| None);342 343    let service = UserService::new(Box::new(mock));344    assert!(service.get_user(99).is_none());345}346```347 348## Doc Tests349 350### Executable Documentation351 352```rust353/// Adds two numbers together.354///355/// # Examples356///357/// ```358/// use my_crate::add;359///360/// assert_eq!(add(2, 3), 5);361/// assert_eq!(add(-1, 1), 0);362/// ```363pub fn add(a: i32, b: i32) -> i32 {364    a + b365}366 367/// Parses a config string.368///369/// # Errors370///371/// Returns `Err` if the input is not valid TOML.372///373/// ```no_run374/// use my_crate::parse_config;375///376/// let config = parse_config(r#"port = 8080"#).unwrap();377/// assert_eq!(config.port, 8080);378/// ```379///380/// ```no_run381/// use my_crate::parse_config;382///383/// assert!(parse_config("}{invalid").is_err());384/// ```385pub fn parse_config(input: &str) -> Result<Config, ParseError> {386    todo!()387}388```389 390## Benchmarking with Criterion391 392```toml393# Cargo.toml394[dev-dependencies]395criterion = { version = "0.5", features = ["html_reports"] }396 397[[bench]]398name = "benchmark"399harness = false400```401 402```rust403// benches/benchmark.rs404use criterion::{black_box, criterion_group, criterion_main, Criterion};405 406fn fibonacci(n: u64) -> u64 {407    match n {408        0 | 1 => n,409        _ => fibonacci(n - 1) + fibonacci(n - 2),410    }411}412 413fn bench_fibonacci(c: &mut Criterion) {414    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));415}416 417criterion_group!(benches, bench_fibonacci);418criterion_main!(benches);419```420 421## Test Coverage422 423### Running Coverage424 425```bash426# Install: cargo install cargo-llvm-cov (or use taiki-e/install-action in CI)427cargo llvm-cov                    # Summary428cargo llvm-cov --html             # HTML report429cargo llvm-cov --lcov > lcov.info # LCOV format for CI430cargo llvm-cov --fail-under-lines 80  # Fail if below threshold431```432 433### Coverage Targets434 435| Code Type | Target |436|-----------|--------|437| Critical business logic | 100% |438| Public API | 90%+ |439| General code | 80%+ |440| Generated / FFI bindings | Exclude |441 442## Testing Commands443 444```bash445cargo test                        # Run all tests446cargo test -- --nocapture         # Show println output447cargo test test_name              # Run tests matching pattern448cargo test --lib                  # Unit tests only449cargo test --test api_test        # Integration tests only450cargo test --doc                  # Doc tests only451cargo test --no-fail-fast         # Don't stop on first failure452cargo test -- --ignored           # Run ignored tests453```454 455## Best Practices456 457**DO:**458- Write tests FIRST (TDD)459- Use `#[cfg(test)]` modules for unit tests460- Test behavior, not implementation461- Use descriptive test names that explain the scenario462- Prefer `assert_eq!` over `assert!` for better error messages463- Use `?` in tests that return `Result` for cleaner error output464- Keep tests independent — no shared mutable state465 466**DON'T:**467- Use `#[should_panic]` when you can test `Result::is_err()` instead468- Mock everything — prefer integration tests when feasible469- Ignore flaky tests — fix or quarantine them470- Use `sleep()` in tests — use channels, barriers, or `tokio::time::pause()`471- Skip error path testing472 473## CI Integration474 475```yaml476# GitHub Actions477test:478  runs-on: ubuntu-latest479  steps:480    - uses: actions/checkout@v4481    - uses: dtolnay/rust-toolchain@stable482      with:483        components: clippy, rustfmt484 485    - name: Check formatting486      run: cargo fmt --check487 488    - name: Clippy489      run: cargo clippy -- -D warnings490 491    - name: Run tests492      run: cargo test493 494    - uses: taiki-e/install-action@cargo-llvm-cov495 496    - name: Coverage497      run: cargo llvm-cov --fail-under-lines 80498```499 500**Remember**: Tests are documentation. They show how your code is meant to be used. Write them clearly and keep them up to date.