i've stopped using assertion libraries in rust

nerd alert. if you don't write rust, this post is still about something — namely, the moment you adopted a third-party library that solved the wrong problem. the rust is incidental. the trap is not.

i stopped using assertion libraries after writing nine rust crates. five used pretty_assertions or a snapshot library. four didn’t. the four without were better — and the difference wasn’t the libraries. it was what i wanted a test failure to do.

what the libraries actually do

pretty_assertions rewrites the default assert_eq! to show a side-by-side diff of the two values when they don’t match. you get expected: [1, 2, 3] and actual: [1, 2, 4] with a clear visual highlight of the difference. without it, you get assertion failed: left == right and a six-line debug dump. that is a real improvement. nobody’s arguing it isn’t.

other libraries go further. snapshot assertion, structured diffs, colour-coded output. some of them are genuinely nice to read for specific kinds of failure.

so why did i stop using them?

the workflow problem

the technical cost is small. pretty_assertions is one crate, no transitive deps. the binary-size cost is real but small. compile-time cost is bigger — pretty_assertions macros pull formatting code into the test build, and on every crate where i tried it, the debug build got noticeably slower. if you have a crate with thousands of test assertions, the build slows down.

the cost that bit me was what got coupled to the dependency over time. every test that did use pretty_assertions::assert_eq; was a test that wouldn’t compile on a contributor’s machine if the dependency wasn’t vendored. every snapshot-style test was a test that needed a snapshot update when the test changed. the libraries don’t just print better output — they bring a workflow. if you adopt the library, you adopt the workflow.

i’d rather have a workflow i can throw away.

what the failure is actually for

the thing the libraries optimize for is reading the failure. that’s the most pleasant thing about them: you write a test, it fails, you see exactly what’s wrong, you fix it. the loop closes fast. the libraries make a hard moment easier.

but i kept noticing that the moment the test fails is rarely the moment the bug lives. the test fails, you look at the diff, you fix the assertion, the test passes, you ship. then the next bug shows up. and the next. and the next. the pretty diffs are good for the part of the debugging where the failure is itself the answer. they’re irrelevant to the rest of it.

what actually closes a debugging loop is: the failing test, the log output from the code under test, and — most importantly — a re-run. a deterministic test that fails, plus enough context in the log to know what state the program was in, is worth ten pretty diffs. the libraries optimize for the wrong moment.

what i do instead

i write a 6-line helper function that prints whatever i want for failures. usually: the assertion, the line number, the values, and a tag. for example:

fn check<T: std::fmt::Debug>(label: &str, expected: &T, actual: &T) {
    if expected != actual {
        eprintln!("\n  [{}]", label);
        eprintln!("  expected: {:#?}", expected);
        eprintln!("  actual:   {:#?}", actual);
        panic!("assertion failed ({}); see above", label);
    }
}

pretty_assertions is one macro. this is one function. the function has zero dependencies, zero compile-time overhead, and gives me most of what the libraries give me. what i lose is automatic color-coding and snapshot support. i don’t need either.

the function also does one thing the libraries don’t: it puts a label on the failure. assert_eq!(left, right) tells you “something wasn’t equal.” check("scoring weights", &left, &right) tells you “the scoring weights weren’t equal.” when a test fails, the label is the first thing i want. it’s not a comparison, it’s a position in the system i’m checking. the libraries don’t have a slot for that.

when i’d pick it back up

i will grant that for some test suites, the dependency is the right call. if you’re testing something that produces deeply nested, structurally complex output — protocol buffers, ASTs, big json documents — the diff view is genuinely the only way to read a failure in a reasonable amount of time. the libraries are tools. the problem is when they become defaults.

for code that checks “does this function return the right thing for this input,” the dependency is mostly aesthetic. you’re not diffing. you’re checking. assert_eq! with one helper function is enough.

so i stopped. five crates of “let me try this again with pretty_assertions” went back to plain assert_eq! plus the helper. the build is faster. the test failures are uglier. the debugging loop is unchanged, because the loop never depended on the pretty diff in the first place.

the principle

a test failure should tell you where the bug is, not what the bug looks like. where is expected: {:#?}\nactual: {:#?}. what is “go look at the state, read the logs, run it again.” libraries optimize for the second. i want the first.

if i ever pick pretty_assertions back up, it’ll be for one specific crate with one specific kind of test. not as a default. defaults shape your day. i’d rather have a workflow i can throw away. that’s the part nobody’s selling me.