ArchUnit-Examples ships four failing architecture test projects, on purpose

Four subprojects, one per way of running an architecture test

ArchUnit is a Java architecture test library for specifying and asserting architecture rules in plain Java, and this repository exists to show how to use the latest release of it.

The structure is four subprojects, one per integration style:

- `example-junit4` shows how to use the JUnit 4 test support including the `ArchUnitRunner` - `example-junit5` shows how to use the JUnit 5 test support, where test classes are picked up simply by being annotated with `@AnalyzeClasses` - `example-junit6` shows the same thing for JUnit 6, with test classes picked up by the `@AnalyzeClasses` annotation - `example-plain` shows how to use ArchUnit independently of any specific test framework, even though as a runtime environment these tests use JUnit 4 as well

The spread across three JUnit generations is the point of the exercise. The mechanism changed between them. JUnit 4 needs an explicit runner wired into the test class, while the JUnit 5 and JUnit 6 examples rely on the engine discovering the class because of the annotation. The plain example is the fallback for teams whose build is not on JUnit 5 or 6, and the note that it still runs on JUnit 4 at runtime is there so nobody mistakes it for a test-framework-free build.

Everything here is Java, the licence is Apache-2.0, and the default branch is main.

Every example rule fails, and that is the design

The single most important thing to know before you run this repository is that the tests are supposed to fail.

The project states it directly. All example rules found within `src/test` refer to classes from `src/main`, and these tests are all designed to fail, to demonstrate how production code could violate typical architectural constraints, like layer dependencies.

That framing changes how you should read the output. A red build here is the correct outcome, and a green build would actually be a sign that something is wrong with your setup, because the example code deliberately contains the dependency violation the rules are looking for. The rules reference real classes in the main source tree, so the failure messages show you a genuine architecture violation being detected and described, not a synthetic error.

The two halves of the layout, `src/main` and `src/test`, are the whole teaching device. Production classes live in one, the rules that judge them live in the other, and the rules are written so that they fire.

For a team evaluating architecture testing, this is a useful property. You can see what a violation report looks like, with the class names and the dependency paths spelled out, without having to write a violating codebase yourself. It is also a trap for the unwary: a CI pipeline that runs these subprojects as if they were a real project's test suite will go red, and the fix is not to make the tests pass.

Running them with Gradle, with Maven, or from the IDE

Three ways to run the examples are given, and the choice is mostly about which build you already have.

With Gradle, using the provided `build.gradle` scripts:

  ./gradlew test

With Maven, using the provided `pom.xml` files in the same directories:

  ./mvnw test 

Or directly from your IDE.

The repository is set up to be buildable either way, and that is visible in the top level layout. There is a `gradlew` and `gradlew.bat` at the root alongside a `gradle/` directory, a root `pom.xml` with a `.mvn/` directory, and `mvnw` and `mvnw.cmd`. There is a root `build.gradle` and a `settings.gradle` too, so the multi-project structure is declared for Gradle, and each example subproject carries its own build files.

The wrappers are the detail worth noting. Using `./gradlew` and `./mvnw` means the build runs against a pinned Gradle and Maven version without installing either on the machine, which matters for an examples repository that people clone on whatever laptop they have. Note that the Maven invocation in the project text carries a trailing space after `test`, which is harmless but is a small sign these files are generated rather than hand maintained.

The four subprojects, `example-junit4`, `example-junit5`, `example-junit6`, and `example-plain`, are the actual content. The example directory listing also shows an `example/CMakeLists.txt` and `example/main.cpp` in the file listing for the repository, which belongs to the wider set of example files rather than to these Java subprojects.

This repository is generated, so the main project is where changes belong

The provenance of this repository is stated in the project text and it changes how you should treat it.

This repository is an autogenerated version of the latest released version of the archunit-example directory in the main ArchUnit repository, with some simplified project setup for illustration. The archunit-example directory in the main repository is therefore the source of truth, and this copy is a published snapshot of a released state.

Two things follow. First, the simplification is deliberate. The project setup has been reduced to make the examples readable, so if you copy the build configuration from here you will get something simpler than a real project needs. Second, the snapshot nature means this copy does not track main. If ArchUnit releases a new version with new example subprojects, they appear in the main repository first and reach this repository at the next regeneration.

The issue routing is stated for the same reason. If you have found any issues with the examples or have any question, please direct them to the main repository instead. So a bug report about an example belongs at the ArchUnit issue tracker, and a question about which integration style to use belongs there too.

The top level layout supports that reading. There is a CONTRIBUTING.md, a LICENSE, a NOTICE file, a .gitignore, and a project description file, but there is no source code of its own outside the example subprojects. This is a publication repository, not a development one.

The last push was on 2026-09-25 and the repository has no GitHub releases, which is consistent with a repository that is regenerated rather than tagged.

What these examples do not tell you

Two gaps are worth naming before you adopt anything from here.

The first is that you will not find a catalogue of ready to use rules in this repository. The examples demonstrate the wiring: how a test class is picked up, how a rule is asserted, and what a violation report looks like. The rules themselves are illustrative and they are constructed to fire. Copying one wholesale into a real project means copying a rule that describes the example's deliberately broken layer structure, not a rule that describes your architecture.

The second is that the project text does not document the ArchUnit version this repository pins, the Java version, or the exact contents of the four example subprojects beyond the one line descriptions quoted earlier. It says the examples use the latest release of ArchUnit, and it mentions the JUnit 4, JUnit 5, JUnit 6, and framework independent setups, but the version coordinates live in the build files rather than in the write-up. Anyone evaluating this should open the `pom.xml` and `build.gradle` files directly rather than infer versions from the text.

A third observation is about the plain example. It shows ArchUnit used independently of any specific test framework, and the note that the runtime environment still uses JUnit 4 is honest about the fact that no framework here means no ArchUnit-specific integration, not no test runner at all. If your build has no JUnit dependency whatsoever, this example does not demonstrate a completely standalone usage, because it still relies on JUnit 4 to execute.

The comparison with writing the checks by hand is straightforward. ArchUnit makes the assertions about dependencies declarative and produces readable failure output, and these examples show the integration points that make that work in each JUnit generation. A team that has never used the library will spend more time on the annotation and runner wiring than on the rules, and that is exactly the gap this repository fills.

Editorial conclusion

ArchUnit-Examples fits a Java team that has already decided to adopt ArchUnit and needs to see how the library attaches to their test runner, since the four subprojects cover JUnit 4, JUnit 5, JUnit 6 and a framework independent setup. It does not fit a team still deciding whether architecture tests are worth the effort, because every rule here is written to fail on purpose and there is no catalogue of production ready rules to copy. Before copying anything, look at the archunit-example directory in the main ArchUnit repository, since this repository is an autogenerated copy of it with a simplified project setup, and send any questions to the main repository's issue tracker.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. TNG/ArchUnit-Examples on GitHub