liveBook · Manning

Architectural test freezing

As explained in Clean Applications with Hexagonal Architecture

A mechanism that records existing architectural rule violations so they can be tolerated while new violations remain disallowed.

Adding architectural rules to a mature codebase can make every existing violation fail the build at once. Freezing records those violations as a baseline: known violations pass, while new ones fail. This lets teams enforce rules immediately without first fixing all accumulated drift. section 7.8 section 7.3

With ArchUnit, the freeze mechanism works as follows:

  • Wrap a rule with FreezingArchRule.freeze() and check it against the classes under test. section 7.8
  • On its first run, ArchUnit records current violations in src/test/resources/archunit_store/. Later runs fail on newly introduced violations and tolerate recorded ones. section 7.8
  • When a recorded violation is fixed, ArchUnit removes it from the store. Commit the store to version control; losing it can cause current violations to be accepted as a fresh baseline. section 7.8
  • Treat freezing as a migration aid: review and reduce the stored violations, then remove the wrapper when a rule’s store is empty. section 7.8
Listing 7.28 Freezing a rule (pattern used throughout all checkers)
FreezingArchRule.freeze(sharedKernelDependencyRule)
  .check(javaClasses);

Shows the ArchUnit wrapper used to freeze a rule before checking Java classes. section 7.8

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains snapshot creation, violation comparison, automatic removal of fixed violations, and eventual removal of the freeze wrapper.
Examples
Uses FreezingArchRule.freeze(sharedKernelDependencyRule).check(javaClasses) and a versioned violation store.
What it assumes
Assumes ArchUnit rules are already defined and checked against Java classes.
What you can do after
Operate incremental enforcement by committing the violation store, reviewing its changes, and removing freezing when it becomes empty.
How it connects
Connects architectural rule enforcement with ArchUnit and baselining existing rule violations.

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.