DGPv2 Android integration tests (#3904)

* DGPv2 Android integration tests

Create integration tests for using DGPv2 with Android projects.

Additionally, create a JUnit extension for helping set up and run the tests.

#### Overview

- DokkaGradlePluginTestExtension is a JUnit extension for automatically configuring and re-running tests.
  The behaviour can be configured by providing custom GradleTestProjectInitializer (for setting up the test projects),
  or custom GradlePropertiesProvider (for providing custom Gradle properties).

- The extension will re-run the tests multiple times with different versions.
  `TestedVersions.testedVersions()` provides all possible, valid combinations of versions used to run the tests.

- Add JUnit `@Tag` annotations, to help organise and categorise the tests.

- Add two new test projects in dokka-integration-tests/gradle/projects: it-android and it-android-compose.
  Each project has an `expectedData` directory containing the expected generated Dokka content.

- Split GradlePropertiesBuilder into separate class, so it can be re-used in the integration tests

* updated expected data

* IJ exclude dokka-integration-tests/.kotlin

* Add more kdoc

* update assertions, use `loadConfigurationCacheReportData` util to avoid detecting CC status via an absence of log output

* Skip testing AGP8 until KT-70855 is fixed

* improve loadConfigurationCacheReportData, tidy assertions

* rm commented out code

* fix `updateProjectLocalMavenDir()`

* Improve directory-contents assertion to provide much more detailed failure messages

* tidy `shouldBeDirectoryWithSameContentAs` assertion

* fix gradle task dependency

* Improve directory comparison assertion

Significantly improve comparison between directories.

Currently the failure messages are too obscure, and hard to diagnose.
Example: https://ge.jetbrains.com/s/vl2jgh3ivevyi/tests/task/:dokka-integration-tests:gradle:test/details/org.jetbrains.dokka.it.gradle.AndroidProjectIT/generate%20dokka%20HTML(DokkaGradleProjectRunner)%5B1%5D?top-execution=1

* comparing fix binary data

* replace non-printable characters with the codepoint

* tidy replaceNonPrintableWithCodepoint

* try re-building to prevent CC miss on TeamCity

```
configuration cache cannot be reused because the file system entry '../../../../../../../home/teamcity/android-sdk-linux/build-tools/34.0.0/aapt' has been created.
```

* clear CC reports

* clear CC reports

* formatting

* fix import

* order properties alphabetically

* Only update versions in specific files, to avoid reading and writing to lots of files

* add workaround for Gradle not logging aborted tests

gradle/gradle#5511

* - rename test tag annotations
- Make TestedVersions more strict, with specific subclasses for the Android and AndroidCompose tests.
- Split out TestedVersions generation into TestedVersionsSource.

* fix Gradle version

* Fix finding the annotations for the tested element by searching the parents.

* fix Gradle version

* Fix test assertion

* Improve `shouldHaveOutcome` assertion message

* Fix build cache tests

.gitattributes

@@ -42,6 +42,8 @@ docs-developer/**                                                   linguist-doc
 examples/**                                                         linguist-documentation
 dokka-integration-tests/gradle/projects/**                          linguist-documentation
 
+# exclude test data
+dokka-integration-tests/gradle/projects/**/expectedData/**                                linguist-generated
 dokka-integration-tests/gradle/src/testExampleProjects/expectedData/**                    linguist-generated
 dokka-runners/dokka-gradle-plugin/src/testFunctional/resources/KotlinDslAccessorsTest/**  linguist-generated
 

build.gradle.kts

@@ -115,12 +115,15 @@ idea {
                 ".idea",
                 ".husky",
                 ".kotlin",
+                "dokka-integration-tests/.kotlin",
                 "dokka-runners/dokka-gradle-plugin/.kotlin",
                 "dokka-runners/runner-cli/.kotlin",
                 "dokka-runners/runner-maven-plugin/.kotlin",
                 "dokka-runners/dokka-gradle-plugin/src/testFunctional/resources/KotlinDslAccessorsTest/",
 
                 "dokka-integration-tests/gradle/src/testExampleProjects/expectedData",
+                "dokka-integration-tests/gradle/projects/it-android/expectedData",
+                "dokka-integration-tests/gradle/projects/it-android-compose/expectedData",
             )
         )
     }

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

@@ -25,7 +25,7 @@ dependencies {
     api(libs.kotlin.test)
     api(libs.junit.jupiterApi)
     api(libs.junit.jupiterParams)
-
+    api(libs.kotest.assertionsCore)
     api(gradleTestKit())
 
     api(testFixtures("org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion"))
@@ -176,6 +176,32 @@ fun registerTestProjectSuite(
     }
 }
 
+testing.suites.named<JvmTestSuite>("test") {
+    targets.configureEach {
+        testTask {
+            systemProperty
+                .inputDirectory("templateProjectsDir", templateProjectsDir)
+                .withPathSensitivity(RELATIVE)
+
+            // Don't register ANDROID_HOME as a Task input, because the path is different on everyone's machine,
+            // which means Gradle will never be able to cache the task.
+            dokkaBuild.androidSdkDir.orNull?.let { androidSdkDir ->
+                environment("ANDROID_HOME", androidSdkDir)
+            }
+
+            // Use a stable Java version for running Gradle in integration tests.
+            // There's no need to parameterise the version, to re-run the tests with different JDKs.
+            // There are a few reasons for this:
+            // - Some tests use AGP 8, which requires Gradle 17+.
+            // - DGP functional tests are already run with Java 8, so we don't need to re-test Java 8 compatibility here.
+            // - The JDK used to run Gradle doesn't affect the Dokka output. The Java Toolchain used to compile
+            //   the code in test projects does affect the output... but that can be parameterised in the
+            //   individual tests if necessary.
+            javaLauncher = javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(17) }
+        }
+    }
+}
+
 val checkoutKotlinxCoroutines by tasks.registering(GitCheckoutTask::class) {
     uri = "https://github.com/Kotlin/kotlinx.coroutines.git"
     commitId = "b78bbf518bd8e90e9ed2133ebdacc36441210cd6"
@@ -193,6 +219,9 @@ testing {
         targets.configureEach {
             testTask.configure {
                 devMavenPublish.configureTask(this)
+
+                // temp workaround, remove when all `testTemplateProject*` source sets are removed
+                mustRunAfter(tasks.withType<GitCheckoutTask>())
             }
         }
     }

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

@@ -0,0 +1,16 @@
+plugins {
+    alias(libs.plugins.android.library) apply false
+    alias(libs.plugins.kotlin.multiplatform) apply false
+
+    if ("/* %{KGP_VERSION} */".startsWith("2.")) {
+        id("org.jetbrains.kotlin.plugin.compose") version "/* %{KGP_VERSION} */" apply false
+    }
+    alias(libs.plugins.compose.multiplatform) apply false
+
+    id("org.jetbrains.dokka") version "/* %{DGP_VERSION} */"
+}
+
+dependencies {
+    dokka(project(":core"))
+    dokka(project(":material3"))
+}

dokka-integration-tests/gradle/projects/it-android-compose/core/build.gradle.kts

@@ -0,0 +1,45 @@
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.multiplatform)
+    id("org.jetbrains.dokka")
+
+    if ("/* %{KGP_VERSION} */".startsWith("2.")) {
+        id("org.jetbrains.kotlin.plugin.compose")
+    }
+    alias(libs.plugins.compose.multiplatform)
+}
+
+group = "org.dokka.it.android.kmp"
+version = "1.0"
+
+android {
+    namespace = "org.dokka.it.android.kmp"
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+}
+
+kotlin {
+    jvmToolchain(17)
+
+    androidTarget {
+        publishLibraryVariants("release")
+    }
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation(compose.runtime)
+                implementation(compose.foundation)
+                implementation(compose.animation)
+            }
+        }
+    }
+}

dokka-integration-tests/gradle/projects/it-android-compose/core/src/androidMain/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest />

dokka-integration-tests/gradle/projects/it-android-compose/core/src/commonMain/kotlin/MenuItem.kt

@@ -0,0 +1,12 @@
+package org.dokka.it.android.kmp.core
+
+import androidx.compose.runtime.Stable
+import androidx.compose.ui.graphics.vector.ImageVector
+
+@Stable
+public data class MenuItem(
+    val label: String,
+    val imageVector: ImageVector,
+    val onClick: () -> Unit,
+    val isImportant: Boolean,
+)