Comparison ArchUnit vs. jQAssistant

Table of Contents

• Introduction to AU and jQA and software architecture
• Use Cases
  • UC Component Dependencies
    • AU layer dependency checks
    • jQA layer dependency checks
      • jQA layer definitions by PlantUML
      • jQA architecture test execution
        • jQA define known technical debt
        • jQA define the layering constraint
  • UC Class in wrong package
    • AU class in package check
    • jQA class in package check

This project was started as a copy of the ArchUnit Example project (cf. README.md). It’s purpose is the comparison of ArchJunit (AU for short) with software architecture testing by jQAssistant (abbreviated by jQA). We make use of the rich set of AU samples and try to set up a similar test in jQA to show the strengths and weaknesses of both approaches different use cases.

Introduction to AU and jQA and software architecture

TBD

Use Cases

The following use cases are compared in detail:

• UC Component Dependencies

• UC Class in wrong package

UC Component Dependencies

Software architectures usually are composed of layers, or shells around a core, or components in general. In Java the components may be implemented as separate build units (JARs), or simply as packages - or as build units containing particular packages. It is very uncommon and inconvenient to have packages which are spread to different JARs (at least beyond a common root package). The architecture describes the desired component model and the allowed dependencies between the components. Technically there are only dependencies (imports) between classes, but this model can be reduced to dependencies between packages: A package A is dependant on package B if any class in package A or in a sub-package of A imports a class from B (or a sub-package of B).

The sample architecture contains three layers

• controller

• service

• persistence

AU layer dependency checks

AU tests the layering by the following Test cases

AU layer dependency rules

link:src/test/java/com/tngtech/archunit/exampletest/LayerDependencyRulesTest.java[role=include]

1. Classes in the service package should not access controller classes

2. Classes in the persistence package must not access service classes

3. Classes in service should only be accessed by classes from controller classes and other service classes.

jQA layer dependency checks

jQA layer definitions by PlantUML

The jQAssistant part is described in detail by (and taken in large parts from) two blog posts

• http://techblog.kontext-e.de/executable-architecture-revisited/

• http://techblog.kontext-e.de/managing-technical-debt-with-arc42-and-jqassistant-dependencies/

The desired architectural model is given in a PlantUML section of src/doc/architecture/05_building_block_view.adoc describing the jQA layer dependencies.

jQA layer dependencies by PlantUML

link:doc/architecture/05_building_block_view.adoc[role=include]

jQA architecture test execution

In this case there are no predefined rules in jQA which allow to test the architectural layering. The comparison of the model with the implementation is performed by several queries in jqassistant/structure.adoc.

The jQA helper query to compute package depth assigns the package level (depth in the package containment tree) to each Java package.

jQA helper query to compute package depth

link:jqassistant/structure.adoc[role=include]

1. Find all Java packages

2. Compute package hierarchy as array splitted

3. Assign the level (depth) to each package as the length of the splitted array.

The query in jQA helper query to make transitive package dependency explicit then adds a an additional DEPENDS_ON relationship to parents of a package P from other packages up to the same level of the source package.

jQA helper query to make transitive package dependency explicit

link:jqassistant/structure.adoc[role=include]

Finally the query in jQA constraint to find architecture violations finds all packages which violate the architecture model.

jQA constraint to find architecture violations

link:jqassistant/structure.adoc[role=include]

1. Matches all packages from PlantUML with allowed dependencies

2. matches all Java packages

3. and

4. finally find packages which have a DEPENDS_ON relationship from <2> but are not covered by the MAY_DEPEND_ON relationship from <1> (note that p3 and p4 seem to be switched as compared to p1 and p2 to do the trick).

5. Will exclude allowed exceptions (cf. jQA define known technical debt)

6. Returns the matches (cf. jQA define the layering constraint).

jQA define known technical debt

An additional query was used to allow the definition of technical debt from an AsciiDoctor table in doc/architecture/05_building_block_view.adoc (cf. jQA add known technical debt, just remove the comment at the beginning of the line to make the test pass).

jQA add the definition of known technical debt

link:jqassistant/structure.adoc[role=include]

jQA add known technical debt

link:doc/architecture/05_building_block_view.adoc[role=include]

jQA define the layering constraint

In jqassistant/structure.adoc the last rule was defined with role=constraint (jQA define layering as constraint). If the query returns a non-empty result it is considered a problem. Since it is tagged as severity=critical it finally breaks the build.

jQA define layering as constraint

link:jqassistant/structure.adoc[role=include]

UC Class in wrong package

Software architectures often require that certain classes belong to particular packages, e.g.,

• DAO (Data Access Object) classes should be part of the .dao package hierarchy, or

• Entity classes (defined by the JPA @Entity annotation) should be defined in .domain packages.

AU class in package check

AU provides several checks for the persistence component in src/test/java/com/tngtech/archunit/exampletest/DaoRulesTest.java.

AU checks if all DAO classes reside in a dao package

link:src/test/java/com/tngtech/archunit/exampletest/DaoRulesTest.java[role=include]

AU checks if all @Entity annotated classes reside in a domain package

link:src/test/java/com/tngtech/archunit/exampletest/DaoRulesTest.java[role=include]

jQA class in package check

The corresponding tests for jQA are implemented in jqassistant/daorules.adoc.

jqassistant/daorules.adoc