Part of KT-64200

- Migrate the CLI integration tests away from the custom integration test convention (which are not build-cache compatible) to use JVM Test Suites.
- Remove shadowing, replace with passing in the JARs via system properties. (a custom CommandLineArgumentProvider is confusing and overly complicated, but it's required to satisfy Gradle input normalization, so that the build-cache can be re-used.)
- Simplify `processUtils.kt` - the coroutines logic isn't necessary since the entrypoint just used `runBlocking {}`.
- move `jsonBuilder.kt` test-util into `src/main`, since it's not a test
- Rename `CliIntegrationTest` to `CliTest` (it wasn't an integration test, and the name was confusing compared to the actual `CliIntegrationTest`)

build-logic/src/main/kotlin/dokkabuild.test-cli-dependencies.gradle.kts

@@ -0,0 +1,42 @@
+ /*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+import dokkabuild.utils.declarable
+import dokkabuild.utils.resolvable
+import org.gradle.api.attributes.Bundling.BUNDLING_ATTRIBUTE
+import org.gradle.api.attributes.Bundling.SHADOWED
+import org.gradle.api.attributes.Usage.JAVA_RUNTIME
+import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE
+
+
+val dokkaCli: Configuration by configurations.creating {
+    description = "Dependency on Dokka CLI JAR. Must only contain a single dependency."
+    declarable()
+}
+
+val dokkaCliResolver: Configuration by configurations.creating {
+    description = "Resolve the Dokka CLI JAR. Intransitive - must only contain a single JAR."
+    resolvable()
+    extendsFrom(dokkaCli)
+    attributes {
+        attribute(USAGE_ATTRIBUTE, objects.named(JAVA_RUNTIME))
+        attribute(BUNDLING_ATTRIBUTE, objects.named(SHADOWED))
+    }
+    // we should have single artifact here
+    isTransitive = false
+}
+
+
+val dokkaPluginsClasspath: Configuration by configurations.creating {
+    description = "Dokka CLI runtime dependencies required to run Dokka CLI, and its plugins."
+    declarable()
+}
+
+val dokkaPluginsClasspathResolver: Configuration by configurations.creating {
+    description = "Resolve Dokka CLI runtime dependencies required to run Dokka CLI, and its plugins."
+    resolvable()
+    extendsFrom(dokkaPluginsClasspath)
+    attributes {
+        attribute(USAGE_ATTRIBUTE, objects.named(JAVA_RUNTIME))
+    }
+}

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

@@ -1,79 +1,84 @@
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
+@file:Suppress("UnstableApiUsage")
 
-import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
+import org.gradle.api.attributes.Bundling.BUNDLING_ATTRIBUTE
+import org.gradle.api.attributes.Bundling.SHADOWED
 
 plugins {
-    id("dokkabuild.test-integration")
-    id("com.github.johnrengelman.shadow")
+    id("dokkabuild.kotlin-jvm")
+    id("dokkabuild.test-cli-dependencies")
+    `jvm-test-suite`
 }
 
 dependencies {
-    implementation(kotlin("test-junit5"))
-    implementation(libs.junit.jupiterApi)
-    implementation(projects.utilities)
-}
+    api(kotlin("test-junit5"))
+    api(libs.junit.jupiterApi)
+    api(projects.utilities)
 
-val cliPluginsClasspath: Configuration by configurations.creating {
-    description = "plugins/dependencies required to run CLI with base plugin"
-    attributes {
-        attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME))
-    }
+    dokkaCli("org.jetbrains.dokka:runner-cli")
 
-    // we don't fetch transitive dependencies here to be able to control external dependencies explicitly
-    isTransitive = false
-}
+    dokkaPluginsClasspath("org.jetbrains.dokka:plugin-base")
+    dokkaPluginsClasspath(libs.kotlinx.html)
+    dokkaPluginsClasspath(libs.freemarker)
 
-val cliClasspath: Configuration by configurations.creating {
-    description = "dependency on CLI JAR"
-    attributes {
-        attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME))
-        attribute(Bundling.BUNDLING_ATTRIBUTE, project.objects.named(Bundling.SHADOWED))
+    val analysisDependency = dokkaBuild.integrationTestUseK2.map { useK2 ->
+        if (useK2) {
+            "org.jetbrains.dokka:analysis-kotlin-symbols"
+        } else {
+            "org.jetbrains.dokka:analysis-kotlin-descriptors"
+        }
+    }
+    dokkaPluginsClasspath(analysisDependency) {
+        attributes {
+            attribute(BUNDLING_ATTRIBUTE, project.objects.named(SHADOWED))
+        }
     }
-    // we should have single artifact here
-    isTransitive = false
 }
 
-dependencies {
-    cliClasspath("org.jetbrains.dokka:runner-cli")
-
-    cliPluginsClasspath("org.jetbrains.dokka:plugin-base")
-    // required dependencies of `plugin-base`
-    cliPluginsClasspath(libs.freemarker)
-    cliPluginsClasspath(libs.kotlinx.html)
+/**
+ * Provide files required for running Dokka CLI in a build cache friendly way.
+ */
+abstract class DokkaCliClasspathProvider : CommandLineArgumentProvider {
+    @get:Classpath
+    abstract val dokkaCli: RegularFileProperty
 
-    val tryK2 = project.providers
-        .gradleProperty("org.jetbrains.dokka.experimental.tryK2")
-        .map(String::toBoolean)
-        .orNull ?: false
+    @get:Classpath
+    abstract val dokkaPluginsClasspath: ConfigurableFileCollection
 
-    val analysisDependency = when {
-        tryK2 -> "org.jetbrains.dokka:analysis-kotlin-symbols"
-        else -> "org.jetbrains.dokka:analysis-kotlin-descriptors"
+    override fun asArguments(): Iterable<String> = buildList {
+        add("-D" + "dokkaCliJarPath=" + dokkaCli.asFile.get().absolutePath)
+        add("-D" + "dokkaPluginsClasspath=" + dokkaPluginsClasspath.joinToString(";") { it.absolutePath })
     }
+}
 
-    cliPluginsClasspath(analysisDependency) {
-        attributes {
-            attribute(Bundling.BUNDLING_ATTRIBUTE, project.objects.named(Bundling.SHADOWED))
+
+testing {
+    suites {
+        withType<JvmTestSuite>().configureEach {
+            useJUnitJupiter()
         }
-    }
-}
 
-val cliPluginsShadowJar by tasks.registering(ShadowJar::class) {
-    archiveFileName.set("cli-plugins-${project.version}.jar")
-    configurations = listOf(cliPluginsClasspath)
+        register<JvmTestSuite>("integrationTest") {
+            dependencies {
+                implementation(project())
+            }
 
-    // service files are merged to make sure all Dokka plugins
-    // from the dependencies are loaded, and not just a single one.
-    mergeServiceFiles()
+            targets.configureEach {
+                testTask.configure {
+                    jvmArgumentProviders.add(
+                        objects.newInstance<DokkaCliClasspathProvider>().apply {
+                            dokkaCli = configurations.dokkaCliResolver.map { it.singleFile }
+                            dokkaPluginsClasspath.from(configurations.dokkaPluginsClasspathResolver)
+                        }
+                    )
+                }
+            }
+        }
+    }
 }
 
-tasks.integrationTest {
-    dependsOn(cliClasspath)
-    dependsOn(cliPluginsShadowJar)
-
-    inputs.dir(file("projects"))
-    environment("CLI_JAR_PATH", cliClasspath.singleFile)
-    environment("BASE_PLUGIN_JAR_PATH", cliPluginsShadowJar.get().archiveFile.get())
+tasks.check {
+    dependsOn(testing.suites)
 }