chapter eight
8 Testing the hexagon with behavioral verification
This chapter covers
- Understanding why hexagonal architecture makes testing mechanical
- Unit testing commands and queries through the validateThenCreate contract
- Unit testing handlers by mocking output ports
- Unit testing REST controllers by mocking the bus
- Unit testing adapters that interface with heterogeneous external systems
- Recognizing what not to test
We proved that WriteFlow's hexagon has the structural form. ArchUnit rules enforce dependency direction, annotation placement, structural contracts, and naming conventions. If a class violates the architecture, the build fails before anyone writes a test for it.
Shape is necessary but not sufficient. A handler that satisfies every structural rule—correct annotations, package, and generic signature—can still return the wrong result. A command that passes ArchUnit's validateThenCreate shape check can still accept invalid input. A controller that lives in the right adapter package can still return the wrong HTTP status. Structural verification proves the hexagon looks correct. Behavioral verification proves it works correctly.