KT-64377 - Preparation for Gradle integration test build config refac…

…toring (#3422)

* KT-64377 - remove gradle wrapper files for integration test projects (#3418)

* remove Gradle wrapper files for integration test projects
* .gitignore Gradle wrapper files

* refactor integration test properties to use DokkaBuildProperties utility (#3420)

rename 'tryK2' to 'useK2' for integration tests

* disable explicit API mode in non-published integration-test utilities (#3428)

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

@@ -3,6 +3,7 @@
  */
 
 import dokkabuild.DokkaBuildProperties
+import org.gradle.language.base.plugins.LifecycleBasePlugin.VERIFICATION_GROUP
 
 /**
  * A convention plugin that sets up common config and sensible defaults for all subprojects.
@@ -21,3 +22,9 @@ tasks.withType<AbstractArchiveTask>().configureEach {
     isPreserveFileTimestamps = false
     isReproducibleFileOrder = true
 }
+
+val integrationTestPreparation by tasks.registering {
+    description =
+        "lifecycle task for preparing the project for integration tests (for example, publishing to the test Maven repo)"
+    group = VERIFICATION_GROUP
+}

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

@@ -51,21 +51,16 @@ val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) {
     classpath = integrationTestSourceSet.runtimeClasspath
 
     useJUnitPlatform {
-        val useK2 = (project.properties["org.jetbrains.dokka.experimental.tryK2"] as? String)?.toBoolean() ?: false
-        if (useK2) excludeTags("onlyDescriptors", "onlyDescriptorsMPP")
+        if (dokkaBuild.integrationTestUseK2.get()) excludeTags("onlyDescriptors", "onlyDescriptorsMPP")
     }
 
-    setForkEvery(1)
-    project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism ->
+    systemProperty("org.jetbrains.dokka.experimental.tryK2", dokkaBuild.integrationTestUseK2.get())
+
+    dokkaBuild.integrationTestParallelism.orNull?.let { parallelism ->
         maxParallelForks = parallelism
     }
 
-    environment(
-        "isExhaustive",
-        project.properties["dokka_integration_test_is_exhaustive"]?.toString()?.toBoolean()
-            ?: System.getenv("DOKKA_INTEGRATION_TEST_IS_EXHAUSTIVE")?.toBoolean()
-            ?: false.toString()
-    )
+    environment("isExhaustive", dokkaBuild.integrationTestExhaustive.get())
 
     testLogging {
         exceptionFormat = TestExceptionFormat.FULL

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

@@ -48,6 +48,20 @@ abstract class DokkaBuildProperties @Inject constructor(
     val kotlinLanguageLevel: Provider<KotlinVersion> =
         dokkaProperty("kotlinLanguageLevel", KotlinVersion::fromVersion)
 
+    /** Control [org.gradle.api.tasks.testing.Test.maxParallelForks] in integration tests. */
+    val integrationTestParallelism: Provider<Int> =
+        dokkaProperty("integration_test.parallelism", String::toInt)
+
+    /** Not currently used - should be dropped. */
+    val integrationTestExhaustive: Provider<Boolean> =
+        dokkaProperty("integration_test.exhaustive", String::toBoolean)
+            .orElse(false)
+
+    /** Control whether integration tests should use the `org.jetbrains.dokka.experimental.tryK2` flag. */
+    val integrationTestUseK2: Provider<Boolean> =
+        dokkaProperty("integration_test.useK2", String::toBoolean)
+            .orElse(false)
+
 
     private fun <T : Any> dokkaProperty(name: String, convert: (String) -> T) =
         providers.gradleProperty("org.jetbrains.dokka.$name").map(convert)

dokka-integration-tests/gradle.properties

@@ -9,4 +9,4 @@ version=2.0.0-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
-dokka_integration_test_parallelism=2
+org.jetbrains.dokka.integration_test.parallelism=2

dokka-integration-tests/gradle/.gitignore

@@ -0,0 +1,8 @@
+# These projects are run using Gradle TestKit, which does not require Gradle or IDE files.
+# However, it is convenient to open up the project in an IDE, which will automatically
+# download Gradle files - but since they're not nessessary, don't commit them.
+.idea
+**/gradle/wrapper/**
+gradlew.bat
+gradlew
+gradle.properties

dokka-integration-tests/gradle/README.md

@@ -25,5 +25,5 @@ In order to update:
 
 ### 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).
+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).

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

@@ -1,8 +1,9 @@
+import org.jetbrains.kotlin.gradle.dsl.ExplicitApiMode
+
 /*
  * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-
 plugins {
     id("dokkabuild.test-integration")
 }
@@ -19,13 +20,14 @@ dependencies {
     implementation(libs.jsoup)
 }
 
+kotlin {
+    // this project only contains test utils and isn't published, so it doesn't matter about explicit API
+    explicitApi = ExplicitApiMode.Disabled
+}
+
 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)