Rust Testing Practice: #[test], assert!, Unit & Integration Tests

The -- separates cargo flags from test runner flags. Everything after -- goes to the test binary.

The test module is a child scope — it cannot see the parent's items without importing them:

fn add(a: i32, b: i32) -> i32 { a + b }

// WRONG: test can't find add()
// #[cfg(test)]
// mod tests {
//     #[test]
//     fn test_add() {
//         assert_eq!(add(2, 2), 4);  // error[E0425]: cannot find function
//     }
// }

// RIGHT: import from parent module
#[cfg(test)]
mod tests {
    use super::*;

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

use super::*; imports everything from the parent module. Add it as the first line inside mod tests.

Integration tests in tests/ are external crates — they can only see your public API:

// src/lib.rs
fn internal_helper() -> i32 { 42 }  // private
pub fn public_api() -> i32 { internal_helper() }

// tests/integration_test.rs
// WRONG: private items are not visible
// use my_crate::internal_helper;  // error[E0603]: function is private

// RIGHT: test the public API
use my_crate::public_api;

#[test]
fn test_api() {
    assert_eq!(public_api(), 42);
}

If you need to test internal logic, use a unit test inside the source file instead. Visibility rules determine what integration tests can access -- see modules and crates for details on pub, pub(crate), and module structure.

#[test] functions must return a type that implements Termination: either () or Result<(), E> where E: Debug:

// WRONG: i32 doesn't implement Termination
// #[test]
// fn test_parse() -> i32 {
//     "42".parse().unwrap()
// }

// RIGHT: return Result to use ? in tests
#[test]
fn test_parse() -> Result<(), Box<dyn std::error::Error>> {
    let n: i32 = "42".parse()?;
    assert_eq!(n, 42);
    Ok(())
}

Returning Result lets you use ? instead of .unwrap() chains, and the error message on failure is more informative. The error handling guide covers the ? operator and Result combinators in depth.

Unit Tests

Go inside the source file in a #[cfg(test)] mod tests block. Can test private functions:

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

    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }
}

#[cfg(test)] means this code is only compiled when running tests — it stays out of production builds. The error handling cheat sheet is a useful companion when writing assertions and test helpers.

Integration Tests

Live in the tests/ directory at the crate root. Each file is compiled as a separate crate:

// tests/integration_test.rs
use my_crate::public_function;

#[test]
fn test_public_api() {
    assert!(public_function());
}

Sharing Code Between Integration Tests

Each file in tests/ is a separate crate, so sharing helpers requires a module:

// tests/common/mod.rs  (must use mod.rs style, not common.rs)
pub fn setup() -> TestContext {
    // shared setup code
}

// tests/integration_test.rs
mod common;

#[test]
fn test_with_setup() {
    let ctx = common::setup();
    // ...
}

The Binary Crate Gotcha

Integration tests import your crate with use my_crate::..., which only works for library crates (src/lib.rs). If your project is binary-only (src/main.rs), move testable logic into src/lib.rs and have main.rs call into it.

Doc Tests

Code examples in doc comments run with cargo test:

/// Adds two numbers.
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 { a + b }

Doctest attributes control compilation and execution:

Testing panics — expected does a substring match on the panic message:

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

Ignored tests with reason:

#[test]
#[ignore = "requires database connection"]
fn expensive_test() {
    // run with: cargo test -- --ignored
}

Custom assertion messages — add context to failures:

#[test]
fn test_bounds() {
    let val = compute();
    assert!(val > 0, "expected positive value, got {val}");
    assert_eq!(val, 42, "compute() should return 42, got {val}");
}

• The Rust Book: Testing — unit, integration, and doc tests
• The Rust Book: Test Organization — cfg(test), tests/ directory
• Rust By Example: Testing — practical test patterns
• Rustdoc: Documentation Tests — doctest attributes and syntax