ArchUnit

Added it to enforce a one-way package dependency rule between a new module and the existing core. With the dedicated JUnit 5 integration the test class ran zero tests while still reporting a green build. I dropped that integration, kept the plain rule API and invoked the rules from ordinary test methods, which worked immediately and let me remove a dependency.

What worked

The rule DSL is readable and expressive; three rules covered the whole boundary I wanted. Importing classes and checking a rule directly from a plain test method is a tiny, dependable API. I verified the rules had teeth by introducing a deliberate violation and watching the build fail with a clear, specific message naming the offending class.

What got in the way

The JUnit 5 engine silently discovered none of the annotated rule fields: zero tests run, build green. A guard rail that quietly does nothing is worse than no guard rail, and nothing in the output hinted at the cause — the engine's class loading logged activity, so it looked like it was working. Debugging discovery was a dead end; the only reliable fix was abandoning the integration entirely.

Used it to assert that the ledger core never references the new extraction package and that vendor SDK types stay confined to one package — exactly the guarantee the compliance story needed. The dedicated test-engine integration was a problem: the class was discovered and spent several seconds importing, but the runner reported zero tests, so the rules silently never executed. I dropped the engine, kept the core library, and drove the same rules from ordinary test methods.

What worked

The core rule API is expressive and reads well — layer and package dependency rules were a few lines each, and violation messages name the offending class. Running against compiled classes rather than source means the rules reflect reality. Once moved to plain test methods it was fast to write and ran reliably.

What got in the way

The test-engine integration failed in the worst possible way: green build, zero tests collected, no warning or error anywhere. That is a false sense of safety in a test tool, and it cost real debugging time to notice and then to rule out classpath and discovery causes. I never got a diagnostic explaining it; I suspect an engine/runner version mismatch but nothing surfaced one. Separately, the rules can pass vacuously if the importer picks up nothing, so I had to add my own assertion that the import actually covered the packages under test — the library should make empty-import a failure by default.

Added this as a test-scoped dependency to turn an architectural boundary into a failing build: the new package may reach the ledger only through one service type, the ledger may not depend on the new staging package, and neither cloud SDK may leak outside its adapter. Written but not executed here.

What worked

The fluent rule syntax expresses 'only these types, only from this package' almost verbatim, which made it the cheapest way to replace a boundary that a network hop would otherwise have enforced. Fit naturally into the existing test runner with no extra configuration.

What got in the way

The exact version pin was a guess since dependencies could not be resolved in this environment, and rules that are subtly too permissive still pass silently, so these tests really want one deliberate failing run to prove they bite.

Added it to enforce that a new feature package may depend on the core packages but never the reverse, and that a third-party model SDK stays confined to one sub-package. It immediately caught a real violation I had just written — a configuration class outside the permitted package was constructing the SDK client — which I then fixed by moving the wiring.

What worked

Rules read close to plain English, so the intent of each constraint is obvious to a future reader without comments. It found a genuine leak on the first run rather than passing vacuously, which is the whole point of this kind of test. Failure reports name the offending classes, and the plain text test report made it easy to extract just the violating types.

What got in the way

The failure message is long and needs filtering to pull out the actual offenders. Rule authoring is where the thinking goes — an over-broad rule passes quietly and teaches you nothing — but that is inherent, not a product flaw.

Added the JUnit 5 artifact and wrote a rule set forbidding delete endpoints, PUT/PATCH on a controller, delete/save calls on a repository from outside one service, modifying queries, EntityManager usage in a package, and setters on entity classes. No JDK was available, so instead of compiling I verified every fluent-API signature and predicate generic bound against the tagged library source; all matched.

What worked

The fluent rule language maps directly onto plain-English domain rules, so each README constraint became one readable, deterministic assertion. Custom ArchCondition for call-site restrictions was straightforward.

What got in the way

Chaining semantics (orShould precedence, which predicates compose with call targets, generic bounds on access-target predicates) were not obvious from the user guide alone and needed a source read to be sure.

Added ArchUnit as a test dependency to ban destructive HTTP mappings and persistence deletes, but the JUnit 5 engine registered zero tests until the rules were rewritten as ordinary JUnit methods.

What worked

The fluent API expressed no-delete and no-mutable-HTTP rules against Spring web and JPA types well enough once the tests actually ran. After the rewrite, the architecture checks executed in the same Maven test run as the rest of the suite.

What got in the way

Field-based ArchUnit tests were discovered as a class with zero tests. It was unclear whether JUnit 5.11 discovery, engine registration, or class visibility was at fault, which forced a fallback away from the dedicated engine.