TDD настраиваемого плагина Gradle на Kotlin с JBake и JGit

Содержание

Цель
Декларативная конфигурация
Архитектура плагина
Определение расширения DSL
Определение пользовательской задачи
Интерфейс GitAdapter
Конкретная реализация с JGit
Конфигурация DSL Kotlin
Юнит-тесты с Mockito
- зависимости
- Тест поведения Git
Заключение
Следующие шаги

Этот пост представляет полный процесс проектирования и тестирования (TDD) плагина Gradle, написанного на Kotlin DSL. Этот плагин автоматизирует генерацию статических сайтов с JBake и развертывание Git через JGit, всё из одного YAML-файла конфигурации.

Цель

Создать плагин Gradle:

настраиваемый в Kotlin DSL ;
способен :
генерировать статический сайт из JBake ;
развернуть в удалённом репозитории Git через JGit ;
интегрируемый в workflow CI/CD;
протестирован в соответствии с подходом TDD.

Декларативная конфигурация

Вот пример конфигурации YAML, которую необходимо смоделировать в нашем 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"

Эта конфигурация представлена через расширение Gradle, объявленное в Kotlin DSL.

Архитектура плагина

@startuml
package "плагин движка" {
class WorkspaceEngineExtension
class GenerateSiteTask
interface GitAdapter
class JGitAdapter
WorkspaceEnginePlugin --> WorkspaceEngineExtension
WorkspaceEnginePlugin --> GenerateSiteTask
GenerateSiteTask --> GitAdapter
JGitAdapter ..|> GitAdapter
}
@enduml

Определение расширения 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"
}

Определение пользовательской задачи

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

Интерфейс GitAdapter

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

Конкретная реализация с 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()
        }
    }
}

Конфигурация DSL Kotlin

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

Юнит-тесты с Mockito

зависимости

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

Тест поведения 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"))
    }
}

@startuml
actor "Разработчик" as Dev
participant "Gradle ProjectBuilder" as Project
participant "СгенерироватьЗадачуСайта" as Task
participant "GitAdapter (Мок)" as Adapter
participant "JGitAdapter / Mockito" as Impl

Dev -> Project : construit projet Gradle
Dev -> Task : configure les propriétés
Task -> Adapter : cloneRepository()
Adapter -> Impl : simulé par Mockito
Task -> Adapter : commitAndPush()
@enduml

Заключение

Разделение обязанностей через`GitAdapter`позволяет полностью применять TDD при разработке плагина Gradle :

вызовы Git абстрагированы и тестируемы;
Конфигурация DSL чиста и ясна;
плагин остаётся независимым от фактической реализации.

Этот подход обеспечивает высокую тестируемость и расширяемость (к GitHub API, GitLab и т.д.).

Следующие шаги

Интегрировать генерацию JBake как`BakeAdapter`
Добавить интеграционные тесты с`GradleRunner`
Поддерживать автоматическую загрузку файлов`site.yml`через SnakeYAML