ArchUnit
Java architecture testing library that validates architectural constraints as unit tests. ArchUnit imports Java bytecode and applies rule checks: no cycles between packages, layered architecture rules (controllers don't import repositories), naming conventions, annotation requirements, dependency restrictions, and custom rules. Rules run as standard JUnit 5 or JUnit 4 tests — architecture violations appear as test failures with detailed violation messages. Catches architecture drift before it becomes technical debt. Rules expressed in fluent DSL: classes().that().resideInPackage('..controller..').should().onlyDependOnClassesThat()...
Score Breakdown
⚙ Agent Friendliness
🔒 Security
No network exposure — purely local bytecode analysis. Can enforce security-related architectural rules: @Secured annotations required on agent REST endpoints, no direct crypto calls outside security package, sensitive data classes must not be logged.
⚡ Reliability
Best When
You're building a Java/Kotlin agent service with intentional architecture (layers, modules, clean architecture) and want to prevent gradual architecture erosion as the codebase grows.
Avoid When
Your codebase has no architectural conventions yet (define them first), you need runtime or behavioral testing, or you're enforcing code formatting (use Checkstyle/PMD).
Use Cases
- • Enforce layered architecture in Java agent services — ArchUnit test verifies agent controllers only depend on services, services only depend on repositories, preventing layer skipping
- • Validate agent module boundaries — ensure agent domain classes don't import infrastructure details; inner circle classes must not depend on outer ring classes (clean architecture enforcement)
- • Enforce naming conventions for agent code — all classes implementing AgentHandler must end in 'Handler', all Spring @Service classes must reside in 'service' package
- • Detect dependency cycles in agent codebase — ArchUnit cycle detection finds package cycles that indicate tangled design before they become impossible to untangle
- • Validate annotation usage patterns — ensure agent @RestController classes are annotated with @Validated, all agent event handlers use @TransactionalEventListener not @EventListener
Not For
- • Runtime behavior testing — ArchUnit analyzes bytecode statically; use integration tests for runtime behavior, security testing, or performance validation
- • Non-Java/Kotlin JVM languages — ArchUnit works on JVM bytecode but rules are expressed in Java; Kotlin users can write rules in Kotlin but some DSL expressions are awkward
- • Enforcing code style/formatting — use Checkstyle or ktlint for formatting; ArchUnit is for structural and architectural rules, not code style
Interface
Authentication
Testing library — no auth concepts. Tests run locally or in CI without external service dependencies.
Pricing
ArchUnit is Apache 2.0 licensed, maintained by TNG Technology Consulting. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ @AnalyzeClasses caching is critical for test suite performance — without @AnalyzeClasses at the test class level, ArchUnit re-imports all bytecode for each test method; large codebases can take 30+ seconds per test without caching
- ⚠ Package matching uses regex, not glob — 'com.agent..' means 'com.agent and all subpackages' (double dot); 'com.agent.' (single dot) means only the exact package; this differs from Gradle/Maven wildcards and causes silent rule mismatches
- ⚠ Inner classes require separate rule handling — ArchUnit's package rules apply to inner/anonymous classes separately; agent inner classes in 'wrong' packages fail layer rules unless explicitly excluded with .ignoreDependency()
- ⚠ Freeze architecture for gradual enforcement — ArchUnit FreezingArchRule stores current violations as 'allowed violations' and only fails on new ones; use this to enforce rules on new code without fixing all legacy violations at once
- ⚠ Third-party library classes are excluded by default — ArchUnit only analyzes YOUR classes by default; rules about dependencies on external libraries require explicit ClassFileImporter with EXCLUDE_JARS not set
- ⚠ Rule naming matters for CI visibility — unnamed rules show 'ArchRule' in test reports; always name rules with .as('Agent controllers should only...') to make CI failure messages actionable without reading rule code
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for ArchUnit.
Scores are editorial opinions as of 2026-03-06.