liveBook · Manning

Architectural testing

As explained in Clean Applications with Hexagonal Architecture

Architectural testing automatically checks whether a codebase conforms to specified structural and dependency rules.

Maven can block dependencies between modules, but it cannot catch every forbidden relationship between classes on a shared classpath. Architectural testing makes those structural boundaries executable: ArchUnit checks compiled code at test time, and violations fail the build. section 7.0

Rules can constrain which layers depend on one another, where annotations appear, and how classes are shaped or named. Keep rule logic in checkers and use thin test classes to wire each checker to the packages it scans. section 7.0 section 7.7.1

A useful rule set can enforce:

  • Layer-specific dependency allowlists, such as keeping the domain independent of application and adapter layers. section 7.3
  • Structural requirements for commands, queries, ports, and handlers, including allowed annotations and naming patterns. section 7.0 section 7.7.2

Freezing existing violations can prevent new ones while a codebase improves incrementally; it is a migration aid, not acceptance of architectural drift. Architectural tests verify structure, while behavioral tests verify what components do, so one cannot replace the other. section 7.3 section 9.7

Table 7.2 Dependency rules by layer
Layer
Rule type
May depend on
Must NOT depend on
Checker class
shared-kernel
AllowList
JDK, Vavr, Lombok, Commons, itself
Everything else
SharedKernelChecker
domain
AllowList
Shared kernel + above
Application, adapters, DI framework
DomainChecker
input-ports
AllowList
Shared kernel, commands, queries
Domain, application, adapters
InputPortChecker
output-ports
AllowList
Shared kernel
Domain, application, adapters
OutputPortChecker
commands
AllowList
Shared kernel
Domain, application, adapters
CommandChecker
queries
AllowList
Shared kernel
Domain, application, adapters
QueryChecker
handlers
AllowList
Domain, ports, commands, queries, shared kernel, MapStruct
Adapters, DI framework
H andlerChecker
adapters
AllowList
Anything external
Domain, handlers (except @Repository impl)
A dapterChecker

Compare permitted and forbidden dependencies across the hexagonal layers. section 7.3

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Builds checks for dependencies, annotations, class shape, naming, configuration, and test wiring.
Examples
Uses layer dependency allowlists, annotation placement, command and query constraints, and naming conventions.
What it assumes
Assumes defined layer dependency rules and demonstrates translating them into executable checks.
What you can do after
Apply ArchUnit to enforce architecture rules as build-failing tests, with checkers wired to scanned packages.
How it connects
Connects ArchUnit checks with hexagonal architecture, Maven module boundaries, and behavioral testing.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.