Lesson 17 · Senior v2 architecture

Testing the hexagon

How the architecture should make testing simpler: what to mock at each layer, what a healthy seam looks like, and how to review test strategy like an architect.

Your win: explain the repo’s layered mock strategy, why ports exist partly for testability, and how to tell whether a module’s seams are helping or hurting the test story.

In plain English Plain English: a clean architecture should make it obvious what to fake at each layer instead of forcing every test to boot the whole world.

The problem: bad seams make bad tests

When a module hides its real dependencies, uses concrete infra in the core, or mixes transport and business logic together, the testing pain shows up immediately. That pain is often the earliest signal that the architecture boundary is not doing its job.

The test rule to memorise Mock at the seam owned by the layer you are testing — repos for usecase tests, usecases for transport tests, DB behavior for repository tests.

What a healthy test story looks like here

Eureka’s conventions document makes the layering explicit. Spike and notification also reflect it in practice through handler dependencies declared as interfaces and thin controller layers. The deeper lesson is that testability is not a bonus after architecture — it is one way architecture proves it is real.

Anchor — what this means in the repo Repo docs explicitly spell out mock strategy by layer, constructor usage, and why interfaces should not drag concrete DB driver types upward. Those are architecture rules and testing rules at the same time.
Common mistake Talking about testability as “we can mock stuff” without being able to say which seam belongs to which layer and why.
Read this next

Eureka v2 conventions — mock strategy by layer

This is the clearest local articulation of the testing model behind the architecture.

→ .claude/rules/eureka-v2-conventions.md

Check yourself (from memory)

Q1. In a usecase test, the normal thing to mock is…

The usecase boundary should be expressed through repo interfaces or equivalent ports.
Why is testability evidence that the architecture boundary is real?
recall, then click to reveal
Because healthy seams make it obvious what to replace or fake at each layer without dragging in unrelated infrastructure.
Want me to turn one module into a test-seam review checklist? Ask me.

Sources. Eureka v2 conventions.