ArchUnit is a powerful tool that has recently garnered the recognition it deserves. Typically regarded as a library for validating architectural structures in Java/JVM systems, its functionality extends far beyond, offering solutions to a myriad of everyday programming challenges. Unfortunately, many sources—including the official website—tend to focus narrowly on its application to architectural layer management and UML diagrams, which limits the tool's perceived versatility.

Introduction to ArchUnit's Capabilities

Contrary to popular belief, ArchUnit is not confined to analyzing cyclic dependencies and software layers. It also offers a robust, language-agnostic framework that enables teams to define and enforce coding conventions across various programming languages. This article delves into the true potential of ArchUnit, showcasing its flexibility to handle non-architectural issues and ultimately improve code quality and reliability.

Why Choose ArchUnit?

Using ArchUnit offers numerous benefits:

• Versatility: Not limited to architectural checks, ArchUnit can validate coding practices across multiple languages.
• Team Collaboration: Rules defined in Java can be shared with Kotlin or other JVM language teams.
• Integration: Simple integration with existing test frameworks like JUnit.
• Execution Speed: Fast rule execution even in large codebases.

Getting Started with ArchUnit

ArchUnit is lightweight, with minimal setup requirements. To integrate it with your project, simply add the following dependency:


testImplementation("com.tngtech.archunit:archunit-junit5:0.22.0")


Once added, you can start defining and running rules seamlessly with your existing JUnit tests. Here’s a basic example of a test using ArchUnit:


@AnalyzeClasses(packages = ["com.example"])
class ArchitectureTest {
@ArchTest
val noAnonymousClasses = noClasses().should().beAnonymousClasses()
}


Advanced Use Cases of ArchUnit

Detecting JUnit Misuse

JUnit’s heavy reliance on annotations can sometimes lead to overlooked mistakes that the compiler won't catch. Here’s an example of such a scenario:


@Test
fun testWithWrongAnnotation() = listOf("Test1", "Test2").forEach { dynamicTest("Test $it") { println("Running $it") } }

@TestFactory
fun testWithMissingReturn() {
listOf("Test1", "Test2").forEach { dynamicTest("Test $it") { println("Running $it") } }
}


In these cases, ArchUnit can enforce proper JUnit usage with the following rules:


@ArchTest
val testMethodsMustBeVoid = noMethods().should(beAnnotatedWith(Test::class.java).and(notHaveRawReturnType(Void.TYPE)))

@ArchTest
val testFactoryMustReturnListOrStream = noMethods().should(beAnnotatedWith(TestFactory::class.java).and(haveRawReturnType(List::class.java)})


These rules will ensure that methods annotated with @Test do not return any value and those annotated with @TestFactory properly return a list or stream of dynamic tests.

Preventing Dangerous Library Methods Usage

Some libraries contain methods that, while necessary, can lead to unpredictable behavior if misused. ArchUnit allows you to define rules to prevent the use of these methods, ensuring that developers adhere to safer coding practices. For example, you can prohibit the use of unsafe overloaded methods:


@ArchTest
val noUnsafeMethodCalls = noMethods().should(callMethod(String::class.java, "unsafeMethod", String::class.java))


This rule will ensure that any unsafe method calls are flagged during the build process, thereby improving code reliability.

Enforcing Uniqueness Constraints

Sometimes, libraries do not inherently enforce uniqueness constraints, leading to potential issues. For example, migration tools might allow duplicate ordinals, causing nondeterministic migrations. ArchUnit can help enforce these constraints:


@ArchTest
fun migrationsMustHaveDistinctOrder(classes: JavaClasses) {
val duplicatedMigrations = classes.filter { it.isAnnotatedWith(Migration::class.java) }
.groupBy { it.getAnnotationOfType(Migration::class.java).order }
.filter { (_, group) -> group.size > 1 }

org.assertj.core.api.Assertions.assertThat(duplicatedMigrations).isEmpty()
}


This rule will ensure that all migration annotations have unique orders, preventing potential execution issues.

Understanding ArchUnit’s Limitations

While ArchUnit is a powerful tool, it does have limitations. The most notable is its reliance on JVM bytecode, which suffers from type erasure. This means that certain type-specific checks are not possible:


// This rule won't work due to type erasure
noMethods().should(returnType(SecretKey::class.java))


ArchUnit provides methods like haveRawReturnType(), but due to type erasure, it cannot check generic return types like List or Mono. However, understanding these limitations allows you to work around them effectively by focusing on bytecode-level checks.

Conclusion: The Future of Code Quality with ArchUnit

ArchUnit is much more than a traditional architectural validation tool. Its flexibility and speed make it ideal for a variety of coding conventions and best practices that go beyond architecture. By integrating ArchUnit into your development process, you can automate the enforcement of coding standards, detect potential pitfalls early, and ultimately deliver more reliable and maintainable code.

Consider incorporating ArchUnit as part of your build pipeline to take advantage of its powerful capabilities. Not only will it assist in maintaining architectural integrity, but it will also ensure overall code quality, making it a valuable addition to any development team.

Ready to enhance your software projects with ArchUnit? Start today and discover the transformative benefits it brings to code quality and reliability.