KT-64377 use Java Test Suites for Gradle integration tests (#3427)

Restructure Gradle Integration tests to use Java Test Suites

- create a test suite for each project under test (a separate test suite helps with Gradle caching, task avoidance, and parallelising)
- update GitHub Action steps to run specific test-suite tasks
- disable caching integration test tasks due to dependency on Maven Local publishing (this will be fixed in #3433)
- converting the CLI and Maven IT projects to use jvm-test-suites will be done in a later PR.

.github/workflows/preview-publish-ga.yml

@@ -25,7 +25,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/coroutines
       - name: Copy files to GitHub Actions Artifacts
@@ -52,7 +52,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:testExternalProjectKotlinxSerialization --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/serialization
       - name: Copy files to GitHub Actions Artifacts

.github/workflows/preview-publish-web-s3.yml

@@ -22,7 +22,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/coroutines
       - name: Configure AWS credentials for S3 access
@@ -36,7 +36,7 @@ jobs:
       - name: Print link
         run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/coroutines/${GITHUB_SHA::7}/index.html
 
-  kotilnx-serialization:
+  kotlinx-serialization:
     runs-on: ubuntu-latest
     if: github.repository == 'Kotlin/dokka'
     steps:
@@ -51,7 +51,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:testExternalProjectKotlinxSerialization --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/serialization
       - name: Configure AWS credentials for S3 access

.github/workflows/tests-thorough.yml

@@ -30,11 +30,11 @@ jobs:
         # Running tests with the Gradle daemon on windows agents leads to some very strange
         # JVM crashes for some reason. Most likely a problem of Gradle/GitHub/Windows server
         run: >
-          ./gradlew test --stacktrace --no-daemon --no-parallel 
+          ./gradlew test --stacktrace --no-daemon --no-parallel --continue 
           "-Dorg.gradle.jvmargs=-Xmx1g -XX:MaxMetaspaceSize=500m"
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ matrix.javaVersion }}"
       - name: Run tests under Ubuntu/Macos
         if: matrix.os != 'windows-latest'
         run: >
-          ./gradlew test --stacktrace 
+          ./gradlew test --stacktrace --continue
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ matrix.javaVersion }}"

build-logic/src/main/kotlin/dokkabuild.base.gradle.kts

@@ -1,7 +1,6 @@
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
-
 import dokkabuild.DokkaBuildProperties
 import org.gradle.language.base.plugins.LifecycleBasePlugin.VERIFICATION_GROUP
 

build-logic/src/main/kotlin/dokkabuild.setup-maven-cli.gradle.kts

@@ -84,7 +84,6 @@ val installMavenBinary by tasks.registering(Sync::class) {
     val archives = serviceOf<ArchiveOperations>()
     from(
         mavenBinary.flatMap { conf ->
-            @Suppress("UnstableApiUsage")
             val resolvedArtifacts = conf.incoming.artifacts.resolvedArtifacts
 
             resolvedArtifacts.map { artifacts ->

build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt

@@ -4,10 +4,12 @@
 
 package dokkabuild
 
+import org.gradle.api.file.ProjectLayout
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
 import org.gradle.jvm.toolchain.JavaLanguageVersion
 import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
+import java.io.File
 import javax.inject.Inject
 
 /**
@@ -20,8 +22,22 @@ import javax.inject.Inject
  */
 abstract class DokkaBuildProperties @Inject constructor(
     private val providers: ProviderFactory,
+    private val layout: ProjectLayout,
 ) {
 
+    private val buildingOnTeamCity: Provider<Boolean> =
+        providers.environmentVariable("TEAMCITY_VERSION").map(String::isNotBlank)
+
+    private val buildingOnGitHub: Provider<Boolean> =
+        providers.environmentVariable("GITHUB_ACTION").map(String::isNotBlank)
+
+    val isCI: Provider<Boolean> =
+        providers.environmentVariable("CI")
+            .map(String::isNotBlank)
+            .orElse(buildingOnTeamCity)
+            .orElse(buildingOnGitHub)
+            .orElse(false)
+
     /**
      * The main version of Java that should be used to build Dokka source code.
      *
@@ -62,6 +78,20 @@ abstract class DokkaBuildProperties @Inject constructor(
         dokkaProperty("integration_test.useK2", String::toBoolean)
             .orElse(false)
 
+    val androidSdkDir: Provider<File> =
+        providers
+            // first try finding a local.properties file in any parent directory
+            .provider {
+                generateSequence(layout.projectDirectory.asFile, File::getParentFile)
+                    .mapNotNull { dir -> dir.resolve("local.properties").takeIf(File::exists) }
+                    .flatMap { file -> file.readLines().filter { it.startsWith("sdk.dir=") } }
+                    .firstOrNull()
+                    ?.substringAfter("sdk.dir=")
+            }
+            // else try getting pre-installed SDK (e.g. via GitHub step setup-android)
+            .orElse(providers.environmentVariable("ANDROID_SDK_ROOT"))
+            .orElse(providers.environmentVariable("ANDROID_HOME"))
+            .map(::File)
 
     private fun <T : Any> dokkaProperty(name: String, convert: (String) -> T) =
         providers.gradleProperty("org.jetbrains.dokka.$name").map(convert)

build-logic/src/main/kotlin/dokkabuild/tasks/GitCheckoutTask.kt

@@ -67,7 +67,7 @@ abstract class GitCheckoutTask @Inject constructor(
             exclude(".git/")
         }
 
-        logger.lifecycle("initialized git repo $uri in ${destination.asFile.orNull}")
+        logger.lifecycle("initialized git repo ${uri.get()} in ${destination.asFile.get()}")
     }
 
     /**

dokka-integration-tests/gradle/README.md

@@ -14,7 +14,7 @@ Integration tests have fixed git revision number, with the diff patch applied fr
 
 In order to update:
 
-* Checkout the project with the requered revision
+* Checkout the project with the required revision
     - It's some state of the `master`
 * Manually write the diff (or apply the existing one and tweak) to have the project buildable against locally published Dokka of version `for-integration-tests-SNAPSHOT`
 * `git diff > $pathToProjectInDokka/project.diff`
@@ -26,4 +26,4 @@ In order to update:
 ### Run integration tests with K2 (symbols)
 
 To run integration tests with K2, the property `org.jetbrains.dokka.integration_test.useK2` should be set to `true`. 
-By default, the task `integrationTest` is run with K1 (descriptors).
+By default, the integration tests are run with K1 (descriptors).