IT Android with DGPv2

- implement new JUnit extension to help set up and re-run DGP integration tests with different versions

.gitattributes

@@ -42,6 +42,9 @@ docs-developer/**                                                   linguist-doc
 examples/**                                                         linguist-documentation
 dokka-integration-tests/gradle/projects/**                          linguist-documentation
 
+# exclude test data
+dokka-integration-tests/gradle/src/*/expectedData                   linguist-generated
+
 # Tell Git not to export certain files or directories when generating an archive.
 # Since an archive doesn't contain git data, also exclude git metadata files.
 .gitattributes export-ignore

dokka-integration-tests/gradle/build.gradle.kts

@@ -22,10 +22,13 @@ dependencies {
     api(libs.kotlin.test)
     api(libs.junit.jupiterApi)
     api(libs.junit.jupiterParams)
-
+    api(libs.kotest.assertionsCore)
     api(gradleTestKit())
 
     val dokkaVersion = project.version.toString()
+
+    api(testFixtures("org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion"))
+
     // We're using Gradle included-builds and dependency substitution, so we
     // need to use the Gradle project name, *not* the published Maven artifact-id
     devPublication("org.jetbrains.dokka:plugin-all-modules-page:$dokkaVersion")
@@ -80,6 +83,11 @@ registerTestProjectSuite(
             dokkaBuild.androidSdkDir.orNull?.let { androidSdkDir ->
                 environment("ANDROID_HOME", androidSdkDir)
             }
+
+            systemProperty.inputDirectory(
+                "baseExpectedDataDir",
+                layout.projectDirectory.dir("src/testTemplateProjectAndroid/expectedData"),
+            )
         }
     }
 }

dokka-integration-tests/gradle/projects/it-android-0-v2/build.gradle.kts

@@ -0,0 +1,17 @@
+plugins {
+    id("com.android.library") /* %{AGP_VERSION} */
+    id("org.jetbrains.dokka") /* %{DGP_VERSION} */
+    kotlin("android") /* %{KGP_VERSION} */
+}
+
+android {
+    namespace = "org.jetbrains.dokka.it.android"
+    defaultConfig {
+        minSdkVersion(21)
+        setCompileSdkVersion(29)
+    }
+}
+
+dependencies {
+    implementation("androidx.appcompat:appcompat:1.1.0")
+}

dokka-integration-tests/gradle/projects/it-android-0-v2/settings.gradle.kts

@@ -0,0 +1,64 @@
+rootProject.name = "it-android-0"
+
+pluginManagement {
+    repositories {
+        /* %{DOKKA_IT_MAVEN_REPO}% */
+        mavenCentral()
+        google()
+        gradlePluginPortal()
+    }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
+    repositories {
+        /* %{DOKKA_IT_MAVEN_REPO}% */
+
+        mavenCentral()
+        google()
+
+        //region Declare the Node.js & Yarn download repositories - workaround for https://youtrack.jetbrains.com/issue/KT-51379
+        ivy("https://nodejs.org/dist/") {
+            name = "Node Distributions at $url"
+            patternLayout { artifact("v[revision]/[artifact](-v[revision]-[classifier]).[ext]") }
+            metadataSources { artifact() }
+            content { includeModule("org.nodejs", "node") }
+        }
+        ivy("https://github.com/yarnpkg/yarn/releases/download") {
+            name = "Yarn Distributions at $url"
+            patternLayout { artifact("v[revision]/[artifact](-v[revision]).[ext]") }
+            metadataSources { artifact() }
+            content { includeModule("com.yarnpkg", "yarn") }
+        }
+        //endregion
+
+        //region Declare Kotlin/Native dependencies - workaround for https://youtrack.jetbrains.com/issue/KT-51379
+        // Remove this repo when the only supported KGP version is above 2.0.0
+        ivy("https://download.jetbrains.com/kotlin/native/builds") {
+            name = "Kotlin Native"
+            patternLayout {
+
+                // example download URLs:
+                // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/linux-x86_64/kotlin-native-prebuilt-linux-x86_64-1.7.20.tar.gz
+                // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/windows-x86_64/kotlin-native-prebuilt-windows-x86_64-1.7.20.zip
+                // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/macos-x86_64/kotlin-native-prebuilt-macos-x86_64-1.7.20.tar.gz
+                listOf(
+                    "macos-x86_64",
+                    "macos-aarch64",
+                    "osx-x86_64",
+                    "osx-aarch64",
+                    "linux-x86_64",
+                    "windows-x86_64"
+                ).forEach { os ->
+                    listOf("dev", "releases").forEach { stage ->
+                        artifact("$stage/[revision]/$os/[artifact]-[revision].[ext]")
+                    }
+                }
+            }
+            metadataSources { artifact() }
+            content { includeModuleByRegex(".*", ".*kotlin-native-prebuilt.*") }
+        }
+        //endregion
+    }
+}

dokka-integration-tests/gradle/projects/it-android-0-v2/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<!--
+  ~ Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+  -->
+
+<manifest package="org.jetbrains.dokka.it.android"/>

dokka-integration-tests/gradle/projects/it-android-0-v2/src/main/java/it/android/AndroidSpecificClass.kt

@@ -0,0 +1,16 @@
+@file:Suppress("unused")
+
+package it.android
+
+import android.content.Context
+import android.util.SparseIntArray
+import android.view.View
+
+/**
+ * This class is specific to android and uses android classes like:
+ * [Context], [SparseIntArray] or [View]
+ */
+class AndroidSpecificClass {
+    fun sparseIntArray() = SparseIntArray()
+    fun createView(context: Context): View = View(context)
+}

dokka-integration-tests/gradle/projects/it-android-0-v2/src/main/java/it/android/IntegrationTestActivity.kt

@@ -0,0 +1,22 @@
+package it.android
+
+import android.annotation.SuppressLint
+import android.os.Bundle
+import android.widget.TextView
+import androidx.appcompat.app.AppCompatActivity
+
+/**
+ * Some Activity implementing [AppCompatActivity] from android x
+ */
+class IntegrationTestActivity : AppCompatActivity() {
+    /**
+     * Will show a small happy text
+     */
+    @SuppressLint("SetTextI18n")
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val textView = TextView(this)
+        textView.text = "I am so happy :)"
+        setContentView(textView)
+    }
+}

dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt

@@ -17,10 +17,7 @@ import java.io.File
 import java.net.URI
 import java.nio.file.Path
 import java.nio.file.Paths
-import kotlin.io.path.copyTo
-import kotlin.io.path.copyToRecursively
-import kotlin.io.path.exists
-import kotlin.io.path.invariantSeparatorsPathString
+import kotlin.io.path.*
 import kotlin.test.BeforeTest
 import kotlin.time.Duration.Companion.seconds
 
@@ -37,7 +34,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
     ) {
         templateProjectDir.copyToRecursively(destination.toPath(), followLinks = false, overwrite = true)
         templateSettingsGradleKts.copyTo(destination.resolve("template.settings.gradle.kts").toPath(), overwrite = true)
-        destination.updateProjectLocalMavenDir()
+        destination.toPath().updateProjectLocalMavenDir()
     }
 
     fun createGradleRunner(
@@ -84,19 +81,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
             .withJetBrainsCachedGradleVersion(buildVersions.gradleVersion)
             .withTestKitDir(File("build", "gradle-test-kit").absoluteFile)
             .withDebug(TestEnvironment.isEnabledDebug)
-            .apply {
-                withEnvironment(
-                    buildMap {
-                        // `withEnvironment()` will wipe all existing environment variables,
-                        // which breaks things like ANDROID_HOME and PATH, so re-add them.
-                        putAll(System.getenv())
-
-                        if (hostGradleDependenciesCache.exists()) {
-                            put("GRADLE_RO_DEP_CACHE", hostGradleDependenciesCache.invariantSeparatorsPathString)
-                        }
-                    }
-                )
-            }
+            .withReadOnlyDependencyCache()
             .withArguments(
                 buildList {
 
@@ -190,7 +175,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
          * Note: Currently all Gradle versions store caches in `$GRADLE_USER_HOME/caches/`,
          * but this might change. Check the docs.
          */
-        private val hostGradleDependenciesCache: Path by lazy {
+        internal val hostGradleDependenciesCache: Path by lazy {
             hostGradleUserHome.resolve("caches")
         }
 
@@ -239,14 +224,14 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
             """.trimMargin()
         }
 
-        fun File.updateProjectLocalMavenDir() {
+        fun Path.updateProjectLocalMavenDir() {
 
             val dokkaMavenRepoMarker = "/* %{DOKKA_IT_MAVEN_REPO}% */"
 
             // Exclusive repository containing local Dokka artifacts.
             // Must be compatible with both Groovy and Kotlin DSL.
 
-            walk().filter { it.isFile }.forEach { file ->
+            walk().filter { it.isRegularFile() }.forEach { file ->
                 val fileText = file.readText()
 
                 if (dokkaMavenRepoMarker in fileText) {
@@ -260,10 +245,30 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
 }
 
 private fun GradleRunner.withJetBrainsCachedGradleVersion(version: GradleVersion): GradleRunner =
+    withJetBrainsCachedGradleVersion(version.version)
+
+internal fun GradleRunner.withJetBrainsCachedGradleVersion(version: String): GradleRunner =
     withGradleDistribution(
-        URI("https://cache-redirector.jetbrains.com/services.gradle.org/distributions/gradle-${version.version}-bin.zip")
+        URI("https://cache-redirector.jetbrains.com/services.gradle.org/distributions/gradle-${version}-bin.zip")
     )
 
+internal fun GradleRunner.withReadOnlyDependencyCache(
+    hostGradleDependenciesCache: Path = AbstractGradleIntegrationTest.hostGradleDependenciesCache,
+): GradleRunner =
+    apply {
+        withEnvironment(
+            buildMap {
+                // `withEnvironment()` will wipe all existing environment variables,
+                // which breaks things like ANDROID_HOME and PATH, so re-add them.
+                putAll(System.getenv())
+
+                if (hostGradleDependenciesCache.exists()) {
+                    put("GRADLE_RO_DEP_CACHE", hostGradleDependenciesCache.invariantSeparatorsPathString)
+                }
+            }
+        )
+    }
+
 private fun Throwable.withAllCauses(): Sequence<Throwable> {
     val root = this
     return sequence {