Beyond assert!(matches!(...)): Inside Rust 1.96.0's Stabilized assert_matches! Revolution

Every Rust developer has experienced the frustration of a late-night CI failure. You open the logs, only to be met with a generic error:

thread 'tests::test_status' panicked at 'assertion failed: matches!(s, Status::Ok)'

What was the actual value of s? The compiler doesn't tell you. To find out, you either had to rewrite the test locally using the dbg! macro or bloat your Cargo.toml with third-party testing assertions.

With the stable release of Rust 1.96.0, this long-standing ergonomic headache is officially over. The stabilization of the assert_matches! and debug_assert_matches! macros introduces native, highly informative pattern-matching assertions directly to the standard library.

The Diagnostics Gap: Old vs. New

Historically, asserting that an enum matched a specific variant required combining assert! with the matches! macro. Look at the following classic scenario:

#[derive(Debug)]
enum Status {
    Ok,
    Pending,
    Failed(u32),
}

let s = Status::Failed(404);
assert!(matches!(s, Status::Ok)); 

Because assert!(matches!(...)) only evaluates a boolean result, the panic message is entirely uninformative.

Rust 1.96.0 fixes this by introducing assert_matches! under core::assert_matches and std::assert_matches:

use std::assert_matches::assert_matches;

let s = Status::Failed(404);
assert_matches!(s, Status::Ok);

When this assertion fails, the macro formats the evaluated expression and prints its Debug representation:

panic: assertion `left matches right` failed
  left: Failed(404)
  right: Status::Ok

Advanced Matching and Pattern Guards

Because assert_matches! leverages Rust’s native match engine, it supports the full spectrum of pattern-matching features. You can bind variables from matched patterns and utilize pattern guards to perform conditional checks on the inner data:

use std::assert_matches::assert_matches;

let result: Result<u32, &str> = Ok(5);

// Asserts the result is Ok AND contains a value greater than 10
assert_matches!(result, Ok(x) if x > 10);

If this fails, the error message seamlessly displays the mismatched structure, saving you from writing verbose boilerplate.

Why Isn't It in the Prelude?

You might wonder why you need to write use std::assert_matches::assert_matches; explicitly.

The Rust compiler team chose not to include these macros in the standard prelude. For years, the third-party assert_matches crate has been a massive dependency staple, with tens of millions of downloads. Adding the macro to the prelude would have introduced widespread namespace collisions and broken existing codebases globally.

Additionally, the release ships with debug_assert_matches!, which operates identically but compiles away in release builds—perfect for safety-critical assertions that shouldn't impact production performance. It is time to audit your dev-dependencies, strip out legacy crates, and embrace native pattern assertions!