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` 
+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).optional(true)
+        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/coroutines/coroutines.diff

@@ -6,7 +6,7 @@ index e7d405e12..db5dcec66 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
          maven { url "https://plugins.gradle.org/m2/" }
          CommunityProjectsBuild.addDevRepositoryIfEnabled(delegate, project)
@@ -54,7 +54,7 @@ index e7d405e12..db5dcec66 100644
  // Configure repositories
  allprojects {
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          /*
           * google should be first in the repository list because some of the play services
           * transitive dependencies was removed from jcenter, thus breaking gradle dependency resolution
@@ -80,7 +80,7 @@ index ae54ad0f6..00963f5b2 100644
  val kotlinDevUrl = project.rootProject.properties["kotlin_repo_url"] as? String
 
  repositories {
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
      mavenCentral()
      if (cacheRedirectorEnabled) {
          maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
@@ -120,7 +120,7 @@ index c2e859f65..9cc749a1f 100644
  pluginManagement {
      val build_snapshot_train: String? by settings
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
          if (cacheRedirectorEnabled) {
              println("Redirecting repositories for buildSrc buildscript")
@@ -177,7 +177,7 @@ index 151c087fd..e4433c24f 100644
 
      repositories {
 -        maven { url "https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev/" }
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //maven { url "https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev/" }
          gradlePluginPortal()
      }

dokka-integration-tests/gradle/projects/serialization/serialization.diff

@@ -7,7 +7,7 @@ index 73b566ae..e2af43bd 100644
 
      repositories {
 -        maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
          // kotlin-dev with space redirector
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -61,7 +61,7 @@ index 73b566ae..e2af43bd 100644
          // Snapshot-specific
          repositories {
 -            mavenLocal()
-+            /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++            /* %{DOKKA_IT_MAVEN_REPO}% */
 +            //mavenLocal()
              maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
          }
@@ -70,7 +70,7 @@ index 73b566ae..e2af43bd 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
 -        maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
 +        //maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
@@ -92,7 +92,7 @@ index c999bcd2..98afdae7 100644
  }
 
  repositories {
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
      mavenCentral()
 -    mavenLocal()
 +    //mavenLocal()
@@ -143,7 +143,7 @@ index dda68347..119c321a 100644
 
      repositories {
 -        mavenLocal()
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //mavenLocal()
          mavenCentral()
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -153,7 +153,7 @@ index dda68347..119c321a 100644
 
  repositories {
 -    mavenLocal()
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
 +    //mavenLocal()
      mavenCentral()
      maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -166,7 +166,7 @@ index f8cb2d87..beebf995 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
          maven { url 'https://plugins.gradle.org/m2/' }
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }

dokka-integration-tests/gradle/projects/template.settings.gradle.kts

@@ -36,7 +36,7 @@ pluginManagement {
         }
     }
     repositories {
-        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
+        /* %{DOKKA_IT_MAVEN_REPO}% */
         mavenCentral()
         gradlePluginPortal()
         google()
@@ -47,7 +47,7 @@ pluginManagement {
 dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
     repositories {
-        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
+        /* %{DOKKA_IT_MAVEN_REPO}% */
         mavenCentral()
         google()
         maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") {

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`
+
+```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,24 @@ 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) {
+                println("Dokka version overridden with $dokkaVersionOverride")
+                // if `DOKKA_VERSION_OVERRIDE` environment variable is provided,
+                //  we allow running tests on a custom Dokka version from specific repositories
+                """
+                maven("https://maven.pkg.jetbrains.space/kotlin/p/dokka/test"),
+                maven("https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev"),
+                mavenCentral(),
+                mavenLocal()
+                """.trimIndent()
+            } 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 +151,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
                     |}
                     """.trimMargin()
                 }
+            }
 
             /* language=kts */
             """
@@ -153,17 +169,17 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
 
         fun File.updateProjectLocalMavenDir() {
 
-            val dokkaDevMavenRepoMarker = "/* %{PROJECT_LOCAL_MAVEN_DIR}% */"
+            val dokkaMavenRepoMarker = "/* %{DOKKA_IT_MAVEN_REPO}% */"
 
             // 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)
                     )
                 }
             }