TDD eines konfigurierbaren Gradle-Kotlin-Plugins mit JBake und JGit

Sommaire

Ziel
deklarative Konfiguration
Architektur des Plugins
Definition der DSL-Erweiterung
Definition der personalisierten Aufgabe
Schnittstelle GitAdapter
Konkrete Implementierung mit JGit
Konfiguration DSL Kotlin
Einheitstests mit Mockito
- Abhängigkeiten
- Test des Verhaltens von Git
Fazit
Nächste Schritte

Dieser Beitrag stellt den vollständigen Prozess der Konzeption und Tests (TDD) eines in Kotlin DSL geschriebenen Gradle-Plugins vor. Dieses Plugin automatisiert die Erstellung statischer Sites mit JBake sowie die Git-Bereitstellung über JGit – alles basierend auf einer YAML-Konfigurationsdatei.

Ziel

Ein Gradle-Plugin erstellen :

konfigurierbar in Kotlin DSL ;
fähig zu:
eine statische Site mit JBake generieren ;
auf einem entfernten Git-Repository via JGit bereitstellen;
in einem CI/CD-Workflow integrierbar ;
getestet gemäß einer TDD-Vorgehensweise.

deklarative Konfiguration

Hier ist ein Beispiel für eine YAML‑Konfiguration, die in unserer DSL modelliert werden soll :

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"

Diese Konfiguration wird über eine deklarierbare Gradle-Erweiterung im Kotlin‑DSL repräsentiert.

Architektur des Plugins

Definition der DSL-Erweiterung

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"
}

Definition der personalisierten Aufgabe

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())
    }
}

Schnittstelle GitAdapter

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

Konkrete Implementierung mit 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()
        }
    }
}

Konfiguration DSL Kotlin

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

Einheitstests mit Mockito

Abhängigkeiten

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 des Verhaltens von 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"))
    }
}

Fazit

Die Trennung der Verantwortlichkeiten via`GitAdapter`ermöglicht das vollständige Anwenden von TDD bei der Entwicklung von Gradle-Plugins:

Die Git-Aufrufe sind abstrahiert und testbar;
Die DSL-Konfiguration ist sauber und klar ;
Das Plugin bleibt agnostisch gegenüber der eigentlichen Implementierung.

Dieser Ansatz gewährleistet eine hohe Testbarkeit und Erweiterbarkeit (zu GitHub-API, GitLab usw.).

Nächste Schritte

Integrieren Sie die JBake-Generierung als ein`BakeAdapter`
Integrations-Tests hinzufügen mit`GradleRunner`
Das automatische Laden von Dateien unterstützen`site.yml`via SnakeYAML