ArchUnit: Tool for Enforcing Architecture in Java Applications

When developing complex software systems, maintaining a clear and consistent architecture is crucial. However, as a project grows, it can be challenging to ensure that the architecture guidelines are being followed, especially as teams and codebases evolve. This is where ArchUnit comes in. ArchUnit is a Java library that enables you to define, enforce, and test architectural rules in your codebase, ensuring that your software architecture remains consistent and aligned with the design principles you’ve set.

In this blog post, we'll take a closer look at ArchUnit, how it works, and how you can integrate it into your Java projects to improve your development process and architecture quality.

What is ArchUnit?

ArchUnit is a Java library that allows you to define rules for your software architecture and check whether your code adheres to those rules. It provides a fluent API for creating tests that validate architectural constraints, such as package dependencies, layer separation, class naming conventions, and many others.

Instead of relying on manual reviews or scattered documentation, ArchUnit makes it easy to automate architectural validation, helping you catch violations early in the development cycle.

Key Features of ArchUnit:

• Test-Driven Architecture: You can write tests that validate whether the code complies with your architecture guidelines.
• Flexibility: ArchUnit provides a wide range of predefined rules and also lets you define custom architectural constraints.
• Seamless Integration: It integrates well with your existing testing framework, such as JUnit or TestNG, making it easy to run architectural checks as part of your regular tests.
• No runtime overhead: The architectural rules are only checked at compile time and during tests, meaning there is no performance overhead when the application is running.

Why Use ArchUnit?

As systems scale, developers often face challenges in keeping the architecture clean and maintaining high cohesion and low coupling. Without formal checks, violations of architectural principles can creep in, leading to problems like:

• Tight coupling: Where classes are overly dependent on each other, making the system hard to maintain and extend.
• Layer violations: Where, for example, a service layer starts to depend on or access the database layer directly, breaking the clean separation of concerns.
• Cycling dependencies: Where different modules or packages become cyclically dependent, which can lead to issues like infinite recursion or difficulties in testing.

ArchUnit allows you to catch these problems early, well before they become bugs, by enforcing architectural rules in a way that is testable and repeatable.

Common Use Cases for ArchUnit

Package Dependency Checks: One of the most common use cases for ArchUnit is enforcing package boundaries. For instance, you can ensure that no class in your application’s UI layer depends on classes in the persistence layer or vice versa. This helps maintain a clean separation of concerns.

@Test
void servicesShouldOnlyDependOnRepositories() {
    ArchRule rule = classes()
        .that().resideInAPackage("..service..")
        .should().onlyDependOnClassesThat()
        .resideInAnyPackage("..repository..", "java..");

    rule.check(classes);
}        

Layered Architecture Validation: In a layered architecture (e.g., presentation layer, business logic layer, data access layer), ArchUnit can help ensure that the layers interact only in the allowed direction.

@Test
void businessLogicShouldNotDependOnPresentation() {
    ArchRule rule = classes()
        .that().resideInAPackage("..business..")
        .should().notDependOnClassesThat()
        .resideInAPackage("..presentation..");

    rule.check(classes);
}        

Naming Conventions: Enforcing consistent naming conventions across your project is another common use case. For example, you can ensure that service classes always end with Service or that DAO classes are prefixed with Dao.

@Test
void serviceClassesShouldHaveServiceSuffix() {
    ArchRule rule = classes()
        .that().haveNameMatching(".*Service")
        .should().resideInAPackage("..service..");

    rule.check(classes);
}        

Preventing Circular Dependencies: Circular dependencies can be a sign of poor design. ArchUnit can help you detect these situations by defining rules that prevent classes from indirectly depending on each other.

1. Custom Architectural Constraints: Besides the predefined rules, ArchUnit allows you to define your own custom constraints. For example, you can write a rule that ensures that all classes in a certain package implement a particular interface.

How to Get Started with ArchUnit?

1. Adding ArchUnit to Your Project

ArchUnit is available via Maven Central, so adding it to your project is simple. If you're using Maven, add the following dependency to your pom.xml:

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-core</artifactId>
    <version>0.23.0</version> <!-- Check for the latest version -->
    <scope>test</scope>
</dependency>        

If you're using Gradle, add this to your build.gradle:

testImplementation 'com.tngtech.archunit:archunit-core:0.23.0' // Check for the latest version        

2. Writing Your First ArchUnit Test

Once you've added the dependency, you can start writing architectural tests using ArchUnit. Here’s a simple example where we enforce that classes in the service package should only depend on classes in the repository package:

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.library.dependencies.SlicesRuleDefinition;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

class ArchitectureTest {

    @Test
    void servicesShouldOnlyDependOnRepositories() {
        JavaClasses importedClasses = new ClassFileImporter().importPackages("com.example.myapp");

        ArchRule rule = classes()
            .that().resideInAPackage("..service..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..repository..", "java..");

        rule.check(importedClasses);
    }
}        

3. Running the Tests

Since ArchUnit integrates with JUnit (or TestNG), you can run your architectural tests just like regular unit tests. If any architectural rules are violated, ArchUnit will fail the test, and you’ll be alerted to the issue.

Best Practices for Using ArchUnit

1. Start Small: Begin by writing a few basic architectural tests and gradually expand as you become more comfortable with the tool.
2. Integrate into CI/CD: Automate architectural tests by integrating them into your Continuous Integration (CI) pipeline. This will help ensure that architectural violations are caught early in the development cycle.
3. Use with Other Testing: Combine ArchUnit with unit tests, integration tests, and other quality checks to ensure that both the functionality and architecture of your codebase remain sound.
4. Avoid Over-Engineering: While enforcing architectural rules is important, avoid making your rules too complex or too restrictive. The goal is to strike a balance between flexibility and maintaining a clean structure.

ArchUnit is an incredibly powerful tool for enforcing architectural standards and ensuring that your Java application remains modular, maintainable, and scalable. By defining and testing architectural rules, you can automate the enforcement of good practices, making it easier to maintain a clean codebase as your project grows.

Whether you're working on a large-scale enterprise application or a smaller project, integrating ArchUnit into your development process can help prevent architectural decay and keep your system aligned with your original design principles.

Author

Nadir Riyani is an accomplished and visionary Engineering Manager with a strong background in leading high-performing engineering teams. With a passion for technology and a deep understanding of software development principles, Nadir has a proven track record of delivering innovative solutions and driving engineering excellence. He possesses a comprehensive understanding of software engineering methodologies, including Agile and DevOps, and has a keen ability to align engineering practices with business objectives.