Testability as a design property

Why is code that is hard to test usually badly designed rather than just hard to test?

You sit down to write a test for a function and find you cannot. Not that the test fails — you cannot even get to the point of running it. To call the function you must first stand up a database, set an environment variable, and let it reach the network. The natural reaction is annoyance at testing: the tools are awkward, the harness is clumsy, this is overhead.

But hold that reaction up to the light for a moment. Nothing about writing a test changed the code. The difficulty was already there, sitting in the code, before anyone thought about testing it. So what exactly did the attempt to test reveal?

Ask what a test actually requires. Only three things: you must be able to put the code in a known starting condition, run it, and observe what happened. That is all. Now notice that each of those is a requirement about the code's relationship with the rest of the world, not about testing at all.

Take the first. To put code in a known condition you must be able to construct it without dragging half the system along. If creating one object requires four collaborators, each requiring three more, you have discovered that the object cannot exist independently of them. That is not a testing fact. It is a fact about coupling, and it applies just as much to a developer trying to reuse the object elsewhere, or to reason about it in isolation while fixing a bug.

The second: running it. Suppose you can only reach the interesting behaviour through five layers of unrelated machinery — an HTTP route, a session, a template. Then the interesting behaviour has no seam of its own. What does that tell you about someone who wants to call that logic from a scheduled job instead of a web request?

And the third: observing the result. If the function returns nothing and its only effect is a row written somewhere far away, then to check it you must go looking. Ask why that is uncomfortable. It is uncomfortable because the effect is invisible at the point of the call — which means anyone reading the calling code cannot see what it does either.

Do you see what has happened? Every complaint about testability turned out to be a restatement of an ordinary design complaint: too much coupling, no clear seam, hidden effects, too many responsibilities in one place. Testing did not create these; it forced us to meet them, because a test is simply the first client of the code that is not embedded in the running system, and so the first one that cannot paper over the dependencies by inheriting them from context.

That is the honest way to put the claim. Testability is not a separate virtue that good code happens to have. It is a proxy — a cheap, mechanical signal that detects properties we already wanted but that are otherwise hard to measure. We have no dial for "well-coupled." We do have "can I instantiate this in three lines."

And a proxy deserves the scepticism proxies always deserve. Two caveats matter. First, the signal is not perfect: some code is genuinely hard to test for reasons unconnected to its design — a GPU kernel, a hardware driver, a distributed timing behaviour. Difficulty there is intrinsic, not a smell. Second, and more common in practice, optimising for the proxy rather than the property produces its own damage: interfaces invented for no reason but to allow a mock, indirection layers with one implementation each, a design shredded into fragments that are individually testable and collectively incomprehensible. Chasing the measurement instead of the thing measured is a real failure mode, not a hypothetical one.

Notice this reframes the usual argument. "We do not have time to write tests" is generally heard as a claim about testing effort. Read through the lens above, it often means something else: the code is shaped so that testing it is expensive, and that shape is charging a toll on every other activity too — onboarding, debugging, changing a requirement — only those tolls are not itemised anywhere.

It also explains why writing the test first tends to produce different code. If you must call the thing before it exists, you are forced to design its interface from the outside, as a caller experiences it, rather than from the inside outward. That is why test-driven development has a design effect at all, and it is a real one, though the empirical literature on whether it improves defect rates and productivity is genuinely mixed — the strong claims made for it outrun the evidence.

One correction worth making explicitly: none of this says untestable code is wrong. It says untestable code is telling you something, and it is worth listening before deciding. Sometimes the answer really is "this is a thin adapter over a vendor API, there is nothing to isolate, we will cover it at integration level." Fine. That is an informed decision. The failure is not making one.

• Where the signal legitimately fails: concurrency, hardware, and timing-dependent behaviour.
• The difference between a mock, a stub, and a fake, and why over-mocking couples tests to implementation.
• Why integration and end-to-end tests trade this design pressure away for realism.

Every term the collection defines is gathered in the glossary.