Gradleプラグインの機能テストにおける効果的なログ

はじめに

Gradleプラグインの開発中、機能テストはGradleの実際の環境でのプラグインの動作を検証するために不可欠です。しかし、重要な質問がすぐに浮上します：どのようにすれば GradleRunner と問題のある依存関係を作らずに効果的なロギングシステムを構築できますか？

この記事では、次のことを探求します：

Gradleの機能テストにおけるロギングの問題
SLF4J と Logback を使用した堅牢なソリューションのアーキテクチャ
具体的な例を含む完全な実装
良いプラクティスと避けるべき罠

問題: GradleRunnerへの依存

プラグイン開発のコンテキスト

Gradleプラグインを開発する際には、通常、`GradleRunner`Gradle TestKit を使用してテストビルドを実行する :

@Test
fun `test my plugin`() {
    val result = GradleRunner.create()
        .withProjectDir(projectDir)
        .withArguments("myTask")
        .build()

    // Comment logger efficacement ici ?
}

ロギングのジレンマ

主な問題は次のとおりです：ロギングは、初期化が確実でないオブジェクトに依存してはならない。。

@startuml
!define RECTANGLE class

skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "問題的アーキテクチャ" {
    RECTANGLE Test {
        + runTest()
    }

    RECTANGLE GradleRunner {
        + build()
        + getLogger() ❌
    }

    RECTANGLE Logger {
        + info()
        + debug()
    }

    Test --> GradleRunner : dépend de
    Logger ..> GradleRunner : dépend de ❌
}

note right of Logger
  Problème: Le logger dépend
  du GradleRunner qui peut
  ne pas être initialisé
end note

@enduml

�誤った良いアイデア

これをしないでください :

// ❌ MAUVAIS: Tentative d'obtenir un logger du runner
val runner = GradleRunner.create()
val logger = runner.logger // N'existe pas !
// ❌ MAUVAIS: Logger partagé initialisé tardivement
lateinit var logger: Logger
@BeforeEach
fun setup() {
    logger = LoggerFactory.getLogger(...)
}

ソリューション: 独立ロガー

推奨アーキテクチャ

解決策はロガーを使用することである完全に独立 du GradleRunner, テストクラスレベルで初期化された

@startuml
!define RECTANGLE class

skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

package "正しいアーキテクチャ" {
    RECTANGLE TestClass {
        + {static} logger: Logger ✓
        + runTest()
    }

    RECTANGLE SLF4J {
        + LoggerFactory
    }

    RECTANGLE GradleRunner {
        + build()
        + forwardOutput()
    }

    RECTANGLE "コンソール出力" as Output {
        + captured text
    }

    TestClass --> SLF4J : utilise ✓
    TestClass --> GradleRunner : utilise
    GradleRunner --> Output : génère
    TestClass --> Output : analyse
}

note top of TestClass
  Le logger est initialisé
  indépendamment du GradleRunner
end note

note bottom of GradleRunner
  .forwardOutput() permet
  de capturer la sortie
  pour analyse
end note

@enduml

実行フロー

@startuml
!theme plain
skinparam backgroundColor #FEFEFE

participant "JUnit" as junit
participant "テストクラス" as test
participant "ロガー (SLF4J)" as logger
participant "GradleRunner" as runner
participant "Gradle ビルド" as gradle

activate junit
junit -> test : load class
activate test

test -> logger : initialize (companion)
activate logger
logger --> test : logger ready ✓
deactivate logger

junit -> test : @BeforeAll
test -> logger : info("Initialisation...")

junit -> test : @BeforeEach
test -> logger : debug("セットアップテスト...")

junit -> test : @Test
test -> logger : info("開始...")

test -> runner : create()
activate runner
test -> runner : .forwardOutput()
test -> runner : .withArguments(...)
test -> runner : .build()

runner -> gradle : execute build
activate gradle
gradle --> runner : output text
deactivate gradle

runner --> test : BuildResult + output
deactivate runner

test -> logger : debug("出力を分析中...")
test -> test : analyze output
test -> logger : info("�✓ テストに合格しました")

test --> junit : success
deactivate test
deactivate junit

@enduml

完全実装

Gradleの依存関係

必要な依存関係をあなたのに追加してください`build.gradle.kts`:

dependencies {
    // Pour les tests fonctionnels
    testImplementation(gradleTestKit())
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")

    // Pour le logging
    testImplementation("org.slf4j:slf4j-api:2.0.17")
    testRuntimeOnly("ch.qos.logback:logback-classic:1.4.14")

    // Pour les assertions
    testImplementation("org.assertj:assertj-core:3.27.6")
}

tasks.test {
    useJUnitPlatform()
}

設定 Logback

ファイルを作成してください`src/test/resources/logback-test.xml`:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Appender console avec format lisible -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Appender fichier pour conservation -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>build/test-results/functional-tests.log</file>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Logger pour vos tests -->
    <logger name="com.cheroliv.bakery" level="DEBUG"/>

    <!-- Réduire le bruit de Gradle -->
    <logger name="org.gradle" level="WARN"/>

    <!-- Configuration racine -->
    <root level="INFO">
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="FILE"/>
    </root>
</configuration>

完全なテストクラス

package com.cheroliv.bakery

import org.gradle.testkit.runner.GradleRunner
import org.gradle.testkit.runner.TaskOutcome
import org.junit.jupiter.api.*
import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS
import org.junit.jupiter.api.io.TempDir
import org.slf4j.Logger
import org.slf4j.LoggerFactory
import java.io.File
import kotlin.test.assertEquals
import kotlin.test.assertTrue

@TestInstance(PER_CLASS)
class BakeryPluginFunctionalTest {

    @field:TempDir
    lateinit var projectDir: File

    private val buildFile by lazy { projectDir.resolve("build.gradle.kts") }
    private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") }

    companion object {
        // ✓ Logger indépendant, initialisé au chargement de la classe
        private val logger: Logger = LoggerFactory.getLogger(
            BakeryPluginFunctionalTest::class.java
        )

        @JvmStatic
        @BeforeAll
        fun globalSetup() {
            logger.info("═".repeat(60))
            logger.info("DÉMARRAGE DE LA SUITE DE TESTS FONCTIONNELS")
            logger.info("═".repeat(60))
        }

        @JvmStatic
        @AfterAll
        fun globalTeardown() {
            logger.info("═".repeat(60))
            logger.info("FIN DE LA SUITE DE TESTS")
            logger.info("═".repeat(60))
        }
    }

    @BeforeEach
    fun setup() {
        logger.info("─".repeat(60))
        logger.info("Préparation de l'environnement de test")
        logger.debug("Répertoire de test: ${projectDir.absolutePath}")

        settingsFile.writeText("""
            rootProject.name = "test-bakery-project"
        """.trimIndent())

        logger.debug("✓ settings.gradle.kts créé")
    }

    @AfterEach
    fun teardown(testInfo: TestInfo) {
        logger.info("✓ Test terminé: ${testInfo.displayName}")
        logger.info("─".repeat(60))
    }

    @Test
    fun `plugin can be applied successfully`() {
        logger.info("TEST: Application du plugin Bakery")

        buildFile.writeText("""
            plugins {
                id("com.cheroliv.bakery")
            }
        """.trimIndent())

        logger.debug("Fichier build.gradle.kts créé")
        logger.debug("Lancement du build Gradle...")

        val startTime = System.currentTimeMillis()

        val result = GradleRunner.create()
            .forwardOutput() // ← Important : capture la sortie
            .withPluginClasspath()
            .withArguments("tasks", "--group=bakery", "--stacktrace")
            .withProjectDir(projectDir)
            .build()

        val duration = System.currentTimeMillis() - startTime
        logger.info("Build terminé en ${duration}ms")

        // Analyse de la sortie
        logger.debug("Analyse de la sortie Gradle...")
        val outputLines = result.output.lines()
        logger.debug("Nombre de lignes capturées: ${outputLines.size}")

        // Validation
        val expectedTasks = listOf("bake", "printConfigPath", "printJBakeClasspath")
        logger.info("Vérification des tâches attendues:")

        expectedTasks.forEach { task ->
            val found = result.output.contains(task)
            logger.debug("  ${if (found) "✓" else "✗"} $task")
            assertTrue(found, "Task '$task' should be available")
        }

        logger.info("✓ Plugin appliqué avec succès - ${expectedTasks.size} tâches trouvées")
    }

    @Test
    fun `bake task executes and prints version`() {
        logger.info("TEST: Exécution de la tâche 'bake'")

        buildFile.writeText("""
            plugins {
                id("com.cheroliv.bakery")
            }
        """.trimIndent())

        logger.debug("Exécution de 'gradle bake'...")

        val result = GradleRunner.create()
            .forwardOutput()
            .withPluginClasspath()
            .withArguments("bake", "--info") // --info pour plus de détails
            .withProjectDir(projectDir)
            .build()

        // Extraction d'informations depuis la sortie
        logger.debug("Recherche du message 'Baking site'...")
        val hasBakingMessage = result.output.contains("Baking site with Bakery Plugin!")

        logger.debug("Recherche de la version JBake...")
        val hasVersionMessage = result.output.contains("Using JBake version:")

        // Extraction de la version (si présente)
        val versionRegex = Regex("Using JBake version: (.+)")
        val versionMatch = versionRegex.find(result.output)
        if (versionMatch != null) {
            val version = versionMatch.groupValues[1]
            logger.info("Version JBake détectée: $version")
        }

        // Validation
        assertTrue(hasBakingMessage, "Message 'Baking site' attendu")
        assertTrue(hasVersionMessage, "Message de version attendu")
        assertEquals(TaskOutcome.SUCCESS, result.task(":bake")?.outcome)

        logger.info("✓ Tâche 'bake' exécutée avec succès")
    }

    @Test
    fun `analyze output with structured logging`() {
        logger.info("TEST: Analyse structurée de la sortie")

        buildFile.writeText("""
            plugins {
                id("com.cheroliv.bakery")
            }

            task("diagnostics") {
                doLast {
                    println("[DIAG] Project: ${'$'}{project.name}")
                    println("[DIAG] Build dir: ${'$'}{project.buildDir}")
                    println("[DIAG] Plugin applied: true")

                    val config = configurations.findByName("jbakeRuntime")
                    println("[DIAG] JBake config exists: ${'$'}{config != null}")

                    if (config != null) {
                        println("[DIAG] Dependencies count: ${'$'}{config.dependencies.size}")
                    }
                }
            }
        """.trimIndent())

        logger.debug("Exécution de la tâche diagnostics...")

        val result = GradleRunner.create()
            .forwardOutput()
            .withPluginClasspath()
            .withArguments("diagnostics", "--quiet")
            .withProjectDir(projectDir)
            .build()

        // Analyse structurée
        logger.info("Extraction des informations de diagnostic:")

        val diagLines = result.output.lines()
            .filter { it.startsWith("[DIAG]") }

        logger.debug("Nombre de lignes de diagnostic: ${diagLines.size}")

        diagLines.forEach { line ->
            logger.info("  $line")

            // Analyse spécifique par type de ligne
            when {
                line.contains("Project:") -> {
                    val projectName = line.substringAfter("Project:").trim()
                    logger.debug("    → Nom du projet extrait: '$projectName'")
                }
                line.contains("Dependencies count:") -> {
                    val count = line.substringAfter("count:").trim()
                    logger.debug("    → Nombre de dépendances: $count")
                }
            }
        }

        assertTrue(diagLines.isNotEmpty(), "Des lignes de diagnostic devraient être présentes")
        logger.info("✓ Analyse structurée terminée - ${diagLines.size} lignes analysées")
    }

    @Test
    fun `test with error handling`() {
        logger.info("TEST: Gestion d'erreurs avec logging")

        buildFile.writeText("""
            plugins {
                id("com.cheroliv.bakery")
            }
        """.trimIndent())

        try {
            logger.debug("Tentative d'exécution...")

            val result = GradleRunner.create()
                .forwardOutput()
                .withPluginClasspath()
                .withArguments("printJBakeClasspath")
                .withProjectDir(projectDir)
                .build()

            val outcome = result.task(":printJBakeClasspath")?.outcome
            logger.info("Outcome: $outcome")

            if (outcome == TaskOutcome.SUCCESS) {
                logger.info("✓ Exécution réussie")
            } else {
                logger.warn("⚠ Outcome inattendu: $outcome")
            }

            assertEquals(TaskOutcome.SUCCESS, outcome)

        } catch (e: Exception) {
            logger.error("✗ Échec du test", e)
            logger.error("Type d'exception: ${e.javaClass.simpleName}")
            logger.error("Message: ${e.message}")

            // Log de la stack trace si nécessaire
            if (logger.isDebugEnabled) {
                logger.debug("Stack trace complète:", e)
            }

            throw e
        }
    }
}

マルチレベルログスキーム

@startuml
!theme plain
skinparam backgroundColor #FEFEFE

package "ロギングレベル" {

    rectangle "痕跡" #E8E8E8 {
        note
            Détails d'exécution très fins
            • Valeurs de variables
            • Appels de méthodes internes
        end note
    }

    rectangle "DEBUG" #D0E8FF {
        note
            Informations de débogage
            • Étapes intermédiaires
            • Contenu des fichiers créés
            • Analyse de la sortie Gradle
        end note
    }

    rectangle "情報" #C8FFC8 {
        note
            Informations principales
            • Début/fin de test
            • Résultats de validation
            • Durée d'exécution
        end note
    }

    rectangle "警告" #FFFFC8 {
        note
            Avertissements
            • Comportements inattendus
            • Outcomes inhabituels
        end note
    }

    rectangle "エラー" #FFC8C8 {
        note
            Erreurs
            • Échecs de test
            • Exceptions
            • Stack traces
        end note
    }
}

@enduml

ベストプラクティス

推奨されるロギング構造

@Test
fun `mon test`() {
    // 1. LOG: Début du test
    logger.info("TEST: Description du test")

    // 2. LOG: Préparation
    logger.debug("Préparation des fichiers...")
    buildFile.writeText("...")
    logger.debug("✓ Fichiers préparés")

    // 3. LOG: Exécution
    logger.debug("Lancement du build...")
    val startTime = System.currentTimeMillis()

    val result = GradleRunner.create()
        .forwardOutput()
        .withArguments("task")
        .build()

    val duration = System.currentTimeMillis() - startTime
    logger.info("Build terminé en ${duration}ms")

    // 4. LOG: Analyse
    logger.debug("Analyse des résultats...")
    // ... validations ...

    // 5. LOG: Conclusion
    logger.info("✓ Test réussi")
}

可読性のための視覚的なシンボル

Unicode記号を使用してログの可読性を向上させなさい：

logger.info("✓ Succès")
logger.info("✗ Échec")
logger.info("⚠ Attention")
logger.info("→ Étape suivante")
logger.info("═".repeat(60)) // Séparateur principal
logger.info("─".repeat(60)) // Séparateur secondaire

出力からの情報抽出

// Recherche simple
val hasMessage = result.output.contains("Expected message")

// Extraction avec regex
val versionRegex = Regex("Version: (.+)")
val version = versionRegex.find(result.output)?.groupValues?.get(1)

// Filtrage de lignes
val errorLines = result.output.lines()
    .filter { it.contains("ERROR") }

errorLines.forEach { logger.error("Gradle error: $it") }

比較前後

前：問題のあるアプローチ

class MyTest {
    lateinit var logger: Logger // ❌ Initialisé tardivement

    @BeforeEach
    fun setup() {
        logger = LoggerFactory.getLogger(...) // ❌ Dépendance
    }

    @Test
    fun test() {
        val runner = GradleRunner.create()
        logger.info("Testing...") // ⚠ Peut échouer
    }
}

後 : 頑健なアプローチ

class MyTest {
    companion object {
        private val logger = LoggerFactory.getLogger(...) // ✓ Indépendant
    }

    @Test
    fun test() {
        logger.info("TEST: Starting...") // ✓ Toujours disponible

        val result = GradleRunner.create()
            .forwardOutput() // ✓ Capture la sortie
            .build()

        logger.debug("Output: ${result.output}") // ✓ Analyse
    }
}

サマリーダイアグラム

@startuml
!theme plain
skinparam backgroundColor #FEFEFE

title 機能テストにおける完全なロギングフロー
actor "開発者" as dev
participant "JUnit" as junit
participant "テストクラス" as test
participant "Logger
(SLF4J)" as logger
participant "Logback" as logback
participant "グラドルランナー" as runner
participant "コンソール/ファイル" as output

dev -> junit : lance les tests

activate junit
junit -> test : charge la classe
activate test

test -> logger : initialize (companion)
activate logger
logger -> logback : configure
activate logback
logback --> logger : ready
deactivate logback
logger --> test : ✓
deactivate logger

== Phase de Setup ==

junit -> test : @BeforeAll
test -> logger : info("初期化")
logger -> output : [INFO] Initialisation

junit -> test : @BeforeEach
test -> logger : debug("セットアップ テスト")
logger -> output : [DEBUG] Setup test

== Phase de Test ==

junit -> test : @Test
test -> logger : info("始める")
logger -> output : [INFO] TEST: Starting

test -> runner : create()
activate runner

test -> runner : .forwardOutput()
test -> runner : .build()

runner -> runner : execute Gradle
runner --> test : BuildResult + output text
deactivate runner

test -> logger : debug("出力を分析中")
logger -> output : [DEBUG] Analyzing output

test -> test : assertions
test -> logger : info("�✓ テストに合格しました")
logger -> output : [INFO] ✓ Test passed

== Phase de Cleanup ==

junit -> test : @AfterEach
test -> logger : debug("クリーンアップ")
logger -> output : [DEBUG] Cleanup

junit -> test : @AfterAll
test -> logger : info("テストの終了")
logger -> output : [INFO] Fin des tests

test --> junit : ✓ all tests passed
deactivate test
deactivate junit

dev <-- junit : rapport de tests

@enduml

�避けるべき罠

�❌ 罠1：忘れる `.forwardOutput()

// MAUVAIS: La sortie Gradle n'est pas capturée
val result = GradleRunner.create()
    .withArguments("task")
    .build()

// result.output sera vide !

// BON: La sortie est capturée
val result = GradleRunner.create()
    .forwardOutput() // ✓
    .withArguments("task")
    .build()

�❌ 罠 2番 : ロガー未初期化

// MAUVAIS
class Test {
    lateinit var logger: Logger // Peut ne pas être initialisé
}

// BON
class Test {
    companion object {
        private val logger = LoggerFactory.getLogger(...) // Toujours initialisé
    }
}

�❌ 罠 3 : 過剰なログ

// MAUVAIS: Trop de logs DEBUG en production
logger.debug("Variable a = $a")
logger.debug("Variable b = $b")
logger.debug("Variable c = $c")
// ... 100 lignes de logs

// BON: Logging ciblé
logger.info("Traitement de ${items.size} éléments")
logger.debug("Détails: ${items.take(5)}...") // Échantillon seulement

結果とメトリクス

このアプローチでは、次のように得られます：

メトリック	前に	後
コードの行	~50 lignes	約80行（＋60％）
デバッグ時間	~30分	~5分 (-83%)
�検出されたエラー	基本的	詳細
メンテナンス	難しい	シンプル
独立	❌ 結合された	独立した

メトリック

前に

後

コードの行

~50 lignes

約80行（＋60％）

デバッグ時間

~30分

~5分 (-83%)

�検出されたエラー

基本的

詳細

メンテナンス

難しい

シンプル

独立

❌ 結合された

独立した

結論

Gradle プラグインの機能テストにおける堅牢なログシステムの導入は、シンプルな原則に基づいています :独立。

重要なポイント：

独立ロガーで初期化された`companion object`
SLF4JとLogback: テスト済みで設定可能なスタック
.forwardOutput(): Gradle出力のキャプチャ
構造化ログ: INFO ステップのために, DEBUG 詳細のために
出力の分析情報の抽出から`result.output`

このアプローチはテストを保証するメンテナンス可能, デバッグ可能なもの et 頑丈, しっかりとした設計の原則を尊重しながら。

資源

もっと先へ

次回の記事では、探求します:

構造化ロギング付きの継続的インテグレーション
ログが組み込まれたHTMLテストレポート
JVMアタッチを使用した高度なデバッグ
パフォーマンスとロギングの最適化

この記事は、私の技術ブログにおける「Gradleプラグイン開発」シリーズの一部です。

HyperFrames-Gradle : AsciiDocをMP4動画に変換
31 May 2026

私のLLM消費の監査：SQLite、OpenCode、Ollama Cloud、そしてなぜ私のプロサブスクリプションが世界市場を破壊するのか
18 May 2026

プラグイン独立＋コンシューマールートアーキテクチャ：なぜ私のGradleビルドが重複するのか
14 May 2026

レコメンデーションエンジンとしての Knowledge Graph：私が時系列の「関連記事」をどう廃止したか
12 May 2026

JavaScriptを有効にして、表示してください Disqusによって提供されるコメント.