Verification of Unsafe Invariants

In this lesson, you will learn how to build automated test suites that confirm your unsafe code blocks maintain their required memory invariants.

When you use unsafe in Rust, you are essentially promising the compiler that you have upheld specific conditions (invariants)—such as ensuring a pointer is non-null, properly aligned, or that data remains initialized. Because the compiler cannot check these promises for you, it is your responsibility to verify them through rigorous testing.

Testing Invariants with Miri

The most powerful tool for verifying unsafe invariants is Miri, a specialized interpreter for Rust that detects undefined behavior. To test your invariants, you should write standard unit tests and execute them with cargo miri test.

Consider a custom RawBox that manages a raw pointer:

struct RawBox<T> {
    ptr: *mut T,
}

impl<T> RawBox<T> {
    // Safety: ptr must be non-null and allocated
    unsafe fn new(val: T) -> Self {
        let ptr = Box::into_raw(Box::new(val));
        Self { ptr }
    }
}

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

    #[test]
    fn test_raw_box_memory_alignment() {
        unsafe {
            let rb = RawBox::new(42);
            // Verify our invariant: the pointer must be aligned to the type
            assert_eq!(rb.ptr as usize % std::mem::align_of::<i32>(), 0);
            drop(Box::from_raw(rb.ptr));
        }
    }
}

Designing Safety-Focused Test Suites

When writing these tests, follow three rules:

1. Stress the Boundary: Use tests to feed your unsafe blocks edge-case inputs (like zero-length buffers or unaligned pointers) to see if your checks catch them.
2. Use Sanitizers: Always run tests under Miri. If your unsafe logic violates an invariant (e.g., a buffer overflow), Miri will halt execution and point to the exact line where the contract was broken.
3. Assert Assumptions: Even if your code compiles, use debug_assert! inside your unsafe blocks to document and check invariants during development builds. This transforms silent memory corruption into loud, observable panics.

By treating your invariants as testable requirements rather than just "implied rules," you turn the invisible risks of unsafe code into verified program properties.

Key Takeaway: Never assume your unsafe invariants hold; use debug_assert! for runtime documentation and execute your test suite with Miri to programmatically prove your memory safety claims.