Article 3 : Intégration de Jackson pour le Parsing YAML avec TDD dans un Plugin Gradle

Publié le 25 September 2025

1. Introduction

Public cible : Développeurs Gradle intermédiaires souhaitant gérer des configurations complexes.

Dans le développement de plugins Gradle, la gestion de configurations complexes est une tâche courante. Plutôt que de surcharger le DSL avec des centaines de propriétés, il est souvent plus propre et plus maintenable de définir la configuration dans un fichier externe, comme le YAML. Cet article vous guide à travers l’intégration de la puissante bibliothèque Jackson pour parser des fichiers YAML en objets Kotlin, en adoptant une approche TDD rigoureuse pour garantir la robustesse de notre plugin site-baker.

2. 1. Le Contexte : Notre Plugin site-baker

Notre plugin site-baker est conçu pour automatiser la génération et le déploiement d’un site statique. Il a besoin de lire un fichier de configuration YAML (managed-jbake-context.yml) pour obtenir des informations telles que les chemins des sources, les destinations de déploiement, et les identifiants Git.

La configuration YAML que nous souhaitons parser ressemble à ceci :

bake:
  srcPath: "./site/jbake"
  destDirPath: "bake"
  cname: "cheroliv.com"
pushPage:
  from: "bake"
  to: "cvs"
  repo:
    name: "trainings"
    repository: "https://github.com/pages-content/pages-content.github.io.git"
    credentials:
      username: "USERNAME"
      password: "SECRET_TOKEN"
  branch: "main"
  message: "cheroliv.com"
# ... autres configurations (pushMaquette, supabase, etc.)

3. 2. Modélisation de la Configuration en Kotlin

Avant de parser, nous devons définir la structure de nos données en Kotlin. Jackson utilisera ces classes pour mapper automatiquement le contenu YAML.

// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt
package com.cheroliv.site.baker.data

import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory
import com.fasterxml.jackson.module.kotlin.readValue
import com.fasterxml.jackson.module.kotlin.registerKotlinModule

fun parseSiteConfiguration(yaml: String): SiteConfiguration {
    val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule()
    return mapper.readValue(yaml)
}

data class GitPushConfiguration(
    val from: String = "",
    val to: String = "",
    val repo: RepositoryConfiguration = RepositoryConfiguration(),
    val branch: String = "",
    val message: String = "",
)

data class RepositoryConfiguration(
    val name: String = "",
    val repository: String = "",
    val credentials: RepositoryCredentials = RepositoryCredentials(),
) {
    companion object {
        const val ORIGIN = "origin"
        const val CNAME = "CNAME"
        const val REMOTE = "remote"
    }
}

data class RepositoryCredentials(val username: String = "", val password: String = "")

data class SiteConfiguration(
    val bake: BakeConfiguration = BakeConfiguration(),
    val pushPage: GitPushConfiguration = GitPushConfiguration(),
    val pushMaquette: GitPushConfiguration = GitPushConfiguration(),
    val pushSource: GitPushConfiguration? = null,
    val pushTemplate: GitPushConfiguration? = null,
    val supabase: SupabaseContactFormConfig? = null
)

data class BakeConfiguration(
    val srcPath: String = "",
    val destDirPath: String = "",
    val cname: String? = null,
)

// ... (autres data classes pour Supabase, si nécessaire)

La fonction parseSiteConfiguration est notre point d’entrée pour la désérialisation. Elle utilise ObjectMapper de Jackson, configuré avec YAMLFactory pour le format YAML et registerKotlinModule() pour le support des spécificités de Kotlin (comme les valeurs par défaut des propriétés).

4. 3. Intégration de Jackson dans le build.gradle.kts

Pour utiliser Jackson, nous devons ajouter les dépendances nécessaires dans le build.gradle.kts de notre module plugin :

// plugin/build.gradle.kts
dependencies {
    // Jackson for YAML parsing
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3")
    implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3")

    // ... autres dépendances
}

Nous utilisons jackson-module-kotlin pour le support de Kotlin et jackson-dataformat-yaml pour la gestion du format YAML.

5. 4. L’Approche TDD : Tester le Parsing YAML

Maintenant, appliquons le TDD pour valider notre logique de parsing.

5.1. 4.1. Test Unitaire : Mapper le YAML en Objet Kotlin

Nous commençons par un test unitaire dans SiteBakerPluginTest.kt pour vérifier que la fonction parseSiteConfiguration peut correctement transformer une chaîne YAML en un objet SiteConfiguration.

// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt
@Test
fun `can map configuration text to SiteConfiguration object`() {
    val yamlString = "../../managed-jbake-context.yml"
        .run(::File)
        .readText()
        .trimIndent()

    val config: SiteConfiguration = parseSiteConfiguration(yamlString)

    assertEquals("cheroliv.com", config.bake.cname)
    assertEquals("main", config.pushPage.branch)
    assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository)
}

Ce test lit le contenu du fichier managed-jbake-context.yml (qui doit exister pour que le test soit valide) et effectue des assertions sur l’objet SiteConfiguration résultant. Il valide que les valeurs clés du YAML sont correctement mappées.

5.2. 4.2. Test Fonctionnel : Valider la Lecture du Fichier de Configuration

Pour s’assurer que le plugin peut lire le fichier de configuration via son DSL et que le parsing fonctionne dans un environnement Gradle réel, nous ajoutons un test fonctionnel dans SiteBakerPluginFunctionalTest.kt.

Ce test est crucial car il simule l’exécution du plugin dans un projet réel. Il doit être hermétique, c’est-à-dire qu’il doit créer lui-même le fichier managed-jbake-context.yml avec un contenu contrôlé, pour garantir la reproductibilité et l’isolation du test.

// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt
@Test
fun `config file contains good data`(){
    val configContent = configFile.readText(UTF_8)
    // Vérifications comme dans vos commentaires
    assertTrue(configContent.contains("bake"))
    assertTrue(configContent.contains("pushPage"))
    assertTrue(configContent.contains("repository"))
}

Ce test fonctionnel vérifie que le fichier de configuration copié dans le répertoire temporaire du test contient les données attendues. Bien que ce test ne parse pas directement le YAML en objet Kotlin, il valide la présence du fichier et de son contenu, ce qui est une étape préalable essentielle au parsing par le plugin.

6. 5. Visualisation du Flux de Parsing

Le diagramme suivant illustre le flux de données et les interactions lors du parsing de la configuration YAML :

Diagram

7. Conclusion

En suivant une approche TDD, nous avons intégré avec succès la bibliothèque Jackson pour parser des fichiers de configuration YAML en objets Kotlin au sein de notre plugin Gradle. Cette méthode nous a permis de :

  • Modéliser clairement notre configuration avec des data classes Kotlin.

  • Valider la logique de parsing avec des tests unitaires ciblés.

  • Assurer l’intégration dans un environnement Gradle réel grâce à des tests fonctionnels hermétiques.

Cette base solide nous offre une grande confiance pour étendre notre plugin avec des fonctionnalités qui s’appuient sur cette configuration, tout en garantissant la maintenabilité et la robustesse du code. Le parsing YAML est désormais une fonctionnalité fiable et testée de notre plugin site-baker.