From 199d6be5eb85aa6636f4b9b94d5db2c6b62aca2b Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Thu, 25 Apr 2024 19:03:22 +0300 Subject: [PATCH] Allow overriding a Dokka version in integration tests --- CONTRIBUTING.md | 10 ++++ .../kotlin/dokkabuild/DokkaBuildProperties.kt | 4 ++ .../gradle/build.gradle.kts | 3 ++ .../gradle/AbstractGradleIntegrationTest.kt | 49 +++++++++++++++---- 4 files changed, 57 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3da88da3c..f6de757a27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,6 +105,16 @@ 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) or +[test](https://maven.pkg.jetbrains.space/kotlin/p/dokka/test) +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 diff --git a/build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt b/build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt index 3ddfa4e102..0102b3d1e5 100644 --- a/build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt +++ b/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 = + dokkaProperty("integration_test.dokkaVersionOverride") { it } + val androidSdkDir: Provider = providers // first try finding a local.properties file in any parent directory diff --git a/dokka-integration-tests/gradle/build.gradle.kts b/dokka-integration-tests/gradle/build.gradle.kts index 2463996ca8..47d3766062 100644 --- a/dokka-integration-tests/gradle/build.gradle.kts +++ b/dokka-integration-tests/gradle/build.gradle.kts @@ -94,6 +94,9 @@ tasks.withType().configureEach { } // environment() isn't Provider API compatible yet https://github.com/gradle/gradle/issues/11534 + dokkaBuild.integrationTestDokkaVersionOverride.orNull?.let { versionOverride -> + environment("DOKKA_VERSION_OVERRIDE", versionOverride) + } dokkaBuild.integrationTestExhaustive.orNull?.let { exhaustive -> environment("isExhaustive", exhaustive) } diff --git a/dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt b/dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt index 7e1793b482..f85ba6859d 100644 --- a/dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt +++ b/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 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,7 +184,7 @@ 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. @@ -161,9 +192,9 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() { 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) ) } }