TDD di un Plugin Gradle Kotlin configurabile con JBake e JGit

Sommaire

Obiettivo
Configuration déclarative
Architettura del plugin
Definizione dell’estensione DSL
Definizione del compito personalizzato
Interfaccia GitAdapter
Implementazione concreta con JGit
Configurazione DSL Kotlin
Test unitari con Mockito
- Dipendenze
- Test del comportamento Git
Conclusione
Prossimi passi

Questo articolo presenta l’intero approccio di progettazione e di test (TDD) di un plugin Gradle scritto in Kotlin DSL. Questo plugin automatizza la generazione di siti statici con JBake e il deployment Git tramite JGit, il tutto a partire da un file YAML di configurazione.

Obiettivo

Creare un plugin Gradle :

configurabile in Kotlin DSL ;
capace di:
generare un sito statico da JBake ;
deployare su un repository Git remoto via JGit;
integrabile in un workflow CI/CD;
testato secondo un approccio TDD.

Configuration déclarative

Ecco un esempio di configurazione YAML da modellare nel nostro DSL :

bake:
  srcPath: "./site/jbake"
  destDirPath: "bake"
pushPage:
  from: "bake"
  to: "cvs"
  repo:
    name: "trainings"
    repository: "https://github.com/pages-content/trainings.git"
    credentials:
      username: "USERNAME"
      password: "SECRET_TOKEN"
  branch: "main"
  message: "cheroliv.com"

Questa configurazione è rappresentata da un’estensione Gradle dichiarabile in Kotlin DSL.

Architettura del plugin

Definizione dell’estensione DSL

open class WorkspaceEngineExtension {
    var outputDir: String = "build/site"
    var template: String = "freemarker"
    var repoUrl: String = ""
    var branch: String = "main"
    var message: String = "Generated by engine"
}

Definizione del compito personalizzato

abstract class GenerateSiteTask : DefaultTask() {
    lateinit var gitAdapter: GitAdapter

    @get:Input abstract val repoUrl: Property<String>
    @get:InputDirectory abstract val outputDir: DirectoryProperty
    @get:Input abstract val branch: Property<String>
    @get:Input abstract val message: Property<String>

    @TaskAction
    fun run() {
        val repo = gitAdapter.cloneRepository(repoUrl.get(), outputDir.get().asFile)
        gitAdapter.commitAndPush(repo, branch.get(), message.get())
    }
}

Interfaccia GitAdapter

interface GitAdapter {
    fun cloneRepository(uri: String, directory: File): Repository
    fun commitAndPush(repo: Repository, branch: String, message: String)
}

Implementazione concreta con JGit

class JGitAdapter : GitAdapter {
    override fun cloneRepository(uri: String, directory: File): Repository {
        return Git.cloneRepository()
            .setURI(uri)
            .setDirectory(directory)
            .call()
            .repository
    }

    override fun commitAndPush(repo: Repository, branch: String, message: String) {
        Git(repo).use {
            it.add().addFilepattern(".").call()
            it.commit().setMessage(message).call()
            it.push().call()
        }
    }
}

Configurazione DSL Kotlin

workspaceEngine {
    outputDir = "build/out"
    template = "freemarker"
    repoUrl = "https://github.com/cheroliv/trainings.git"
    branch = "main"
    message = "deploy from plugin"
}

Test unitari con Mockito

Dipendenze

testImplementation("org.mockito:mockito-core:5.12.0")
testImplementation("org.mockito.kotlin:mockito-kotlin:5.2.1")
testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")

Test del comportamento Git

class GenerateSiteTaskMockitoTest {

    @TempDir
    lateinit var tempDir: File

    @Test
    fun `task should call clone and commitAndPush`() {
        val project = ProjectBuilder.builder().build()
        val task = project.tasks.create("generateSite", GenerateSiteTask::class.java)

        val mockGitAdapter = mock<GitAdapter>()
        val mockRepo = mock<Repository>()

        whenever(mockGitAdapter.cloneRepository(any(), any())).thenReturn(mockRepo)

        task.gitAdapter = mockGitAdapter
        task.repoUrl.set("https://github.com/cheroliv/test.git")
        task.outputDir.set(project.layout.projectDirectory.dir(tempDir.name))
        task.branch.set("main")
        task.message.set("test commit")

        task.run()

        verify(mockGitAdapter).cloneRepository(eq("https://github.com/cheroliv/test.git"), any())
        verify(mockGitAdapter).commitAndPush(eq(mockRepo), eq("main"), eq("test commit"))
    }
}

Conclusione

La separazione delle responsabilità via`GitAdapter`consente di applicare pienamente il TDD nello sviluppo di plugin Gradle :

le chiamate Git sono astratte e testabili ;
la configurazione DSL è pulita e chiara;
Il plugin rimane agnostico dell’implementazione reale.

Questo approccio garantisce una elevata testabilità ed estensibilità (verso GitHub API, GitLab, etc.).

Prossimi passi

Integrare la generazione JBake come un`BakeAdapter`
Aggiungere test di integrazione con`GradleRunner`
Supportare il caricamento automatico dei file`site.yml`via SnakeYAML