Tests Are Documentation That Runs

August 10, 2026 · Engineering · Michael Marquez

Back to Michael's Crumbs

I used to think of tests mainly as a safety net, something that catches regressions before a customer does. That is still true, but it undersells what a good test suite actually does. A test is documentation that cannot lie to you. A comment describing what a function does can go stale the moment the function changes underneath it. A test describing the same thing fails the moment that happens, loudly, in a way nobody can ignore.

This matters more now than it used to, because AI generated code changes fast and comments generated alongside it are exactly as unreliable as any other comment, maybe more so, since they read as confident regardless of whether they are still true. A test suite does not have that problem. It either passes against the current behavior or it does not.

What I actually test for

I am less interested in coverage percentage than in whether the tests describe the behavior a future engineer, human or AI, actually needs to know before changing this code safely. That usually means testing the edge cases and the invariants, not just the happy path. What happens with an empty input. What happens when two requests arrive at the same time. What is not allowed to happen no matter what.

When I hand AI a task now, one of the first things I ask for is the tests, often before the implementation. It changes the conversation from what should this code do into what should never happen, which is usually the more important question.