diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3da88da3c..3973619dcb 100644 --- a/CONTRIBUTING.md +++ b/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 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 2e11f96538..fa87425eca 100644 --- a/dokka-integration-tests/gradle/build.gradle.kts +++ b/dokka-integration-tests/gradle/build.gradle.kts @@ -94,13 +94,15 @@ tasks.withType().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) { + 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) diff --git a/dokka-integration-tests/gradle/projects/coroutines/coroutines.diff b/dokka-integration-tests/gradle/projects/coroutines/coroutines.diff index 0f03057015..09540912e5 100644 --- a/dokka-integration-tests/gradle/projects/coroutines/coroutines.diff +++ b/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() } diff --git a/dokka-integration-tests/gradle/projects/serialization/serialization.diff b/dokka-integration-tests/gradle/projects/serialization/serialization.diff index da51d8667e..31c7ac8fe2 100644 --- a/dokka-integration-tests/gradle/projects/serialization/serialization.diff +++ b/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" } diff --git a/dokka-integration-tests/gradle/projects/template.settings.gradle.kts b/dokka-integration-tests/gradle/projects/template.settings.gradle.kts index 05d176a6ae..663399a7a4 100644 --- a/dokka-integration-tests/gradle/projects/template.settings.gradle.kts +++ b/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") { diff --git a/dokka-integration-tests/gradle/projects/ui-showcase/README.md b/dokka-integration-tests/gradle/projects/ui-showcase/README.md index 7aff495754..0ef78cee47 100644 --- a/dokka-integration-tests/gradle/projects/ui-showcase/README.md +++ b/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 +``` 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..18539b2cf1 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,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 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,7 +169,7 @@ 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. @@ -161,9 +177,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) ) } }