Tests d’Architecture avec ArchUnit

Les tests d’architecture garantissent automatiquement le respect de l’architecture hexagonale.

Sans tests automatisés, rien n’empêche un développeur de violer l’architecture. ArchUnit est la solution !

Pourquoi des Tests d’Architecture ?

❌ Problème

Le Problème Sans Tests

Sans tests automatisés, rien n’empêche un développeur de faire ça :


// ❌ VIOLATION : Le domain dépend de l'infrastructure
package org.smoka.domain.model;
 
import org.smoka.infrastructure.adapter.TrendRepositoryAdapter; // ❌ INTERDIT !
 
public class TrendResult {
    private TrendRepositoryAdapter adapter; // ❌ Le domain ne doit pas connaître les adapters
}

Ou ça :


// ❌ VIOLATION : L'application dépend de l'infrastructure
package org.smoka.application.usecase;
 
import org.smoka.infrastructure.adapter.TrendRepositoryAdapter; // ❌ INTERDIT !
 
public class GetTrendsUseCase {
    private TrendRepositoryAdapter adapter; // ❌ Doit dépendre de l'interface TrendRepository
}

Conséquences :

❌ Architecture compromise
❌ Couplage fort
❌ Impossible de changer d’implémentation
❌ Tests difficiles

✅ Solution

Solution : ArchUnit

Avec ArchUnit, ces violations sont automatiquement détectées et les tests échouent !


[ERROR] Tests run: 15, Failures: 1
[ERROR] domainShouldNotDependOnAnything:49
  Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in a
  package '..domain..' should depend on classes that reside in any package
  ['..infrastructure..']' was violated (1 times):

  Class <org.smoka.domain.model.trends.TrendResult> depends on class
  <org.smoka.infrastructure.adapter.TrendRepositoryAdapter>
  in (TrendResult.java:5)

Avantages :

✅ Détection automatique des violations
✅ Intégration CI/CD
✅ Documentation vivante de l’architecture
✅ Feedback immédiat pour les développeurs

Résultat

Résultat

Le build échoue, impossible de merger le code ! 🚫


[ERROR] BUILD FAILURE
[INFO] There are test failures.

✅ Architecture protégée
✅ Revue de code automatisée
✅ Qualité garantie
✅ Équipe alignée sur les règles

Installation

Ajouter la dépendance Maven

Ajoutez ArchUnit dans votre pom.xml :


<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>1.3.0</version>
    <scope>test</scope>
</dependency>

Créer le fichier de test

Créez le fichier suivant :

Configurer le setup


@BeforeAll
static void setup() {
    // Importe toutes les classes du projet
    classes = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .withImportOption(location -> !location.contains("$")) // Exclure classes générées
            .importPackages("org.smoka");
}

Important :

DO_NOT_INCLUDE_TESTS : Exclut les classes de test
!location.contains("$") : Exclut les classes générées par Micronaut, Lombok et le compilateur

Règles d’Architecture

1. Règles de Dépendances entre Couches

Domain Indépendant

Le DOMAIN ne dépend de RIEN


@Test
void domainShouldNotDependOnAnything() {
    noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat().resideInAnyPackage(
            "..application..",
            "..infrastructure.."
        )
        .check(classes);
}

Vérifie que :

domain/model/TrendQuery.java ne dépend PAS de application/
domain/model/TrendResult.java ne dépend PAS de infrastructure/
domain/port/output/TrendRepository.java ne dépend PAS de frameworks

Autorisé :

✅ java.* (Collections, LocalDateTime, Optional, etc.)
✅ lombok.* (annotations pour réduire le boilerplate)
✅ Autres classes du domain/

Interdit :

❌ io.micronaut.*
❌ jakarta.persistence.*
❌ application.*
❌ infrastructure.*

Application → Domain

L’APPLICATION ne dépend PAS de l’INFRASTRUCTURE


@Test
void applicationShouldNotDependOnInfrastructure() {
    noClasses()
        .that().resideInAPackage("..application..")
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
        .check(classes);
}

Vérifie que :

GetTrendsUseCase dépend de TrendRepository (interface) ✅
GetTrendsUseCase ne dépend PAS de MockTrendRepositoryAdapter ❌

Principe : Inversion de dépendances


✅ BON
GetTrendsUseCase → TrendRepository (interface)
                        ↑
                        | implements
        MockTrendRepositoryAdapter

❌ MAUVAIS
GetTrendsUseCase → MockTrendRepositoryAdapter (implémentation concrète)

Architecture en Couches

Architecture en Couches Respectée


@Test
void layeredArchitectureShouldBeRespected() {
    layeredArchitecture()
        .consideringOnlyDependenciesInLayers() // Ignore java.*, lombok.*, etc.
 
        .layer("Domain").definedBy("..domain..")
        .layer("Application").definedBy("..application..")
        .layer("Infrastructure").definedBy("..infrastructure..")
 
        .whereLayer("Domain").mayNotAccessAnyLayer()
        .whereLayer("Application").mayOnlyAccessLayers("Domain")
        .whereLayer("Infrastructure").mayOnlyAccessLayers("Domain", "Application")
 
        .check(classes);
}

.consideringOnlyDependenciesInLayers() permet d’ignorer les dépendances vers les packages standards (java.*, lombok.*, etc.) qui ne font pas partie de notre architecture.

Flux de dépendances autorisé :


Infrastructure → Application → Domain
                              ↑
                              |
                    (Domain ne dépend de RIEN)

2. Règles des Ports de Sortie

Ports = Interfaces

Les Ports de Sortie sont des INTERFACES


@Test
void outputPortsShouldBeInterfacesInDomain() {
    classes()
        .that().resideInAPackage("..domain.port.output..")
        .should().beInterfaces()
        .check(classes);
}

Vérifie que :

TrendRepository.java est bien une interface ✅
Pas de classes concrètes dans domain/port/output/ ❌

Les ports de sortie sont des contrats que l’infrastructure doit respecter.

Nommage

Nommage des Ports de Sortie


@Test
void outputPortsShouldHaveCorrectNaming() {
    classes()
        .that().resideInAPackage("..domain.port.output..")
        .should().haveSimpleNameEndingWith("Repository")
        .orShould().haveSimpleNameEndingWith("Port")
        .check(classes);
}

Convention :

✅ TrendRepository.java
✅ NotificationPort.java
❌ TrendService.java (pas dans domain/port/output/)

Exemple

Exemple de Port de Sortie


// domain/port/output/TrendRepository.java
package org.smoka.domain.port.output;
 
import org.smoka.domain.model.trends.TrendQuery;
import org.smoka.domain.model.trends.TrendResult;
 
import java.util.Optional;
 
public interface TrendRepository {
    /**
     * Récupère les tendances pour une requête donnée.
     *
     * @param query La requête contenant le mot-clé et la région
     * @return Un Optional contenant le résultat, ou vide si non trouvé
     */
    Optional<TrendResult> getTrends(TrendQuery query);
}

3. Règles des Adaptateurs

Adapters → Ports

Les Adaptateurs Implémentent des Ports


@Test
void adaptersShouldImplementDomainPorts() {
    classes()
        .that().resideInAPackage("..infrastructure.adapter..")
        .and().haveSimpleNameEndingWith("Adapter")
        .should().dependOnClassesThat().resideInAPackage("..domain.port.output..")
        .check(classes);
}

Vérifie que :

MockTrendRepositoryAdapter dépend de TrendRepository (interface du domain) ✅
Si un adapter n’implémente aucun port, le test échouera ❌

On utilise dependOnClassesThat() au lieu de implement() car c’est plus flexible et fonctionne avec l’API ArchUnit.

Nommage

Nommage des Adaptateurs


@Test
void adaptersShouldHaveCorrectNaming() {
    classes()
        .that().resideInAPackage("..infrastructure.adapter..")
        .should().haveSimpleNameEndingWith("Adapter")
        .check(classes);
}

Convention :

✅ MockTrendRepositoryAdapter.java
✅ GoogleTrendsApiAdapter.java
❌ TrendService.java

Exemple

Exemple d’Adaptateur


// infrastructure/adapter/MockTrendRepositoryAdapter.java
@Singleton
public class MockTrendRepositoryAdapter implements TrendRepository {
 
    @Override
    public Optional<TrendResult> getTrends(TrendQuery query) {
        // Génère des données mockées
        TrendResult result = TrendResult.builder()
            .keyword(query.getKeyword())
            .region(query.getRegion())
            .interestScore(generateRandomScore())
            .build();
 
        return Optional.of(result);
    }
}

4. Règles des Use Cases

Package Correct

Les Use Cases sont dans le Bon Package


@Test
void useCasesShouldResideInCorrectPackage() {
    classes()
        .that().haveSimpleNameEndingWith("UseCase")
        .should().resideInAPackage("..application.usecase..")
        .check(classes);
}

Convention de nommage :

✅ GetTrendsUseCase dans application.usecase/
❌ TrendService dans application.service/

Pas d’Infrastructure

Les Use Cases ne Dépendent PAS de l’Infrastructure


@Test
void useCasesShouldNotDependOnInfrastructure() {
    noClasses()
        .that().resideInAPackage("..application.usecase..")
        .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
        .check(classes);
}

Principe : Les use cases dépendent des interfaces (ports), pas des implémentations.

Exemple

Exemple de Use Case


// application/usecase/GetTrendsUseCase.java
@Singleton
@RequiredArgsConstructor
public class GetTrendsUseCase {
 
    private final TrendRepository trendRepository; // ✅ Interface du domain
 
    public TrendResult execute(String keyword, String region) {
        TrendQuery query = new TrendQuery(keyword, region);
 
        return trendRepository.getTrends(query)
            .orElseThrow(() -> new TrendNotFoundException(keyword, region));
    }
}

5. Règles du Domain

Domain Pur

Le Domain est PUR (pas d’annotations framework)


@Test
void domainModelsShouldNotHaveFrameworkAnnotations() {
    noClasses()
        .that().resideInAPackage("..domain.model..")
        .should().dependOnClassesThat().resideInAnyPackage(
            "io.micronaut..",
            "jakarta.persistence..",
            "org.springframework.."
        )
        .check(classes);
}

Vérifie que :

❌ Pas de @Entity JPA
❌ Pas de @Singleton Micronaut
❌ Pas de @Component Spring
✅ Seulement @Data, @Builder Lombok (acceptable car annotations de compilation)

Java + Lombok Uniquement

Le Domain Utilise Seulement Java Standard + Lombok


@Test
void domainModelsCanUseLombokAndJavaStandard() {
    classes()
        .that().resideInAPackage("..domain.model..")
        .should().onlyDependOnClassesThat().resideInAnyPackage(
            "java..",
            "lombok..",
            "..domain.."
        )
        .check(classes);
}

Le domain reste portable et testable sans aucune dépendance framework.

Exemple

Exemple de Modèle Domain Pur


// domain/model/trends/TrendResult.java
@Value
@Builder
public class TrendResult {
    String keyword;
    String region;
    Integer interestScore;
    List<RelatedTopic> relatedTopics;
    LocalDateTime queriedAt;
 
    // Règles métier
    public boolean isPopular() {
        return interestScore > 70;
    }
 
    public String getPopularityLevel() {
        if (interestScore >= 90) return "VERY_HIGH";
        if (interestScore >= 70) return "HIGH";
        if (interestScore >= 40) return "MEDIUM";
        return "LOW";
    }
}

6. Règles des Controllers

Pas de Logique Métier

Les Controllers ne Contiennent PAS de Logique Métier


@Test
void controllersShouldNotContainBusinessLogic() {
    noClasses()
        .that().resideInAPackage("..application.port.input..")
        .and().haveSimpleNameEndingWith("Controller") // Seulement les *Controller
        .should().dependOnClassesThat().resideInAPackage("..domain.model..")
        .check(classes);
}

Principe : Les controllers délèguent aux use cases, ils ne manipulent pas le domain directement.

Note importante : Cette règle s’applique uniquement aux classes *Controller. Les DTOs peuvent (et doivent) dépendre du domain pour faire le mapping.

DTOs OK

Les DTOs Peuvent Dépendre du Domain

Autorisé :


// ✅ DTO mappe depuis le domain
public class TrendResponseDto {
    public static TrendResponseDto fromDomain(TrendResult result) {
        return TrendResponseDto.builder()
                .keyword(result.getKeyword()) // ✅ Les DTOs peuvent accéder au domain
                .region(result.getRegion())
                .build();
    }
}

Interdit dans le Controller :


// ❌ Controller manipule directement le domain
@Controller
public class TrendController {
    public TrendResponseDto getTrends(String keyword) {
        TrendResult result = new TrendResult(...); // ❌ Création directe du domain model
        result.calculateScore(); // ❌ Logique métier dans le controller
        return TrendResponseDto.from(result);
    }
}

Exemple

Exemple de Controller Correct


// application/port/input/TrendController.java
@Controller("/api/trends")
@RequiredArgsConstructor
public class TrendController {
 
    private final GetTrendsUseCase useCase;
 
    @Get
    public TrendResponseDto getTrends(
        @QueryValue @NotBlank String keyword,
        @QueryValue(defaultValue = "US") String region
    ) {
        // ✅ Controller délègue au use case
        TrendResult result = useCase.execute(keyword, region);
 
        // ✅ Conversion via DTO
        return TrendResponseDto.fromDomain(result);
    }
}

Lancer les Tests

Maven

Via Maven


mvn test -Dtest=HexagonalArchitectureTest

Ou dans votre cycle de build complet :


mvn clean test

Résultat Success

Résultat en Cas de Succès


[INFO] Running org.smoka.architecture.HexagonalArchitectureTest
[INFO] Tests run: 15, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  12.345 s

Toutes les règles d’architecture sont respectées ! ✅

Résultat Failure

Résultat en Cas de Violation


[ERROR] domainShouldNotDependOnAnything FAILED
  Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in a
  package '..domain..' should depend on classes that reside in any package
  ['..infrastructure..']' was violated (1 times):

  Class <org.smoka.domain.model.trends.TrendResult> depends on class
  <org.smoka.infrastructure.adapter.TrendRepositoryAdapter>
  in (TrendResult.java:5)

[INFO] BUILD FAILURE

Le build échoue → impossible de merger le code ! 🚫

Cas d’Usage Réels

Cas 1: JPA dans Domain

Cas 1 : Quelqu’un ajoute une dépendance JPA dans le Domain

Code violant l’architecture :


// ❌ domain/model/TrendResult.java
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
 
@Entity // ❌ VIOLATION !
public class TrendResult {
    @Id
    private Long id;
}

Test qui échoue :


domainModelsShouldNotHaveFrameworkAnnotations FAILED
  Class <TrendResult> depends on <jakarta.persistence.Entity>

Solution :


// ✅ domain/model/TrendResult.java
@Value
@Builder
public class TrendResult {
    Long id; // Pas d'annotation JPA
}

Cas 2: Use Case → Adapter

Cas 2 : Un Use Case dépend directement d’un Adapter

Code violant l’architecture :


// ❌ application/usecase/GetTrendsUseCase.java
 
import org.smoka.infrastructure.adapter.TrendRepositoryAdapter; // ❌ VIOLATION !
 
public class GetTrendsUseCase {
    private TrendRepositoryAdapter adapter; // ❌ Doit être TrendRepository (interface)
}

Test qui échoue :


applicationShouldNotDependOnInfrastructure FAILED
  Class <GetTrendsUseCase> depends on <MockTrendRepositoryAdapter>

Solution :


// ✅ application/usecase/GetTrendsUseCase.java
 
import org.smoka.domain.port.output.TrendRepository; // ✅ Interface
 
public class GetTrendsUseCase {
    private final TrendRepository repository; // ✅ Dépend de l'interface
}

Cas 3: Controller → Domain

Cas 3 : Un Controller crée directement des objets du Domain

Code violant l’architecture :


// ❌ application/port/input/TrendController.java
 
import org.smoka.domain.model.trends.TrendResult; // ❌ VIOLATION !
 
@Controller
public class TrendController {
    public TrendResponseDto getTrends(String keyword) {
        TrendResult result = new TrendResult(...); // ❌ Logique métier dans le controller
        return TrendResponseDto.from(result);
    }
}

Test qui échoue :


controllersShouldNotContainBusinessLogic FAILED
  Class <TrendController> depends on <TrendResult> (domain model)

Solution :


// ✅ application/port/input/TrendController.java
@Controller
@RequiredArgsConstructor
public class TrendController {
    private final GetTrendsUseCase useCase; // ✅ Délègue au use case
 
    @Get
    public TrendResponseDto getTrends(@QueryValue String keyword) {
        TrendResult result = useCase.execute(keyword, "US"); // ✅ Use case fait le travail
        return TrendResponseDto.fromDomain(result); // ✅ DTO fait la conversion
    }
}

Intégration CI/CD

GitHub Actions

GitHub Actions


name: Architecture Tests
 
on: [push, pull_request]
 
jobs:
  architecture-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'
 
      - name: Run Architecture Tests
        run: mvn test -Dtest=HexagonalArchitectureTest

Résultat : Impossible de merger si l’architecture est violée ! 🚫

GitLab CI

GitLab CI


architecture-tests:
  stage: test
  image: maven:3.9-eclipse-temurin-21
  script:
    - mvn test -Dtest=HexagonalArchitectureTest
  only:
    - merge_requests
    - master
  artifacts:
    when: on_failure
    reports:
      junit: target/surefire-reports/TEST-*.xml

Jenkins

Jenkins Pipeline


pipeline {
    agent any
    stages {
        stage('Architecture Tests') {
            steps {
                sh 'mvn test -Dtest=HexagonalArchitectureTest'
            }
        }
    }
    post {
        always {
            junit 'target/surefire-reports/*.xml'
        }
    }
}

Ajouter une Nouvelle Règle

System.out.println

Exemple : Interdire l’utilisation de System.out.println


@Test
@DisplayName("Ne pas utiliser System.out.println (utiliser un logger)")
void shouldNotUseSystemOutPrintln() {
    ArchRule rule = noClasses()
        .should().callMethod(System.class, "out")
        .because("Utiliser un logger (SLF4J) au lieu de System.out.println");
 
    rule.check(classes);
}

Cette règle force les développeurs à utiliser un logger au lieu de System.out.println.

DTOs dans Package

Exemple : Les DTOs doivent être dans le bon package


@Test
@DisplayName("Les DTOs doivent résider dans application.port.input.dto")
void dtosShouldResideInCorrectPackage() {
    ArchRule rule = classes()
        .that().haveSimpleNameEndingWith("Dto")
        .should().resideInAPackage("..application.port.input.dto..")
        .because("Convention de nommage et placement des DTOs");
 
    rule.check(classes);
}

Cycles de Dépendances

Exemple : Détecter les Cycles de Dépendances


@Test
@DisplayName("Pas de cycles de dépendances entre packages")
void shouldBeFreeOfCycles() {
    slices()
        .matching("org.smoka.(*)..")
        .should()
        .beFreeOfCycles()
        .check(classes);
}

Les cycles de dépendances créent du couplage et rendent le code difficile à maintenir.

Résumé

ArchUnit garantit automatiquement que votre architecture hexagonale est respectée !

Règle	Vérifie	Empêche
`domainShouldNotDependOnAnything`	Domain indépendant	Couplage au framework
`applicationShouldNotDependOnInfrastructure`	Inversion de dépendances	Couplage fort
`layeredArchitectureShouldBeRespected`	Architecture en couches	Violations de flux
`outputPortsShouldBeInterfaces`	Ports = contrats	Implémentations dans le domain
`adaptersShouldImplementDomainPorts`	Adaptateurs dépendent des ports	Adaptateurs isolés
`domainModelsShouldNotHaveFrameworkAnnotations`	Domain pur	Couplage JPA/Micronaut
`controllersShouldNotContainBusinessLogic`	Séparation des responsabilités	Logique dans controllers

Notes importantes :

✅ Les DTOs peuvent dépendre du domain pour le mapping
✅ Les classes générées (Micronaut $Definition, Lombok) sont exclues automatiquement
✅ Les dépendances vers java.*, lombok.* sont ignorées dans les règles de couches

Checklist

Avant de commit :

mvn test -Dtest=HexagonalArchitectureTest passe ✅
Le domain ne dépend de rien
L’application ne dépend pas de l’infrastructure
Les adaptateurs implémentent des interfaces du domain
Les controllers ne contiennent pas de logique métier
Les DTOs sont dans le bon package

Prochaines étapes

Maintenant que votre architecture est protégée, explorez comment tester votre code efficacement.

Tests Unitaires → - Tester la logique métier
Tests d’Intégration → - Tester les endpoints
Pièges Courants → - Éviter les erreurs

Tests d’Architecture avec ArchUnit

Pourquoi des Tests d’Architecture ?

❌ Problème

✅ Solution

Résultat

Installation

Ajouter la dépendance Maven

Créer le fichier de test

Configurer le setup

Règles d’Architecture

1. Règles de Dépendances entre Couches

Domain Indépendant

Application → Domain

Architecture en Couches

2. Règles des Ports de Sortie

Ports = Interfaces

Nommage

Exemple

3. Règles des Adaptateurs

Adapters → Ports

Nommage

Exemple

4. Règles des Use Cases

Package Correct

Pas d’Infrastructure

Exemple

5. Règles du Domain

Domain Pur

Java + Lombok Uniquement

Exemple

6. Règles des Controllers

Pas de Logique Métier

DTOs OK

Exemple

Lancer les Tests

Maven

Résultat Success

Résultat Failure

Cas d’Usage Réels

Cas 1: JPA dans Domain

Cas 2: Use Case → Adapter

Cas 3: Controller → Domain

Intégration CI/CD

GitHub Actions

GitLab CI

Jenkins

Ajouter une Nouvelle Règle

System.out.println

DTOs dans Package

Cycles de Dépendances

Résumé

Checklist

Prochaines étapes

Ressources