Allow overriding a Dokka version in integration tests

CONTRIBUTING.md

@@ -105,6 +105,17 @@ However, if you need to run all integration tests locally, you can use the `inte
 If you need to run a specific test locally, you can run it from your IDE or by calling the corresponding Gradle
 task (for example, `:dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines`).
 
+It's possible to run integration tests with a custom Dokka version published to
+[MavenCentral](https://central.sonatype.com),
+[dev](https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev),
+[test](https://maven.pkg.jetbrains.space/kotlin/p/dokka/test) or
+`mavenLocal` (in this case the version should contain `-local-` suffix, f.e `2.0.0-local-reproducing-bug`) 
+via `org.jetbrains.dokka.integration_test.dokkaVersionOverride` Gradle property:
+
+```bash
+./gradlew :dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines -Porg.jetbrains.dokka.integration_test.dokkaVersionOverride=2.0.0-dev-329
+```
+
 ## Infrastructure
 
 ### Java version

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

@@ -81,6 +81,10 @@ abstract class DokkaBuildProperties @Inject constructor(
         dokkaProperty("integration_test.useK2", String::toBoolean)
             .orElse(false)
 
+    /** Allows running integration tests with a custom Dokka version */
+    val integrationTestDokkaVersionOverride: Provider<String> =
+        dokkaProperty("integration_test.dokkaVersionOverride") { it }
+
     val androidSdkDir: Provider<File> =
         providers
             // first try finding a local.properties file in any parent directory

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

@@ -94,13 +94,15 @@ tasks.withType<Test>().configureEach {
     }
 
     // environment() isn't Provider API compatible yet https://github.com/gradle/gradle/issues/11534
-    dokkaBuild.integrationTestExhaustive.orNull?.let { exhaustive ->
-        environment("isExhaustive", exhaustive)
-    }
-    dokkaBuild.androidSdkDir.orNull?.let { androidSdkDir ->
-        environment("ANDROID_HOME", androidSdkDir.invariantSeparatorsPath)
+    fun environmentProvider(name: String, provider: Provider<out Any>) {
+        inputs.property(name, provider)
+        provider.orNull?.let { environment(name, it) }
     }
 
+    environmentProvider("DOKKA_VERSION_OVERRIDE", dokkaBuild.integrationTestDokkaVersionOverride)
+    environmentProvider("isExhaustive", dokkaBuild.integrationTestExhaustive)
+    environmentProvider("ANDROID_HOME", dokkaBuild.androidSdkDir.map { it.invariantSeparatorsPath })
+
     testLogging {
         exceptionFormat = FULL
         events(SKIPPED, FAILED)

dokka-integration-tests/gradle/projects/ui-showcase/README.md

@@ -5,9 +5,22 @@ This is a Dokka test project for UI e2e tests.
 The goal is to have as much variety of UI elements in one project as possible, so that during refactorings
 we can compare the outputs between different versions of Dokka and make sure we didn't break any corner cases.
 
-### Run from root of the project
+### Run from the root of the project
 
 ```bash
 export DOKKA_TEST_OUTPUT_PATH="build/ui-showcase-result"
 ./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject
 ```
+
+### Run with the published Dokka version
+
+Dokka should be published in one of the following repositories:
+[MavenCentral](https://central.sonatype.com),
+[dev](https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev),
+[test](https://maven.pkg.jetbrains.space/kotlin/p/dokka/test) or
+`mavenLocal` (in this case the version should contain `-local-` suffix, f.e `2.0.0-local-reproducing-bug`)
+
+```bash
+export DOKKA_TEST_OUTPUT_PATH="build/ui-showcase-result"
+./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject -Porg.jetbrains.dokka.integration_test.dokkaVersionOverride=2.0.0-dev-329
+```

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

@@ -67,7 +67,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
             .withDebug(TestEnvironment.isEnabledDebug)
             .withArguments(
                 listOfNotNull(
-                    "-Pdokka_it_dokka_version=${System.getenv("DOKKA_VERSION")}",
+                    "-Pdokka_it_dokka_version=${dokkaVersion}",
                     "-Pdokka_it_kotlin_version=${buildVersions.kotlinVersion}",
                     buildVersions.androidGradlePluginVersion?.let { androidVersion ->
                         "-Pdokka_it_android_gradle_plugin_version=$androidVersion"
@@ -103,6 +103,9 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
     }
 
     companion object {
+        private val dokkaVersionOverride: String? = System.getenv("DOKKA_VERSION_OVERRIDE")
+        private val dokkaVersion: String = dokkaVersionOverride ?: System.getenv("DOKKA_VERSION")
+
         /**
          * Location of the template project that will be copied into [AbstractIntegrationTest.projectDir].
          *
@@ -120,12 +123,39 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
         val templateSettingsGradleKts: Path by systemProperty(Paths::get)
 
         /** file-based Maven repositories with Dokka dependencies */
-        private val devMavenRepositories: String by systemProperty { repos ->
-            val repoPaths = repos.split(",").map { Paths.get(it) }
+        private val devMavenRepositories: List<Path> by systemProperty { repos ->
+            repos.split(",").map { Paths.get(it) }
+        }
 
-            val reposSpecs = repoPaths
-                .withIndex()
-                .joinToString(",\n") { (i, repoPath) ->
+        private val mavenRepositories: String by lazy {
+            val reposSpecs = if (dokkaVersionOverride != null) {
+                // if `DOKKA_VERSION_OVERRIDE` environment variable is provided,
+                //  we allow running tests on a custom Dokka version from specific repositories
+                when {
+                    // release version like `2.0.0`
+                    !dokkaVersion.contains("-") -> "mavenCentral()"
+                    // locally published version for testing some bug like `2.0.0-local-reproducing-bug`
+                    dokkaVersion.contains("-local-") -> "mavenLocal()"
+                    // dev version like `2.0.0-dev-329`
+                    dokkaVersion.contains("-dev-") -> "maven(\"https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev\")"
+                    // test version like `2.0.0-test-49477c44dfc58e2702f4c145ff41190b39d117fb`
+                    dokkaVersion.contains("-test-") -> "maven(\"https://maven.pkg.jetbrains.space/kotlin/p/dokka/test\")"
+                    else -> error(
+                        """
+                        Provided Dokka version override is not supported: $dokkaVersion.
+                        Supported versions are:
+                        - release versions like '2.0.0'
+                        - dev versions like `2.0.0-dev-329`
+                        - test versions like `2.0.0-test-49477c44dfc58e2702f4c145ff41190b39d117fb`
+                        - locally published (to mavenLocal) versions with `-local-` suffix like `2.0.0-local-reproducing-bug`
+                        """.trimIndent()
+                    )
+                }.also { repository ->
+                    println("Dokka version overridden with ${dokkaVersionOverride}. Using $repository for resolving Dokka")
+                }
+            } else {
+                // otherwise - use locally published versions via `devMavenPublish`
+                devMavenRepositories.withIndex().joinToString(",\n") { (i, repoPath) ->
                     // Exclusive repository containing local Dokka artifacts.
                     // Must be compatible with both Groovy and Kotlin DSL.
                     /* language=kts */
@@ -136,6 +166,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
                     |}
                     """.trimMargin()
                 }
+            }
 
             /* language=kts */
             """
@@ -153,17 +184,17 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
 
         fun File.updateProjectLocalMavenDir() {
 
-            val dokkaDevMavenRepoMarker = "/* %{PROJECT_LOCAL_MAVEN_DIR}% */"
+            val dokkaMavenRepoMarker = "/* %{PROJECT_LOCAL_MAVEN_DIR}% */"
 
             // Exclusive repository containing local Dokka artifacts.
             // Must be compatible with both Groovy and Kotlin DSL.
 
             walk().filter { it.isFile }.forEach { file ->
                 val fileText = file.readText()
 
-                if (dokkaDevMavenRepoMarker in fileText) {
+                if (dokkaMavenRepoMarker in fileText) {
                     file.writeText(
-                        fileText.replace(dokkaDevMavenRepoMarker, devMavenRepositories)
+                        fileText.replace(dokkaMavenRepoMarker, mavenRepositories)
                     )
                 }
             }