Good vs Brittle Unit Tests

"Test behaviour, not implementation. The user of your code — including future you — never once asked how it works inside." — a lesson every engineer learns the second time they refactor

Somewhere in your career, usually on a Friday, you will do everything right and still get punished. You will rename a private helper, split one function into two, or swap a for loop for a .map() — a change that alters nothing a caller could ever observe — and forty tests will turn red. You didn't break the code. You broke the tests. And in that moment you will feel the specific, radicalising fury that turns engineers off testing for years: the suite that was supposed to protect you just mugged you instead.

That experience is not an argument against testing. It is an argument against bad testing. There is a real, teachable, unglamorous craft to writing unit tests that catch genuine regressions and stay silent through honest refactors — tests that behave like a smoke detector (screaming only when there's actually fire) rather than a car alarm (screaming when a leaf lands on the bonnet). This chapter is that craft. It is the foundation everything else in Part II stands on, because a matcher you don't understand or an edge case you forgot matters far less than the single decision that separates a suite you trust from a suite you learn to ignore: what, exactly, are you asserting about?

You have already tested code informally throughout this Library — the slugify you hardened in the JavaScript volume (V1), the typed domain models you designed in the TypeScript volume (V2), the API handlers behind the Backend service in Volume 8. You've run things and eyeballed the output. Now we make it rigorous. And we start with the two questions that a surprising number of professional engineers never explicitly answer: what is a unit, and what am I actually allowed to test about it?

Core Concepts

What a "unit" actually is

Ask five engineers to define "unit" and you'll get five answers: a function, a class, a method, a file, a module. They're all reaching for the same intuition and all slightly missing it. A unit is a unit of behaviour, not a unit of code. It is the smallest piece of your system that does something meaningful and observable from the outside — one rule, one decision, one transformation. It might be implemented as a single pure function. It might be a class with three collaborating methods. It might be two small functions that only make sense together. The code boundary is negotiable; the behaviour boundary is the point.

This distinction is not pedantry — it decides everything downstream. If you believe a unit is "one function," you will write one test per function, including the tiny private helpers, and you will couple your tests to your internal decomposition. Then the day you inline a helper or rename it, its tests have nowhere to live and they die screaming. If instead you believe a unit is "one behaviour," you test the public thing the outside world calls, let it exercise its private helpers as a side effect, and you are free to reorganise the insides however you like.

Here is the working definition to carry for the rest of your life: a unit test verifies one behaviour of a unit through its public interface, with everything slow or unpredictable held still. "Public interface" is the load-bearing phrase. It's the contract — the inputs a caller passes and the outputs and effects a caller observes. Everything on the other side of that contract is implementation, and implementation is precisely the thing you are allowed to change without telling anyone.

Behaviour versus implementation — the whole ballgame

Every function has two sides. There is what it promises — "give me a list of prices and I'll give you the total with tax" — and there is how it keeps the promise — the loop, the accumulator variable, the intermediate Math.round, the helper it delegates to. Callers depend on the promise. Only the code itself depends on the how.

A good test asserts against the promise. A brittle test asserts against the how. That's it. That's the entire chapter in one sentence, and everything else is elaboration and evidence.

Watch it happen on a concrete function. Suppose you're building the checkout logic for a store — the kind of cart you'll test end-to-end much later in this volume, but here reduced to its core rule.

Those three tests describe the contract. Notice what they never mention: reduce, subtotal, Math.round, the accumulator. They pass sample carts through the front door and check what comes out the front door. Tomorrow you could rewrite cartTotal with a plain for loop, precompute tax differently, or extract a lineTotal helper — and as long as the promise holds, all three stay green. They are coupled to behaviour, and behaviour is what you were hired to preserve.

Now watch the same function tested badly.

The brittle version passes today, and that is exactly why it's dangerous — green tests feel like safety. But it has welded itself to details no caller cares about. Rewrite cartTotal as a for loop and the reduce spy fails, even though every customer still gets the right total. The test now punishes correct refactors and rewards leaving bad code alone. Multiply that by a thousand tests and you understand why some teams are terrified to touch their own codebase: the tests have quietly become handcuffs.

Coupling to internals is the root evil

Every brittle test traces back to a single sin: coupling to internals. The test knows something it shouldn't — a private method name, an intermediate variable, the number of times an inner helper is called, the exact shape of a data structure the caller never sees. Coupling is what makes a test break on a change that changed nothing observable, because the test was watching the internals and the internals moved.

There's a precise way to see this. A test creates a dependency from the test onto whatever it asserts about. Assert on the public interface and you depend only on the contract, which is stable by definition — that's what "contract" means. Assert on the internals and you depend on the implementation, which is supposed to change; that's what refactoring is. You have coupled a stable thing to a volatile thing and then act surprised when the volatile thing shakes it loose.

This is why over-mocking (which you'll study properly in Part III) is so often a brittleness factory. The moment you mock a collaborator and then assert "it was called exactly twice with these arguments," you've frozen an interaction detail. If the real code can satisfy its contract by calling the collaborator once, or three times, or with reshaped arguments, your test now forbids a correct implementation. Mocks are sometimes necessary — a unit that sends real emails or charges real cards must be isolated — but every mock is a small bet that a particular interaction is part of the contract. Bet only when it truly is.

The counter-discipline has a name in the literature: test through the public API, and treat the unit as a black box wherever you can. The blacker the box, the freer you are inside it. When you find yourself needing to reach past the interface to test something, that's usually a design signal — the thing you want to verify wants to be public, i.e. it wants to be its own unit with its own front door. You'll feel this pull most sharply in Part IV, where TDD uses exactly this pressure to shape better designs.

The false economy of "testing everything"

New engineers, taught that testing is virtue, sometimes conclude that more assertions are more virtue, and start asserting on everything in sight — every field, every intermediate, every call. This is the road to brittleness paved with good intentions. A test suite is not measured by how much it asserts; it's measured by how much real breakage it catches per false alarm it raises. A suite that screams at every refactor has a terrible signal-to-noise ratio, and humans respond to noisy alarms in exactly one way: they stop listening.

Good tests catch real regressions

Everything so far might read as "assert less" — but that's only half the craft, and the dangerous half if taken alone. The point of a test is to catch a real regression the instant it appears. A suite that never breaks is as useless as a smoke detector with the battery removed: blissfully quiet, and no protection at all. The art is asserting on exactly the behaviour that matters — no less (or you miss real bugs) and no more (or you drown in false alarms).

A regression is a behaviour that used to be right and silently became wrong. The right test is the one that goes red the moment the promise is broken and stays green through every honest reshuffle of the how. Let's prove both halves in one runnable block: the robust test survives a refactor and still catches a genuine bug.

Run it. The refactor (V2) passes untouched — the tests didn't even notice the internals moved. And the genuine bug (applyDiscountBuggy) fails loudly: 10% off 1000 returns -9000 instead of 900, and the failure message tells you precisely what broke. This is a good test. It is deaf to how the code is written and hair-triggered on what the code does. Silent through refactors, screaming through regressions — the two properties that make a suite worth keeping.

FIRST — the five properties of a test you can trust

There is a well-worn mnemonic for the qualities of a good unit test, and it's worn for a reason. FIRST: Fast, Isolated, Repeatable, Self-validating, Timely. It's easy to recite and hard to live, so let's take each one as an engineering constraint, not a slogan.

Fast is not vanity. A unit test that finishes in 40 milliseconds gives you feedback faster than you can form the next thought, which is why you'll actually run it — before every commit, in a watch loop, constantly. A suite that takes ten minutes gets run once a day, and a test you don't run protects nothing. Speed is what keeps the safety net in your hands instead of in a nightly CI job you've stopped reading.

Isolated means no test may depend on another test's leftovers or on the order tests happen to run in. Each test arranges its own world, acts, asserts, and cleans up — so that running one test, or all of them, or a random third of them, gives identical results. The moment test B only passes because test A ran first, you have a suite that fails mysteriously the day someone adds a test in the middle, and "mysterious" is the most expensive word in testing.

Repeatable is the property whose violation does the most damage, because its failure mode is the flaky test — one that passes and fails on the same code depending on the clock, a random value, the network, or timezone. Flakiness is poison not because it's occasionally wrong but because it teaches your team to shrug at red. Once "oh, that one's just flaky" enters the vocabulary, the next red — the real one — gets the same shrug, and a genuine bug sails into production behind the cover of learned indifference. A flaky test is worse than a deleted one. Anything that touches time, randomness, or the outside world is where repeatability goes to die, and it's exactly where the test doubles of Part III earn their keep.

Self-validating means the test decides pass or fail by itself, with a real assertion — no human squinting at printed output to judge whether it "looks right." If a person has to interpret the result, it isn't a test; it's a chore that will be skipped. And Timely means you write the test close in time to the code, ideally alongside or (in TDD) just before it — because "I'll add tests later" is one of engineering's most reliable lies. Later, the context is gone, the deadline is closer, and the untested code has already shipped a bug.

Hold FIRST and the behaviour-versus-implementation rule together and you have the whole philosophy of Part II in a single frame: test observable behaviour, keep the volatile world held still, and make failure fast, deterministic, and loud. Everything remaining in this Part — matchers, edge cases, parametrisation, coverage — is technique in service of that philosophy.

Common Mistakes

• Testing private methods directly. If you're reaching for a private helper to test it in isolation, you've coupled your test to internal structure that refactoring will move. Fix: test the private behaviour through the public method that uses it; if it feels too important to test only indirectly, that's a design smell telling you it wants to be its own public unit.
• Asserting on call counts and argument shapes of mocked collaborators. expect(mock).toHaveBeenCalledTimes(2) freezes an interaction detail that isn't part of the contract. Fix: assert on the outcome the collaborator produces, not the choreography of getting there; reserve interaction assertions for genuine contract points (e.g. "the payment gateway was charged exactly once").
• Snapshotting everything. Giant snapshot tests capture entire rendered structures, so any cosmetic change turns them red and everyone just re-runs --update without reading the diff. Fix: assert on the specific text or values that matter; use snapshots sparingly and only for output that's genuinely meant to be pinned.
• One test that asserts fifteen things. When a mega-test fails, you can't tell which behaviour broke, and it usually fails for a reason unrelated to what you changed. Fix: one behaviour per test, named for that behaviour, so a red result reads like a sentence.
• Coupling to data-structure shape the caller never sees. Asserting on an internal cache's exact keys or an intermediate array's order breaks the moment you optimise storage. Fix: assert only on what the public interface exposes.
• Chasing a coverage number instead of catching bugs. Adding assertion-free tests to turn a line green is theatre; you'll meet this trap head-on in the coverage chapter. Fix: aim tests at behaviour that could plausibly break, not at colouring the coverage report.
• Depending on test order or shared fixtures. A test that only passes after another mutated a shared object is a time bomb. Fix: each test builds its own fixtures in beforeEach; never let state leak between them.

Interview Corner

Hands-on

Summary

• A unit is a unit of behaviour, not a unit of code — the smallest observable rule, tested through its public interface.
• Test the promise, not the how. Assert on inputs and outputs a caller can see; never on private helpers, intermediate state, or the internal shape of things.
• Coupling to internals is the root evil. Every brittle test is a stable thing (the test) welded to a volatile thing (the implementation), so it breaks on refactors that changed nothing observable.
• A good test is silent through refactors and loud through regressions — deaf to how the code is written, hair-triggered on what it does.
• More assertions is not more virtue. A suite is measured by real breakage caught per false alarm raised; noisy suites train people to ignore red.
• FIRST — Fast, Isolated, Repeatable, Self-validating, Timely — are the properties of a test you can actually trust, and Repeatable (no flakiness) is the one whose violation does the most damage.
• Over-mocking is a brittleness factory: every mock bets that an interaction is part of the contract, so bet only when it truly is.

You now know what to assert about — behaviour through the public interface — but not yet the full vocabulary for how to say it. toBe or toEqual? How do you check a float without exact equality, a thrown error, a substring, or the negation of any of these? The next chapter, Assertions & Matchers, hands you the whole toolbox and shows you which tool the failure message thanks you for choosing.