[K2] Run Gradle integration tests (#3390)

* [K2] Run Gradle integration tests

* [K2] Pass the property to a test fork

* [K2] Fix "Modules are inconsistent" in the Basic Groovy test

* [K2] Fix "Modules are inconsistent" in the `SequentialTasksExecutionStressTest` test

* [K2] Mute failed tests

* [K2] Add doc

* Add comments

Author: vmishenev

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

@@ -50,7 +50,10 @@ val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) {
     testClassesDirs = integrationTestSourceSet.output.classesDirs
     classpath = integrationTestSourceSet.runtimeClasspath
 
-    useJUnitPlatform()
+    useJUnitPlatform {
+        val useK2 = (project.properties["org.jetbrains.dokka.experimental.tryK2"] as? String)?.toBoolean() ?: false
+        if (useK2) excludeTags("onlyDescriptors", "onlyDescriptorsMPP")
+    }
 
     setForkEvery(1)
     project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism ->

dokka-integration-tests/gradle/README.md

@@ -19,3 +19,9 @@ In order to update:
 * Go to `$pathToProjectInDokka`, `git fetch && git checkout $revisionNumber`
     - Prior to that, ensure that you have your git submodules initialized
 * Ensure that the corresponding `GradleIntegrationTest` passes locally and push
+
+
+### Run integration tests with K2 (symbols)
+
+To run integration tests with K2, the property `org.jetbrains.dokka.experimental.tryK2` should be set to `true`. 
+By default, the task `integrationTest` is run with K1 (descriptors).

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

@@ -22,6 +22,10 @@ dependencies {
 val aggregatingProject = gradle.includedBuild("dokka")
 
 tasks.integrationTest {
+    // pass the property to a test fork
+    project.findProperty("org.jetbrains.dokka.experimental.tryK2")
+        ?.let { systemProperty("org.jetbrains.dokka.experimental.tryK2", it) }
+
     dependsOn(aggregatingProject.task(":publishToMavenLocal"))
 
     environment("DOKKA_VERSION", project.version)

dokka-integration-tests/gradle/projects/it-basic-groovy/build.gradle

@@ -13,9 +13,10 @@ dokkaHtml {
     outputDirectory = new File(buildDir, "/dokka/customHtml")
     failOnWarning = false
     dokkaSourceSets {
+        // create a new source set
         customSourceSet {
-            sourceRoot(file("src/main/java"))
-            sourceRoot(file("src/main/kotlin"))
+            sourceRoot(file("src/custom/java"))
+            sourceRoot(file("src/custom/kotlin"))
             displayName.set("custom")
             reportUndocumented.set(true)
         }

dokka-integration-tests/gradle/projects/it-basic-groovy/src/custom/java/it/basic/java/SampleJavaClass.java

@@ -0,0 +1,17 @@
+package it.basic.java;
+
+import it.basic.PublicClass;
+
+/**
+ * This class is, unlike {@link PublicClass}, written in Java
+ */
+@SuppressWarnings("unused")
+public class SampleJavaClass {
+
+    /**
+     * @return Empty instance of {@link PublicClass}
+     */
+    public PublicClass publicDocumentedFunction() {
+        return new PublicClass();
+    }
+}

dokka-integration-tests/gradle/projects/it-basic-groovy/src/custom/kotlin/it/basic/PublicClass.kt

@@ -0,0 +1,48 @@
+@file:Suppress("unused")
+
+package it.basic
+
+class PublicClass {
+    /**
+     * This function is public and documented
+     */
+    fun publicDocumentedFunction(): String = ""
+
+    fun publicUndocumentedFunction(): String = ""
+
+    /**
+     * This function is internal and documented
+     */
+    internal fun internalDocumentedFunction(): String = ""
+
+    internal fun internalUndocumentedFunction(): String = ""
+
+    /**
+     * This function is private and documented
+     */
+    private fun privateDocumentedFunction(): String = ""
+
+    private fun privateUndocumentedFunction(): String = ""
+
+
+    /**
+     * This property is public and documented
+     */
+    val publicDocumentedProperty: Int = 0
+
+    val publicUndocumentedProperty: Int = 0
+
+    /**
+     * This property internal and documented
+     */
+    val internalDocumentedProperty: Int = 0
+
+    val internalUndocumentedProperty: Int = 0
+
+    /**
+     * This property private and documented
+     */
+    private val privateDocumentedProperty: Int = 0
+
+    private val privateUndocumentedProperty: Int = 0
+}

dokka-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/build.gradle.kts

@@ -26,10 +26,11 @@ fun createTask(name: String) {
     tasks.register(name, org.jetbrains.dokka.gradle.DokkaTask::class) {
         dokkaSourceSets {
             moduleName.set("Some example")
+            // create a new source set
             register("kotlin-stdlib-common") {
-                sourceRoots.from("src/main/java")
-                sourceRoots.from("src/main/kotlin")
-                samples.from("src/main/kotlin")
+                sourceRoots.from("src/common/java")
+                sourceRoots.from("src/common/kotlin")
+                samples.from("src/common/kotlin")
             }
         }
     }

dokka-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/src/common/java/it/basic/java/SampleJavaClass.java

@@ -0,0 +1,17 @@
+package it.basic.java;
+
+import it.basic.PublicClass;
+
+/**
+ * This class is, unlike {@link PublicClass}, written in Java
+ */
+@SuppressWarnings("unused")
+public class SampleJavaClass {
+
+    /**
+     * @return Empty instance of {@link PublicClass}
+     */
+    public PublicClass publicDocumentedFunction() {
+        return new PublicClass();
+    }
+}

dokka-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/src/common/kotlin/RootPackageClass.kt

@@ -0,0 +1,8 @@
+@file:Suppress("unused")
+
+/**
+ * A class that lives inside the root package
+ */
+class RootPackageClass {
+    val description = "I do live in the root package!"
+}

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/JsIRGradleIntegrationTest.kt

@@ -36,6 +36,7 @@ class JsIRGradleIntegrationTest : AbstractGradleIntegrationTest() {
         File(templateProjectDir, "src").copyRecursively(File(projectDir, "src"))
     }
 
+    @OnlyDescriptors
     @ParameterizedTest(name = "{0}")
     @ArgumentsSource(AllSupportedTestedVersionsArgumentsProvider::class)
     fun execute(buildVersions: BuildVersions) {

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/WasmGradleIntegrationTest.kt

@@ -41,6 +41,7 @@ class WasmGradleIntegrationTest : AbstractGradleIntegrationTest() {
         File(templateProjectDir, "src").copyRecursively(File(projectDir, "src"))
     }
 
+    @OnlyDescriptors
     @ParameterizedTest(name = "{0}")
     @ArgumentsSource(WasmTestedVersionsArgumentsProvider::class)
     fun execute(buildVersions: BuildVersions) {

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/WasmJsWasiGradleIntegrationTest.kt

@@ -40,6 +40,7 @@ class WasmJsWasiGradleIntegrationTest : AbstractGradleIntegrationTest() {
         File(templateProjectDir, "src").copyRecursively(File(projectDir, "src"))
     }
 
+    @OnlyDescriptors
     @ParameterizedTest(name = "{0}")
     @ArgumentsSource(WasmJsWasiTestedVersionsArgumentsProvider::class)
     fun execute(buildVersions: BuildVersions) {

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/CoroutinesGradleIntegrationTest.kt

@@ -9,6 +9,7 @@ import org.jetbrains.dokka.it.TestOutputCopier
 import org.jetbrains.dokka.it.copyAndApplyGitDiff
 import org.jetbrains.dokka.it.gradle.AbstractGradleIntegrationTest
 import org.jetbrains.dokka.it.gradle.BuildVersions
+import org.jetbrains.dokka.it.gradle.OnlyDescriptors
 import org.junit.jupiter.api.extension.ExtensionContext
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.Arguments
@@ -45,6 +46,7 @@ class CoroutinesGradleIntegrationTest : AbstractGradleIntegrationTest(), TestOut
         copyAndApplyGitDiff(File("projects", "coroutines/coroutines.diff"))
     }
 
+    @OnlyDescriptors
     @ParameterizedTest(name = "{0}")
     @ArgumentsSource(CoroutinesBuildVersionsArgumentsProvider::class)
     fun execute(buildVersions: BuildVersions) {

dokka-integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/kotlin/SerializationGradleIntegrationTest.kt

@@ -9,6 +9,7 @@ import org.jetbrains.dokka.it.TestOutputCopier
 import org.jetbrains.dokka.it.copyAndApplyGitDiff
 import org.jetbrains.dokka.it.gradle.AbstractGradleIntegrationTest
 import org.jetbrains.dokka.it.gradle.BuildVersions
+import org.jetbrains.dokka.it.gradle.OnlyDescriptors
 import org.junit.jupiter.api.extension.ExtensionContext
 import org.junit.jupiter.params.ParameterizedTest
 import org.junit.jupiter.params.provider.Arguments
@@ -44,6 +45,7 @@ class SerializationGradleIntegrationTest : AbstractGradleIntegrationTest(), Test
         copyAndApplyGitDiff(File("projects", "serialization/serialization.diff"))
     }
 
+    @OnlyDescriptors // failed due to https://github.com/Kotlin/dokka/issues/3207
     @ParameterizedTest(name = "{0}")
     @ArgumentsSource(SerializationBuildVersionsArgumentsProvider::class)
     fun execute(buildVersions: BuildVersions) {

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

@@ -41,6 +41,12 @@ public abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest()
                     buildVersions.androidGradlePluginVersion?.let { androidVersion ->
                         "-Pdokka_it_android_gradle_plugin_version=$androidVersion"
                     },
+                    // property flag to use K2
+                    if (TestEnvironment.shouldUseK2())
+                        "-P${TestEnvironment.TRY_K2}=true"
+                    else
+                        null,
+
                     * arguments
                 )
             ).run { this as DefaultGradleRunner }

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

@@ -4,10 +4,23 @@
 
 package org.jetbrains.dokka.it.gradle
 
+import org.junit.jupiter.api.Tag
+
 public object TestEnvironment {
+    public const val TRY_K2: String = "org.jetbrains.dokka.experimental.tryK2"
+
     public val isExhaustive: Boolean = checkNotNull(System.getenv("isExhaustive")) {
         "Missing `isExhaustive` environment variable"
     }.toBoolean()
+
+    /**
+     * By default, it is disabled
+     */
+    public fun shouldUseK2(): Boolean = getBooleanProperty(TRY_K2)
+
+    private fun getBooleanProperty(propertyName: String): Boolean {
+        return System.getProperty(propertyName) in setOf("1", "true")
+    }
 }
 
 /**
@@ -16,3 +29,19 @@ public object TestEnvironment {
 public inline fun <reified T> ifExhaustive(vararg values: T): Array<out T> {
     return if (TestEnvironment.isExhaustive) values else emptyArray()
 }
+
+/**
+ * Run a test only for descriptors (K1), not symbols (K2).
+ * The test with this annotation will be ignored only if the property [TestEnvironment.TRY_K2] = true.
+ */
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY_GETTER,
+    AnnotationTarget.PROPERTY_SETTER
+)
+@Retention(
+    AnnotationRetention.RUNTIME
+)
+@Tag("onlyDescriptors")
+public annotation class OnlyDescriptors(val reason: String = "")