ArchUnit is a library designed to verify the architecture of Java code through unit tests, helping to prevent architectural erosion and maintain integrity across various characteristics. By creating rules and fitness functions, developers can ensure that their code adheres to architectural constraints, thereby fostering maintainability and comprehensibility. The document outlines how to implement ArchUnit tests, emphasizing its application in checking dependencies, layering, and coding rules within existing codebases.

1. Jeremy Cook
Unit test your Java Architecture
with ArchUnit
What, why and how to unit test your architecture

2. Agenda
1. What is ArchUnit?
2. Why do I want to test my architecture?
3. ArchUnit overview
4. Limitations

3. ArchUnit Website
“ArchUnit is a free, simple and extensible library
for checking the architecture of your Java
code using any plain Java unit test framework”

4. Why do I want to test my
architecture?

9. Problems architects face
Architecture is intangible
Knowing the design is implemented
Systems tend towards entropy over time
Architectural erosion ➡ loss of architectural characteristics

10. Fitness functions can help

11. Building Evolutionary Architectures by Neal Ford, Rebecca Parsons and Patrick Kua
“An architectural fitness function provides
objective integrity of some architectural
characteristic(s)”

12. Architectural
Characteristics

13. Performance
Scalability
Durability
Accessibility
Fault tolerance
Elasticity
Stability
Evolvability
Maintainability
Comprehensibility
Testability
Verifiable with
ArchUnit
*Not an exhaustive list
Architectural
Characteristics*

14. ArchUnit allows fitness functions to be
created that verify and protect architectural
characteristics expressed in code

15. How ArchUnit helps
Architecture as code ➡ tangible architecture
Architecture violations ➡ build failures
Harder to unintentionally change design

16. Verifiable with
Static Analysis
Verifiable with
ArchUnit

17. Verifiable with
Static Analysis
Verifiable with
ArchUnit

18. ArchUnit overview

19. Anatomy of an ArchUnit test
1. Find code to verify
2. Create one or more rules
3. Check code against rules

20. private final JavaClasses classes = new ClassFileImporter()
.importPackages(“com.myapp.somepackage”, “com.myapp.other”);

21. ArchRule rule = classes().that().resideInAPackage(“..service..”)
.should().onlyHaveDependentClassesThat()
.resideInAnyPackage("..controller..", “..service..");

22. private final JavaClasses classes = new ClassFileImporter()
.importPackages(“com.myapp.somepackage”, “com.myapp.other”);
@Test
public void checkServiceDependencies() {
}
classes().that().resideInAPackage(“..service..”)
.should().onlyHaveDependentClassesThat()
.resideInAnyPackage("..controller..", “..service..”)
.check(classes);

23. Identifying code to test

24. Using ClassFileImporter
Import by class, classpath, JAR, location, package name, packages of class(es),
URL and path
Resolves dependencies of imported code
Filter imported code by location

25. private final JavaClasses classes = new ClassFileImporter()
.withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
.withImportOption(location -> !location.contains("foo"))
.withImportOption(location -> location.matches(Pattern.compile(“.*“)))
.importClasspath();

26. Working with Rules

27. ArchUnit rules
CODE UNITS (classes, methods, fields, constructors, code units, etc)
THAT meet one or more conditions (optional)
SHOULD have one or more architectural characteristics

28. noClasses().that().areInterfaces()
.should().haveSimpleNameContaining(“Interface”)
.check(classes);

29. theClass(VeryCentralCore.class)
.should().onlyBeAccessed()
.byClassesThat().implement(CoreSatellite.class)
.check(classes);

30. fields().that().haveRawType(Logger.class)
.should().bePrivate()
.andShould().beStatic()
.andShould().beFinal()
.check(classes);

31. constructors().that()
.areDeclaredInClassesThat().resideInAPackage("..controller..")
.should().beAnnotatedWith(Inject.class)
.check(classes);

32. noMethods().that()
.areDeclaredInClassesThat().haveNameMatching(".*Dao")
.should().declareThrowableOfType(SQLException.class)
.check(classes);

33. .should().haveRawReturnType(Optional.class)
.orShould().beAnnotatedWith(NotNull.class)
.check(classes);
methods().that().arePublic()

34. .should().haveRawReturnType(Optional.class)
.orShould().beAnnotatedWith(NotNull.class)
.check(classes);
methods().that().arePublic()
.and().doNotHaveRawReturnType("void")

35. .should().haveRawReturnType(Optional.class)
.orShould().beAnnotatedWith(NotNull.class)
.check(classes);
methods().that().arePublic()
.and().doNotHaveRawReturnType("void")
.and().areDeclaredInClassesThat()
.areNotAnnotatedWith(ParametersAreNonnullByDefault.class)

36. .and(GET_RAW_RETURN_TYPE.is(not(assignableTo(Collection.class))))
.and(GET_RAW_RETURN_TYPE.is(not(assignableTo(Map.class))))
.should().haveRawReturnType(Optional.class)
.orShould().beAnnotatedWith(NotNull.class)
.check(classes);
methods().that().arePublic()
.and().doNotHaveRawReturnType("void")
.and().areDeclaredInClassesThat()
.areNotAnnotatedWith(ParametersAreNonnullByDefault.class)

37. @Test
public void controllersMustBeAnnotatedWithRestController() {
}
classes().that().resideInAPackage(“..controller..")
.should().beAnnotatedWith(RestController.class)
.check(classes);

38. @Test
public void onlyControllersHaveRestControllerAnnotation() {
}
noClasses().that().resideOutsideOfPackage("..controller..")
.should().beAnnotatedWith(RestController.class)
.check(classes);

39. @Test
public void publicMethodsInControllersMustHaveRouteAnnotation() {
}
methods().that()
.areDeclaredInClassesThat().resideInAPackage("..controller..")
.and().arePublic()
.should().beAnnotatedWith(GetMapping.class)
.orShould().beAnnotatedWith(PostMapping.class)
.orShould().beAnnotatedWith(DeleteMapping.class)
.orShould().beAnnotatedWith(PutMapping.class)
.check(classes);

40. Additional Features

41. Customizing failure messages
ArchUnit uses method names in rules for error messages
Customizable in two ways:
• Append text with .because()
• Replace error message with.as()

42. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.check(classes);

43. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.check(classes);

44. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.because("mutable public state is not a good idea")
.check(classes);

45. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.because("mutable public state is not a good idea")
.check(classes);

46. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.as("Don't give public fields mutable state")
.check(classes);

47. @Test
public void publicStaticFieldsShouldBeFinal() {
}
fields().that().arePublic()
.and().areStatic()
.should().beFinal()
.as("Don't give public fields mutable state")
.check(classes);

48. Creating custom rules
CODE UNITS (classes, methods, fields, constructors, code units, etc)
THAT meet one or more conditions
SHOULD have one or more architectural characteristics

49. Creating custom rules
CODE UNITS (classes, methods, fields, constructors, code units, etc)
DESCRIBED PREDICATES {THAT meet one or more conditions}
SHOULD have one or more architectural characteristics

50. Creating custom rules
CODE UNITS (classes, methods, fields, constructors, code units, etc)
DESCRIBED PREDICATES {THAT meet one or more conditions}
ARCH CONDITIONS {SHOULD have one or more architectural characteristics}

51. Creating custom rules
Create DescribedPredicates and ArchConditions in two ways:
1. Compose using built in library functions
2. Extend to create custom classes

52. .and(GET_RAW_RETURN_TYPE.is(not(assignableTo(Collection.class))))
.and(GET_RAW_RETURN_TYPE.is(not(assignableTo(Map.class))))
.should().haveRawReturnType(Optional.class)
.orShould().beAnnotatedWith(NotNull.class)
.check(classes);
methods().that().arePublic()
.and().doNotHaveRawReturnType("void")
.and().areDeclaredInClassesThat()
.areNotAnnotatedWith(ParametersAreNonnullByDefault.class)

53. classes().that().areAssignableTo(Serializable.class)
.and().areNotEnums()
.and().areNotInterfaces()
.should(new HaveAValidSerialVersionUIDField())
.check(classes);

54. public class HaveAValidSerialVersionUIDField extends ArchCondition<JavaClass> {
}

55. public class HaveAValidSerialVersionUIDField extends ArchCondition<JavaClass> {
}
public HaveAValidSerialVersionUIDField() {
super("have a valid serialVersionUID field");
}

56. public class HaveAValidSerialVersionUIDField extends ArchCondition<JavaClass> {
}
public HaveAValidSerialVersionUIDField() {
super("have a valid serialVersionUID field");
}
@Override
public void check(JavaClass item, ConditionEvents events) {
}

57. public class HaveAValidSerialVersionUIDField extends ArchCondition<JavaClass> {
}
public HaveAValidSerialVersionUIDField() {
super("have a valid serialVersionUID field");
}
@Override
public void check(JavaClass item, ConditionEvents events) {
}
var errorMessage = item.getName() + " does not contain a valid serialVersionUID field";
try {
JavaField field = item.getField("serialVersionUID");
} catch (IllegalArgumentException e) {
events.add(SimpleConditionEvent.violated(item, errorMessage));
}

58. public class HaveAValidSerialVersionUIDField extends ArchCondition<JavaClass> {
}
public HaveAValidSerialVersionUIDField() {
super("have a valid serialVersionUID field");
}
@Override
public void check(JavaClass item, ConditionEvents events) {
}
var errorMessage = item.getName() + " does not contain a valid serialVersionUID field";
try {
JavaField field = item.getField("serialVersionUID");
} catch (IllegalArgumentException e) {
events.add(SimpleConditionEvent.violated(item, errorMessage));
}
var hasValidSerialVersionUID =
HasModifiers.Predicates.modifier(JavaModifier.STATIC).apply(field)
&& HasModifiers.Predicates.modifier(JavaModifier.FINAL).apply(field)
&& HasType.Predicates.rawType("long").apply(field);
events.add(new SimpleConditionEvent(item, hasValidSerialVersionUID, errorMessage));

59. General Coding Rules
Small number of pre-configured rules to test common conditions

60. GeneralCodingRules.NO_CLASSES_SHOULD_USE_FIELD_INJECTION
.check(classes);

61. GeneralCodingRules.NO_CLASSES_SHOULD_THROW_GENERIC_EXCEPTIONS
.check(classes);

62. Testing architectural layers
Can be done manually
Three specialized rule types for checking layers:
• Check lower packages do not depend on upper packages
• Define layers and check dependencies between them
• Testing onion architectures

63. DependencyRules.NO_CLASSES_SHOULD_DEPEND_UPPER_PACKAGES
.check(classes);

64. layeredArchitecture()
.layer(“Controllers")
.definedBy(“com.myapp.somepackage.controller..")
.layer(“Services")
.definedBy("com.myapp.somepackage.service..")
.layer(“Persistence")
.definedBy(“com.myapp.somepackage.persistence..")
.whereLayer(“Controllers")
.mayNotBeAccessedByAnyLayer()
.whereLayer(“Services")
.mayOnlyBeAccessedByLayers("Controllers")
.whereLayer(“Persistence")
.mayOnlyBeAccessedByLayers("Services")
.ignoreDependency(SomeMediator.class, ServiceViolatingLayerRules.class)
.check(classes);

65. onionArchitecture()
.domainModels("..domain.model..")
.domainServices("..domain.service..")
.applicationServices("..application..")
.adapter("cli", "..adapter.cli..")
.adapter("persistence", "..adapter.persistence..")
.adapter("rest", "..adapter.rest..")
.check(classes);

66. Adding ArchUnit to existing codebases
How can you add architecture tests to existing code that has violations?
1. Ignoring violations based on patterns
2. Freezing architecture rules

67. var rule = fields().that().arePublic()
.and().areStatic()
.should().beFinal();
FreezingArchRule.freeze(rule)
.check(classes);

68. Other features
• Check code against PlantUML diagrams
• Options to manage dependencies outside of diagram
• Identify and test slices of an application:
• Check for cycles
• Check slices do not depend on each other

69. Limitations

70. Cannot test all architectural
characteristics

71. Does not ensure maintainability
on its own

72. Can only check (some) JVM
languages

73. Importing large amounts of code

74. More information
ArchUnit website: https://www.archunit.org
Sample project: https://github.com/TNG/ArchUnit-Examples

75. Questions?

76. Thank you
Feel free to reach out to me
• Twitter @JCook21
• jeremycook0@icloud.com