Enhance Your Java Project’s Architecture with ArchUnit: A Comprehensive Guide to Code Integrity

1. Use Cases

Ensuring that a codebase adheres to architectural standards is essential for maintaining quality, scalability, and effective team collaboration. ArchUnit is a powerful tool that allows you to enforce architecture rules in Java projects, making it easier to maintain consistency and avoid technical debt.

This guide will walk you through integrating ArchUnit into your Gradle-based Java projects with practical code examples and insights on leveraging it for robust architecture compliance.

---

2. Why Use ArchUnit?

• Architectural Compliance: Automates checks to ensure adherence to pre-defined architectural rules.
• Prevents Technical Debt: Detects violations early to avoid long-term code issues.
• Consistency: Promotes uniform code practices across teams and projects.
• Simplifies Code Reviews: Reduces the need for manual architectural checks during code reviews.
• CI/CD Integration: Integrates seamlessly into build pipelines for continuous validation.

---

3. Setting Up ArchUnit in a Gradle Project

To introduce ArchUnit into your Gradle project, follow these steps:

Step 1: Add the ArchUnit Dependency

Add the following dependency to your build.gradle file under

dependencies {
    testImplementation 'com.tngtech.archunit:archunit:1.3.0'
}

Step 2: Create Architecture Test Class

Create a class, such as ArchitectureTest.java, in your test source folder (e.g., src/test/java/com/developerscoffee/test/integrity).

---

4. Sample Architecture Test Class

Below is an example of how to write architecture tests for a multi-module Gradle project:

package com.developerscoffee.test.integrity;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;

import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Tag("architecture")
@DisplayName("Architecture Compliance Tests")
public class ArchitectureTest {

    private static final Logger logger = LoggerFactory.getLogger(AbstractArchitectureTest.class);
  protected static JavaClasses importedClasses;

  @BeforeAll
  public static void setUp() throws IOException {
    logger.info("Setting up the architecture test environment...");
    importedClasses =
        new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPaths(getAllModuleClassPaths());
    logger.info("Setup complete. Classes imported: {}", importedClasses.size());
  }

  private static List<Path> getAllModuleClassPaths() throws IOException {
    Path rootPath = new File(System.getProperty("user.dir")).toPath();
    try (Stream<Path> pathStream = Files.walk(rootPath)) {
      return pathStream
          .filter(path -> path.toString().endsWith("build/classes/java/main"))
          .collect(Collectors.toList());
    }
  }

  @Test
  public void domainLayerShouldBeIndependent() {
    executeRule(
        "domainLayerShouldBeIndependent",
        classes()
            .that()
            .resideInAPackage("..domain..")
            .should()
            .onlyDependOnClassesThat()
            .resideInAnyPackage("java..", "..domain..")
            .because("The domain layer should be independent and not depend on other layers."));
  }

  @Test
  public void infrastructureLayerShouldOnlyBeAccessedViaInterfaces() {
    executeRule(
        "infrastructureLayerShouldOnlyBeAccessedViaInterfaces",
        classes()
            .that()
            .resideInAPackage("..infrastructure..")
            .should()
            .onlyBeAccessed()
            .byClassesThat()
            .resideInAPackage("..service..")
            .andShould()
            .onlyDependOnClassesThat()
            .areInterfaces()
            .because("The infrastructure layer should only be accessed through interfaces."));
  }

  @Test
  public void repositoriesShouldOnlyBeAccessedByServices() {
    executeRule(
        "repositoriesShouldOnlyBeAccessedByServices",
        classes()
            .that()
            .resideInAPackage("..repository..")
            .should()
            .onlyBeAccessed()
            .byClassesThat()
            .resideInAPackage("..service..")
            .because("Repositories should only be accessed by service classes."));
  }

  @Test
  public void controllersShouldUseDTOsOnly() {
    executeRule(
        "controllersShouldUseDTOsOnly",
        noClasses()
            .that()
            .resideInAPackage("..controller..")
            .should()
            .dependOnClassesThat()
            .resideInAPackage("..domain..")
            .because(
                "Controllers should use DTOs and not directly interact with the core domain."));
  }

  @Test
  public void servicesShouldDependOnInterfaces() {
    executeRule(
        "servicesShouldDependOnInterfaces",
        classes()
            .that()
            .resideInAPackage("..service..")
            .should()
            .onlyDependOnClassesThat(
                DescribedPredicate.describe(
                    "be interfaces or Java core classes",
                    javaClass ->
                        javaClass.isInterface() || javaClass.getPackageName().startsWith("java")))
            .because(
                "Services should depend on interfaces or Java core classes rather than concrete implementations."));
  }

  @Test
  public void noCircularDependenciesAmongPackages() {
    executeRule(
        "noCircularDependenciesAmongPackages",
        slices()
            .matching("com.developerscoffee.(*)..")
            .should()
            .beFreeOfCycles()
            .because("There should be no cyclic dependencies among packages."));
  }

  @Test
  public void testNoFieldInjection() {
    executeRule(
        "testNoFieldInjection",
        noClasses()
            .should()
            .dependOnClassesThat()
            .haveNameMatching(".*Autowired")
            .because(
                "Field injection should be avoided. Use constructor-based injection instead."));
  }

  @Test
  public void testPublicClassesInControllerAndServicePackages() {
    executeRule(
        "testPublicClassesInControllerAndServicePackages",
        classes()
            .that()
            .resideInAnyPackage("..controller..", "..service..")
            .should()
            .bePublic()
            .because("Classes in controller and service packages should be public."));
  }

  @Test
  public void testUtilityClassNaming() {
    executeRule(
        "testUtilityClassNaming",
        classes()
            .that()
            .resideInAPackage("..util..")
            .should()
            .haveSimpleNameEndingWith("Util")
            .because("Classes in the utility package should have names ending with 'Util'."));
  }

  private void executeRule(String ruleName, ArchRule rule) {
    logger.info("Executing: {}", ruleName);
    try {
      rule.check(importedClasses);
      logger.info("Completed: {}", ruleName);
    } catch (AssertionError e) {
      logger.error("Architecture Violation in {}: {}", ruleName, e.getMessage());
      throw e;
    }
  }
}

---

5. Running the Tests

• In IDE: Run the ArchitectureTest class as a regular JUnit test.
• In Gradle: Run the tests with ./gradlew test to execute the architecture checks as part of your build pipeline.

This ensures that architecture checks are part of your build pipeline.

---

6. Handling Violations

When a rule is violated, ArchUnit provides detailed feedback specifying the problematic class or method.

the offending class or method.

Example Violation Output:

Method <com.developerscoffee.order.OrderController.processOrder()> calls method <com.developerscoffee.order.service.OrderService.processOrder()> in (OrderController.java:45)

Steps to Handle:

• Review the Violation: Understand the reason behind the failure.
• Discuss: Decide if the rule needs adjustment or if refactoring is needed.
• Document Exceptions: If the violation is acceptable, clearly document why in the code or as a test comment.

---

7. Best Practices for ArchUnit Tests

• Keep Rules Simple: Focus on writing rules that are easy to maintain and understand.
• Use Logging: Include meaningful logs for traceability.
• Document Exceptions: Clearly note any acceptable violations and their justification.

---

8. Conclusion

Integrating ArchUnit checks into your Java projects helps enforce architectural compliance, maintain consistency, and reduce technical debt. Regular use of ArchUnit tests ensures that your codebase remains maintainable and aligns with organizational standards, fostering a robust and scalable code environment.

Reference:

Use Cases

Introduction to ArchUnit | Baeldung

ArchUnit FAQ

1. What is ArchUnit?

ArchUnit is a testing library for Java that allows you to write tests to enforce architectural rules within your codebase. These rules can cover aspects such as package dependencies, class location, and usage of specific annotations.

2. Why should I use ArchUnit in my Java project?

ArchUnit offers a number of benefits, including:

• Ensuring Architectural Compliance: It automatically verifies your code adheres to predefined architectural principles, ensuring consistency and preventing architectural drift.
• Preventing Technical Debt: By catching architectural violations early, ArchUnit helps avoid long-term code issues and maintainability problems.
• Improving Code Quality: It promotes consistent code practices and standards across teams and projects, leading to more maintainable and readable code.
• Simplifying Code Reviews: ArchUnit tests can automate a significant portion of architectural checks, reducing the manual effort needed during code reviews.
• Seamless CI/CD Integration: It can be effortlessly integrated into build pipelines to ensure continuous validation of architectural rules with every build.

3. How does ArchUnit compare to other tools like AspectJ or Checkstyle?

While tools like AspectJ, Checkstyle, or FindBugs can also be used for verifying certain code rules, ArchUnit stands out for its specific focus on architectural testing. It offers a fluent API that is purely Java-based, making it easy to learn and integrate without introducing new languages or complex configurations.

Furthermore, ArchUnit is highly extensible. You can create custom rules and conditions beyond the standard predefined rules, giving you flexibility in defining your architectural constraints.

4. What are some best practices for writing effective ArchUnit tests?

• Keep rules simple and focused: Aim for clarity and maintainability. Complex rules can become difficult to understand and manage.
• Use descriptive naming and explanations: Clearly name your test methods and provide “because” clauses to explain the rationale behind each rule.
• Document exceptions thoughtfully: If certain violations are deemed acceptable, document them clearly in your code or test comments to explain the reasoning.
• Leverage logging for traceability: Include meaningful logs to track test execution and provide insights into potential issues.