Every Test Can Name Why It Exists
Four kinds of test, each derived from a property of the code
Most test strategies arrive as a shape. The pyramid: lots of unit tests, fewer integration tests, a handful of end-to-end. Seventy, twenty, ten. The proportions are the input, and your code is expected to conform to them.
This is the opposite. Start from what the code is, derive what the tests must be, and let the proportions come out wherever they come out.
Here is the whole strategy up front:
- Value object tests -- cover one type's invariant. No isolation needed; the thing is pure.
- Complex leaf tests -- cover one rule's decision space. No isolation needed; the thing is pure.
- Use case tests -- cover the composition: ordering, propagation, branching. Adapters stubbed, everything else real.
- Adapter contract tests -- cover success, failure, and the translation between worlds. Run against the real dependency.
Four kinds. Nothing else. The rest of this is where each one comes from, and why the list is not longer or shorter.
The one premise
Everything below follows from a single structural fact, and if your code does not have it, none of this applies.
The code is a set of typed steps, composed into use cases, with errors as values and I/O confined to adapters. A use case does not reach out to a database; it takes a step that does, and that step is a parameter. Failures do not throw; they travel back through the composition as values.
public interface RegisterUser {
Result<Response> execute(Request request);
static RegisterUser registerUser(CheckEmailUniqueness checkEmail,
CreateValidUser createUser,
SaveUser saveUser, // <- the only I/O in here
GenerateToken generateToken) { ... }
}
That shape is what makes the strategy derivable. Every decision below reads a property of it.
1. Value object tests
The code fact: a value object is pure and has zero dependencies. Email.email(raw) takes a string and returns a Result<Email>. There is nothing to stub because there is nothing to reach.
Therefore: test it directly. Not because unit tests are virtuous, but because isolation is free here -- there is no assembly to do and nothing to fake.
How many tests, though? That is the question people answer by habit, and habit is where the gaps come from. Count the decision space first, and let the count choose the shape:
- Small and enumerable -- a status enum, a three-way branch. Write examples: the space is the examples.
- A finite grid -- an enum against an enum, banded ranges. Write a table, one row per cell: the cell count is known, so a missing row is a hole you can see.
-
Unbounded -- any string, any
BigDecimal, any timestamp. State the invariant: four examples sample an infinite space as arbitrarily as one does.
Quantity accepting 1..100 is the first kind: boundary examples genuinely cover it.
Email is the third. Four malformed strings do not cover the space of malformed addresses; they cover four of them. The honest test states what the parser guarantees -- normalization is idempotent, nothing accepted violates the invariant -- which is what property-based testing libraries automate by generating inputs instead of listing them.
Do not use coverage to check yourself here. Four hand-picked strings reach 100% line coverage of Email. So would two. A metric that reports the same number for a careful suite and a lucky one is measuring the paths the code has, not the space it decides over.
2. Complex leaf tests
The code fact: most business leaves are trivial -- one calculation, one transformation -- and are exercised whenever the use case runs. A few are not.
Therefore: a leaf earns its own tests when the assembled use case cannot reach its decision space at a price worth paying.
Here is a real one. An order price calculator with three rules: a volume discount by item count, an order-value discount, a shipping rule that depends on the discounted total. Plus the rule that the two discounts do not stack -- the customer gets the better of them.
Three volume bands, two value bands, three shipping outcomes: eighteen combinations.
Two things fall out of that number, and both arrive before any test is written. First, three of the eighteen are impossible: an order over the large-order threshold, discounted by at most 10%, always clears free shipping, so a large order can never pay flat shipping.
That is a fact about the rules, and counting is how you find it. Second, the fifteen that remain want a table:
@ParameterizedTest
@CsvSource({
// unit, items, oversized, expected -- subtotal / volume / value / shipping
" 20.00, 5, false, 109.99", // 100 / none / low / flat
" 4.00, 25, false, 104.99", // 100 / 5% / low / flat
" 2.00, 50, false, 99.99", // 100 / 10% / low / flat
// ... twelve more
" 40.00, 25, false, 950.00", // 1000 / 5% vs 5%: equal, so no stacking
" 20.00, 50, false, 900.00", // 1000 / 10% beats 5%: volume wins
})
void calculate_computesTotal_acrossTheDecisionSpace(...) { ... }
Now compare that with testing the same fifteen through the use case. Each vector there needs six stubs, a request with lines and an address, and an await() -- roughly fourteen lines against one row. Two hundred lines of assembly to check a multiplication, and every failure reports "PlaceOrder failed" rather than naming the rule that broke.
The common heuristic -- three or more branches, write dedicated tests -- works. Keep it. Just know that it cannot see a decision expressed as data: a limit resolved by looking up two enumerations, seven types against five tiers, is thirty-five answers wrapped in four conditionals, and rates borderline on a branch count while being the most combinatorial rule in the system.
3. Use case tests
The code fact: the use case is a composition. Its steps are parameters. The only thing on the path that cannot run in a test is I/O, and I/O lives at adapters.
Therefore: assemble the whole use case, stub only the adapters, and test the behavior. The stub set is not a preference -- it is the minimum that makes the test runnable, and anyone with the same code would compute the same set.
@Test
void execute_fails_whenEmailAlreadyExists() {
CheckEmailUniqueness checkEmail = req -> EMAIL_ALREADY_REGISTERED.promise();
// remaining steps stubbed for success
useCase.execute(validRequest())
.await()
.onSuccess(Assertions::fail);
}
This is where behavior lives, so this is where most of the interesting tests are: happy path, each step's failure, each branch condition, error propagation through the chain.
Two rules make this level work, and both are easy to get wrong.
Assert on the outcome, except where the effect is invisible in it. A transfer that retried twice looks identical to one that never retried. A transfer that wrote an audit entry looks identical to one that dropped it. There, capturing the call is the only oracle that can see the behavior:
@Test
void execute_auditsSuccessfulTransfer() {
var audited = new ArrayList<AuditEntry>();
AuditLog auditLog = entry -> { audited.add(entry); return Promise.success(unit()); };
// ...
assertEquals(1, audited.size());
}
Everywhere else, capturing calls couples the test to the implementation for nothing. The rule is neither "avoid mocks" nor "verify interactions": assert on the effect where the effect is visible, and on the call only where it is not. That produces far fewer interaction assertions than a mock-first habit, and a firmly non-zero number, which a no-mocks rule gets wrong.
One composition test for propagation, N cheap vectors for the space. When validation lives in its own type, test it there -- that is where the vectors are cheap -- and keep exactly one use case test proving that a validation failure short-circuits the remaining steps. That fact is a property of the chain and exists nowhere else. Everything beyond it is duplication that breaks twice on every change.
4. Adapter contract tests
The code fact: an adapter is the one place two worlds meet. It converts a domain call into SQL or HTTP, and converts what comes back -- including exceptions -- into typed domain values.
Therefore: it needs tests against the real dependency, and it needs exactly three kinds: it succeeds, it fails the way the domain expects, and it translates a transport exception into a typed failure.
@Test
void findById_wrapsException_whenDatabaseFails() {
var repo = new JooqUserRepository(failingConnection(new SQLException("reset")));
repo.findById(SOME_ID)
.await()
.onSuccess(Assertions::fail)
.onFailure(cause -> assertInstanceOf(UserError.StorageUnavailable.class, cause));
}
This is the layer most often missing, and skipping it undermines everything above it. Every stub in every use case test is an assumption about a boundary: that the real adapter succeeds that way, fails that way, translates that way. Nothing in the use case tests checks any of it. The contract test is what makes the stub honest, and a suite of integration-first tests without contract tests is a suite whose stubs nobody has verified.
The third case is the one that matters most and the one usually absent. Translation is the adapter's entire job, and no use case test can reach it.
Why this is better than choosing a ratio
Every test can name why it exists. Not "we needed coverage" -- a property of the code put it there. That makes tests reviewable on a basis other than taste, and it makes deleting one a decision you can argue about with evidence.
The proportions become an output. You never argue about whether you have enough unit tests. You have as many as the pure-and combinatorial parts warrant, as many use case tests as the compositions warrant, and if that comes out diamond-shaped rather than pyramid shaped, that is information about your code, not a violation of a rule.
Nothing is tested twice. Each fact is tested where it lives: invariants in the type, decision spaces in the rule, propagation in the composition, translation in the adapter.
Duplication is what makes suites brittle, and duplication is what a shape-first strategy produces, because the shape does not know what is already covered.
Refactoring stops breaking tests. Tests assert on outcomes, and stubs sit at boundaries that only move when the architecture moves. Rename an internal method and nothing turns red.
Gaps become visible. A table with a known cell count shows its holes. A decision count gives you a target before you start. Neither line coverage nor a branch count can do that, because both measure the shape of the code rather than the size of what it decides.
What this needs from you, and what it does not
It needs the premise. If your business logic reaches out to a database directly, the stub set is not "the adapters" and the derivation does not run. Fixing that is a design change, not a testing change -- which is the honest answer, and also the useful one, since a branch you cannot reach in a test is usually telling you about a hidden dependency rather than about your test suite.
It does not need a new framework. Everything here is JUnit and parameterized tests, apart from the one place property-based testing earns its keep.
And it does not need the pyramid. Count what your code decides, put each test where the fact it checks actually lives, and let the shape fall out.
The structure assumed here -- typed steps, errors as values, use cases composed from small pieces, I/O confined to adapters -- is described in Java Backend Coding Technology, along with the worked examples the tests above are drawn from.
Top comments (0)