Tech Talk: ArchUnit - Unit Tests to Force Architecture

A new Tech Talk has taken place at Faktor Zehn. This time it was about ArchUnit - unit tests to force architecture. Read the summary of the exciting talk by our colleague Aykut in the following blog article:

Many projects have the problem of design and architecture decisions not being adhered to over time. From a new developer's ignorance to a quick bug fix to the most experienced developer's lack of concentration. Architecture and design violations creep in all the time. ArchUnit gives us means to define the boundaries and usage intent of our code down to the smallest detail, and keeps our codebase free of outliers through automated testing. This reduces the accumulation of technical debt and keeps the system maintainable.

We take a look at ArchUnit and see how it can help us avoid the misuse of code.

Narrowing down the affected packages and selecting classes

No additional tools are needed to use ArchUnit. All that is needed to force an architectural rule or coding convention is an ordinary JUnit test.

As shown in the picture above, first the affected packages are narrowed down. In this case all classes are imported, which originate from the package "de.faktorzehn". Subsequently, the ArchRule is defined. This always goes after the scheme "classes that ${PREDICATE} should ${CONDITION}". In the predicate, based on the specified criteria, the affected classes are selected and in the condition these classes are held against the rule.

Rules in ArchUnit

The rules that can be defined using ArchUnit can be categorized as dependency checking, containment checking, inheritance checking, annotation checking, layer checking and cyclic checking.

                  Dependency Checking:

The first of the two dependency checks defines that no class from the "web" package can have

package may have dependencies on a class from the "persistence" package. However, all other packages, such as "business", are allowed.

The other check states that sharp objects (for example, knives) may only be used by adults. Other classes, such as baby, are not allowed.

As you can see in the picture, for the layer check, the individual layers are defined first and then the allowed dependencies among them are defined. For example, a class from the "Webapp" layer cannot now access a class from the "Business" layer, even if it would be possible through transitive dependencies of the Maven modules.

The same game can be applied not only to classes, but also to fields, methods, constructors, etc. There is also the possibility to define rules in a separate project and apply them later across products.


In general, it can be said that ArchUnit is a very powerful tool, which shines with a flexible and easily extensible API. If you are often upset about architecture and convention violations, you will quickly take ArchUnit to your heart.

About the author: Aykut works as a developer at Faktor Zehn and has been co-developing the Faktor-ICS claims management software since May 2020.


Your Faktor Zehn team

Sprachauswahl Icon
We noticed your browser language is not German.
Do you want to switch to English?