ArchUnit User Guide

ArchUnit consists of the following production modules: archunit, archunit-junit4 as well as archunit-junit5-api, archunit-junit5-engine and archunit-junit5-engine-api. Also relevant for end users is the archunit-example module.

To use ArchUnit in combination with JUnit 4, include the following dependency from Maven Central:

ArchUnit’s JUnit 5 artifacts follow the pattern of JUnit Jupiter. There is one artifact containing the API, i.e. the compile time dependencies to write tests. Then there is another artifact containing the actual TestEngine used at runtime. Just like JUnit Jupiter ArchUnit offers one convenience artifact transitively including both API and engine with the correct scope, which in turn can be added as a test compile dependency. Thus to include ArchUnit’s JUnit 5 support, simply add the following dependency from Maven Central:

ArchUnit works with any test framework that executes Java code. To use ArchUnit in such a context, include the core ArchUnit dependency from Maven Central:

There exists a Maven plugin by Société Générale to run ArchUnit rules straight from Maven. For more information visit their GitHub repo: https://github.com/societe-generale/arch-unit-maven-plugin

At its core ArchUnit provides infrastructure to import Java bytecode into Java code structures. This can be done using the ClassFileImporter

The ClassFileImporter offers many ways to import classes. Some ways depend on the current project’s classpath, like importPackages(..). However there are other ways that do not, for example:

The returned object of type JavaClasses represents a collection of elements of type JavaClass, where JavaClass in turn represents a single imported class file. You can in fact access most properties of the imported class via the public API:

To express architectural rules, like 'Services should only be accessed by Controllers', ArchUnit offers an abstract DSL-like fluent API, which can in turn be evaluated against imported classes. To specify a rule, use the class ArchRuleDefinition as entry point:

The two dots represent any number of packages (compare AspectJ Pointcuts). The returned object of type ArchRule can now be evaluated against a set of imported classes:

Thus the complete example could look like

While ArchUnit can be used with any unit testing framework, it provides extended support for writing tests with JUnit 4 and JUnit 5. The main advantage is automatic caching of imported classes between tests (of the same imported classes), as well as reduction of boilerplate code.

To use the JUnit support, declare ArchUnit’s ArchUnitRunner (only JUnit 4), declare the classes to import via @AnalyzeClasses and add the respective rules as fields:

The JUnit test support will automatically import (or reuse) the specified classes and evaluate any rule annotated with @ArchTest against those classes.

For further information on how to use the JUnit support refer to JUnit Support.

Using the JUnit support with Kotlin is quite similar to Java:

Much of ArchUnit’s core API resembles the Java Reflection API. There are classes like JavaMethod, JavaField, and more, and the public API consists of methods like getName(), getMethods(), getRawType() or getRawParameterTypes(). Additionally ArchUnit extends this API for concepts needed to talk about dependencies between code, like JavaMethodCall, JavaConstructorCall or JavaFieldAccess. For example, it is possible to programmatically iterate over javaClass.getAccessesFromSelf() and react to the imported accesses between this Java class and other Java classes.

To import compiled Java class files, ArchUnit provides the ClassFileImporter, which can for example be used to import packages from the classpath:

For more information refer to The Core API.

The Core API is quite powerful and offers a lot of information about the static structure of a Java program. However, tests directly using the Core API lack expressiveness, in particular with respect to architectural rules.

For this reason ArchUnit provides the Lang API, which offers a powerful syntax to express rules in an abstract way. Most parts of the Lang API are composed as fluent APIs, i.e. an IDE can provide valuable suggestions on the possibilities the syntax offers.

An example for a specified architecture rule would be:

Once a rule is composed, imported Java classes can be checked against it:

The syntax ArchUnit provides is fully extensible and can thus be adjusted to almost any specific need. For further information, please refer to The Lang API.

The Library API offers predefined complex rules for typical architectural goals. For example a succinct definition of a layered architecture via package definitions. Or rules to slice the code base in a certain way, for example in different areas of the domain, and enforce these slices to be acyclic or independent of each other. More detailed information is provided in The Library API.

As mentioned in Ideas and Concepts the backbone of the infrastructure is the ClassFileImporter, which provides various ways to import Java classes. One way is to import packages from the classpath, or the complete classpath via

However, the import process is completely independent of the classpath, so it would be well possible to import any path from the file system:

The ClassFileImporter offers several other methods to import classes, for example locations can be specified as URLs or as JAR files.

Furthermore specific locations can be filtered out, if they are contained in the source of classes, but should not be imported. A typical use case would be to ignore test classes, when the classpath is imported. This can be achieved by specifying ImportOptions:

A Location is principally an URI, i.e. ArchUnit considers sources as File or JAR URIs

For the two common cases to skip importing JAR files and to skip importing test files (for typical setups, like a Maven or Gradle build), there already exist predefined ImportOptions:

The domain objects represent Java code, thus the naming should be pretty straight forward. Most commonly, the ClassFileImporter imports instances of type JavaClass. A rough overview looks like this:

Most objects resemble the Java Reflection API, including inheritance relations. Thus a JavaClass has JavaMembers, which can in turn be either JavaField, JavaMethod, JavaConstructor (or JavaStaticInitializer). While not present within the reflection API, it makes sense to introduce an expression for anything that can access other code, which ArchUnit calls 'code unit', and is in fact either a method, a constructor (including the class initializer) or a static initializer of a class (e.g. a static { …​ } block, a static field assignment, etc.).

Furthermore one of the most interesting features of ArchUnit that exceeds the Java Reflection API, is the concept of accesses to another class. On the lowest level accesses can only take place from a code unit (as mentioned, any block of executable code) to either a field (JavaFieldAccess), a method (JavaMethodCall) or constructor (JavaConstructorCall).

ArchUnit imports the whole graph of classes and their relationship to each other. While checking the accesses from a class is pretty isolated (the bytecode offers all this information), checking accesses to a class requires the whole graph to be built first. To distinguish which sort of access is referred to, methods will always clearly state fromSelf and toSelf. For example, every JavaField allows to call JavaField#getAccessesToSelf() to retrieve all code units within the graph that access this specific field. The resolution process through inheritance is not completely straight forward. Consider for example

The bytecode will record a field access from ClassAccessing.accessField() to ClassBeingAccessed.accessedField. However, there is no such field, since the field is actually declared in the superclass. This is the reason why a JavaFieldAccess has no JavaField as its target, but a FieldAccessTarget. In other words, ArchUnit models the situation, as it is found within the bytecode, and an access target is not an actual member within another class. If a member is queried for accessesToSelf() though, ArchUnit will resolve the necessary targets and determine, which member is represented by which target. The situation looks roughly like

Two things might seem strange at the first look.

First, why can a target resolve to zero matching members? The reason is that the set of classes that was imported does not need to have all classes involved within this resolution process. Consider the above example, if SuperclassBeingAccessed would not be imported, ArchUnit would have no way of knowing where the actual targeted field resides. Thus in this case the resolution would return zero elements.

Second, why can there be more than one resolved methods for method calls? The reason for this is that a call target might indeed match several methods in those cases, for example:

While this situation will always be resolved in a specified way for a real program, ArchUnit cannot do the same. Instead, the resolution will report all candidates that match a specific access target, so in the above example, the call target C.targetMethod() would in fact resolve to two JavaMethods, namely A.targetMethod() and B.targetMethod(). Likewise a check of either A.targetMethod.getCallsToSelf() or B.targetMethod.getCallsToSelf() would return the same call from D.callTargetMethod() to C.targetMethod().

The Core API is pretty powerful with regard to all the details from the bytecode that it provides to tests. However, tests written this way lack conciseness and fail to convey the architectural concept that they should assert. Consider:

What we want to express, is the rule "no classes that reside in a package 'service' should access classes that reside in a package 'controller'". Nevertheless, it’s hard to read through that code and distill that information. And the same process has to be done every time someone needs to understand the semantics of this rule.

To solve this shortcoming, ArchUnit offers a high level API to express architectural concepts in a concise way. In fact, we can write code that is almost equivalent to the prose rule text mentioned before:

The only difference to colloquial language is the ".." in the package notation, which refers to any number of packages. Thus "..service.." just expresses "any package that contains some sub-package 'service'", e.g. com.myapp.service.any. If this test fails, it will report an AssertionError with the following message:

So as a benefit, the assertion error contains the full rule text out of the box and reports all violations including the exact class and line number. The rule API also allows to combine predicates and conditions:

In addition to a predefined API to write rules about Java classes and their relations, there is an extended API to define rules for members of Java classes. This might be relevant, for example, if methods in a certain context need to be annotated with a specific annotation, or return types implementing a certain interface. The entry point is again ArchRuleDefinition, e.g.

Besides methods(), ArchRuleDefinition offers the methods members(), fields(), codeUnits(), constructors() – and the corresponding negations noMembers(), noFields(), noMethods(), etc.

In fact, most architectural rules take the form

In other words, we always want to limit imported classes to a relevant subset, and then evaluate some condition to see that all those classes satisfy it. ArchUnit’s API allows you to do just that, by exposing the concepts of DescribedPredicate and ArchCondition. So the rule above is just an application of this generic API:

Thus, if the predefined API does not allow to express some concept, it is possible to extend it in any custom way. For example:

If the rule fails, the error message will be built from the supplied descriptions. In the example above, it would be

Custom predicates and conditions like in the last section can often be composed from predefined elements. ArchUnit’s basic convention for predicates is that they are defined in an inner class Predicates within the type they target. For example, one can find the predicate to check for the simple name of a JavaClass as

Predicates can be joined using the methods predicate.or(other) and predicate.and(other). So for example a predicate testing for a class with simple name "Foo" that is serializable could be created the following way:

Note that for some properties, there exist interfaces with predicates defined for them. For example the property to have a name is represented by the interface HasName; consequently the predicate to check the name of a JavaClass is the same as the predicate to check the name of a JavaMethod, and resides within

This can at times lead to problems with the type system, if predicates are supposed to be joined. Since the or(..) method accepts a type of DescribedPredicate<? super T>, where T is the type of the first predicate. For example:

This behavior is somewhat tedious, but unfortunately it is a shortcoming of the Java type system that cannot be circumvented in a satisfying way.

Just like predicates, there exist predefined conditions that can be combined in a similar way. Since ArchCondition is a less generic concept, all predefined conditions can be found within ArchConditions. Examples:

Earlier we stated that most architectural rules take the form

However, we do not always talk about classes, if we express architectural concepts. We might have custom language, we might talk about modules, about slices, or on the other hand more detailed about fields, methods or constructors. A generic API will never be able to support every imaginable concept out of the box. Thus ArchUnit’s rule API has at its foundation a more generic API that controls the types of objects that our concept targets.

To achieve this, any rule definition is based on a ClassesTransformer that defines how JavaClasses are to be transformed to the desired rule input. In many cases, like the ones mentioned in the sections above, this is the identity transformation, passing classes on to the rule as they are. However, one can supply any custom transformation to express a rule about a different type of input object. For example:

Of course these transformers can represent any custom concept desired:

If the rule is straight forward, the rule text that is created automatically should be sufficient in many cases. However, for rules that are not common knowledge, it is good practice to document the reason for this rule. This can be done in the following way:

Nevertheless, the generated rule text might sometimes not convey the real intention concisely enough, e.g. if multiple predicates or conditions are joined. It is possible to completely overwrite the rule description in those cases:

In legacy projects there might be too many violations to fix at once. Nevertheless, that code should be covered completely by architecture tests to ensure that no further violations will be added to the existing code. One approach to ignore existing violations is to tailor the that(..) clause of the rules in question to ignore certain violations. A more generic approach is to ignore violations based on simple regex matches. For this one can put a file named archunit_ignore_patterns.txt in the root of the classpath. Every line will be interpreted as a regular expression and checked against reported violations. Violations with a message matching the pattern will be ignored. If no violations are left, the check will pass.

For example, suppose the class some.pkg.LegacyService violates a lot of different rules. It is possible to add

All violations mentioning some.pkg.LegacyService will consequently be ignored, and rules that are only violated by such violations will report success instead of failure.

It is possible to add comments to ignore patterns by prefixing the line with a '#':

The entrance point for checks of common architectural styles is:

At the moment this only provides a convenient check for a layered architecture and onion architecture. But in the future it might be extended for styles like a pipes and filters, separation of business logic and technical infrastructure, etc.

Currently, there are two "slice" rules offered by the Library API. These are basically rules that slice the code by packages, and contain assertions on those slices. The entrance point is:

The API is based on the idea to sort classes into slices according to one or several package infixes, and then write assertions against those slices. At the moment this is for example:

If this constraint is too rigid, e.g. in legacy applications where the package structure is rather inconsistent, it is possible to further customize the slice creation. This can be done by specifying a mapping of JavaClass to SliceIdentifier where classes with the same SliceIdentifier will be sorted into the same slice. Consider this example:

To express the concept of modularization ArchUnit offers ArchModules. The entrypoint into the API is ModuleRuleDefinition, e.g.

As the example shows, it shares some concepts with the Slices API. For example definedByPackages(..) follows the same semantics as slices().matching(..). Also, the configuration options for cycle detection mentioned in the last section are shared by these APIs. But, it also offers several powerful concepts beyond that API to express many different modularization scenarios.

One example would be to express modules via annotation. We can introduce a custom annotation like @AppModule and follow a convention to annotate the top-level package-info file of each package we consider the root of a module. E.g.

We can then define a rule using this annotation:

As the example shows, the syntax carries on meta-information (like the annotation of the annotated package-info) into the created ArchModule objects where it can be used to define the rule. In this example, the allowed dependencies are taken from the @AppModule annotation on the respective package-info and compared to the actual module dependencies. Any dependency not listed is reported as violation. Likewise, the exposed packages are taken from the @AppModule annotation and any dependency where the target class’s package doesn’t match any declared package identifier is reported as violation.

Note that the modules() API can be adjusted in many ways to model custom requirements. For further details, please take a look at the examples provided here.

The Library API also offers a small set of coding rules that might be useful in various projects. Those can be found within

The Library API offers a feature that supports PlantUML diagrams. This feature is located in

ArchUnit can derive rules straight from PlantUML diagrams and check to make sure that all imported JavaClasses abide by the dependencies of the diagram. The respective rule can be created in the following way:

Diagrams supported have to be component diagrams and associate classes to components via stereotypes. The way this works is to use the respective package identifiers (compare ArchConditions.onlyHaveDependenciesInAnyPackage(..)) as stereotypes:

Consider this diagram applied as a rule via adhereToPlantUmlDiagram(..), then for example a class some.target.Target accessing some.source.Source would be reported as a violation.

When rules are introduced in grown projects, there are often hundreds or even thousands of violations, way too many to fix immediately. The only way to tackle such extensive violations is to establish an iterative approach, which prevents the code base from further deterioration.

FreezingArchRule can help in these scenarios by recording all existing violations to a ViolationStore. Consecutive runs will then only report new violations and ignore known violations. If violations are fixed, FreezingArchRule will automatically reduce the known stored violations to prevent any regression.

Similar to code quality metrics, like cyclomatic complexity or method length, software architecture metrics strive to measure the structure and design of software. ArchUnit can be used to calculate some well-known software architecture metrics. The foundation of these metrics is generally some form of componentization, i.e. we partition the classes/methods/fields of a Java application into related units and provide measurements for these units. In ArchUnit this concept is expressed by com.tngtech.archunit.library.metrics.MetricsComponent. For some metrics, like the Cumulative Dependency Metrics by John Lakos, we also need to know the dependencies between those components, which are naturally derived from the dependencies between the elements (e.g. classes) within these components.

A very simple concrete example would be to consider some Java packages as components and the classes within these packages as the contained elements. From the dependencies between the classes we can derive which package depends on which other package.

The following will give a quick overview of the metrics that ArchUnit can calculate. However, for further background information it is recommended to rely on some dedicated literature that explains these metrics in full detail.

Make sure you follow the installation instructions at Installation, in particular to include the correct dependency for the respective JUnit support.

ArchUnit will use exactly the archunit.properties file returned by the context ClassLoader from the classpath root, via the standard Java resource loading mechanism.

It is possible to override any property from archunit.properties, by passing a system property to the respective JVM process executing ArchUnit:

E.g. to override the property resolveMissingDependenciesFromClassPath described in the next section, it would be possible to pass:

As mentioned in Dealing with Missing Classes, it might be preferable to configure a different import behavior if dealing with missing classes wastes too much performance. One way that can be chosen out of the box is to never resolve any missing class from the classpath:

If you want to resolve just some classes from the classpath (e.g. to import missing classes from your own organization but avoid the performance impact of importing classes from 3rd party packages), it is possible to configure only specific packages to be resolved from the classpath:

This configuration would only resolve the packages some.pkg.one and some.pkg.two from the classpath, and stub all other missing classes.

The last example also demonstrates, how the behavior can be customized freely, for example if classes are imported from a different source and are not on the classpath:

First Supply a custom implementation of

Then configure it

If the resolver needs some further arguments, create a public constructor with one List<String> argument, and supply the concrete arguments as

For further details, compare the sources of SelectedClassResolverFromClasspath.

Sometimes it can be valuable to record the MD5 sums of classes being imported to track unexpected behavior. Since this has a performance impact, it is disabled by default, but it can be activated the following way:

If this feature is enabled, the MD5 sum can be queried as

By default, ArchUnit will forbid the should-part of rules to be evaluated against an empty set of classes. The reason is that this can lead to rules that by accident do not check any classes at all. Take for example

Now consider somebody renames the package old to newer. The rule will now always evaluate successfully without any reported error. However, it actually does not check any classes at all anymore. This is likely not what most users want. Thus, by default ArchUnit will fail checking the rule in this case. If you want to allow evaluating such rules, i.e. where the actual input to the should-clause is empty, you can use one of the following ways:

Allow Empty Should on a Per-Rule Basis

On each ArchRule you can use the method ArchRule.allowEmptyShould(..) to override the behavior for a single rule, e.g.

Allow Empty Should Globally

To allow all rules to be evaluated without checking any classes you can set the following property:

You can configure a custom format to display the failures of a rule.

First Supply a custom implementation of

Then configure it

One example would be to shorten the fully qualified class names in failure messages:

Note that due to the free format how violation texts can be composed, in particular by custom predicates and conditions, there is at the moment no more sophisticated way than plain text parsing. Users can tailor this to their specific environments where they know which sorts of failure formats can appear in practice.