Unit Testing

Ignoring Tests

The #[ignore] attribute instructs cargo test to skip executing a #[test] function during normal test runs while still type-checking and compiling the test body so it never rots as surrounding APIs evolve.

#[test]
#[ignore = "requires live PostgreSQL instance on localhost:5432"]
fn migrations_apply_cleanly() { ... }
        |
        +-- Compiled during `cargo test`?  YES (type-checked every run!)
        +-- Executed during `cargo test`?  NO  (reported as `ignored`)
        +-- Executed with `--ignored`?     YES (`cargo test -- --ignored`)

Adding #[ignore] with an Explicit Reason

Always attach a descriptive reason string (#[ignore = "reason"]) explaining why the test is skipped by default—for example, because it takes several minutes to run, requires external hardware, or connects to an external staging service.

pub fn fast_hash(data: &[u8]) -> u64 {
    data.iter().fold(0xcbf29ce484222325u64, |acc, &b| {
        (acc ^ (b as u64)).wrapping_mul(0x100000001b3)
    })
}

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

    #[test]
    fn hashes_short_slice_quickly() {
        assert_ne!(fast_hash(b"hello"), fast_hash(b"world"));
    }

    #[test]
    #[ignore = "exhaustive 4 GiB collision scan takes ~45 seconds"]
    fn exhaustive_large_buffer_scan() {
        let buf = vec![0xAAu8; 1024 * 1024];
        assert_ne!(fast_hash(&buf), 0);
    }
}

fn main() {
    println!("Hash of 'hello': {:#x}", fast_hash(b"hello"));
}

Hash of 'hello': 0xa430d84680aabd0b

During a standard cargo test run, exhaustive_large_buffer_scan is compiled but skipped at runtime:

running 2 tests
test tests::exhaustive_large_buffer_scan ... ignored, exhaustive 4 GiB collision scan takes ~45 seconds
test tests::hashes_short_slice_quickly ... ok

test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s

Running Ignored Tests On Demand

The test harness provides two flags (placed after --) to run ignored tests in nightly CI jobs or pre-release checks:

Command Tests Executed
cargo test Only non-ignored tests (1 passed; 1 ignored).
cargo test -- --ignored Only tests marked with #[ignore].
cargo test -- --include-ignored All tests (both normal and #[ignore] tests together).
cargo test exhaustive -- --ignored Only ignored tests matching the filter "exhaustive".

Conditional Ignoring with #[cfg_attr(..., ignore)]

Combining #[cfg_attr] with #[ignore] allows a test to run normally on one platform or feature set while being marked ignored on others:

#[test]
#[cfg_attr(target_os = "windows", ignore = "uses Unix domain socket permissions")]
fn unix_socket_chmod_test() {
    assert!(true);
}

fn main() {
    println!("Conditional #[cfg_attr(..., ignore)] configured");
}

Conditional #[cfg_attr(..., ignore)] configured