Update test-k2 convention to use test suites (#3524)

* Update test-k2 convention to use test suites - use jvm-test-suites to create create separate targets for descriptor and symbols tests - rename descriptorsTest/symbolsTest tasks - update Configurations to use newer Gradle guidelines for declarable/resolvable configurations - add comments to clarify K1 vs K2 analysis - always run symbol and descriptor tests
Kotlin · Mar 22, 2024 · 1ed0186 · 1ed0186
1 parent 507770a
commit 1ed0186
Show file tree

Hide file tree

Showing 8 changed files with 180 additions and 42 deletions.
diff --git a/build-logic/src/main/kotlin/dokkabuild.test-k2.gradle.kts b/build-logic/src/main/kotlin/dokkabuild.test-k2.gradle.kts
@@ -1,6 +1,9 @@
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
+import dokkabuild.utils.declarable
+import dokkabuild.utils.jvmJar
+import dokkabuild.utils.resolvable
 
 /**
  * Utility to run unit tests for K1 and K2 (analysis API).
@@ -9,39 +12,83 @@
 plugins {
     id("dokkabuild.base")
     id("dokkabuild.java")
+    `jvm-test-suite`
 }
 
-val descriptorsTestConfiguration: Configuration by configurations.creating {
-    extendsFrom(configurations.testImplementation.get())
-}
-val symbolsTestConfiguration: Configuration by configurations.creating {
-    extendsFrom(configurations.testImplementation.get())
+val symbolsTestImplementation: Configuration by configurations.creating {
+    description = "Dependencies for symbols tests (K2)"
+    declarable()
 }
 
-val symbolsTest = tasks.register<Test>("symbolsTest") {
-    useJUnitPlatform {
-        excludeTags("onlyDescriptors", "onlyDescriptorsMPP")
-    }
-    classpath += symbolsTestConfiguration
-}
-// run symbols and descriptors tests
-tasks.test {
-    //enabled = false
-    useJUnitPlatform {
-        excludeTags("onlySymbols")
-    }
-    classpath += descriptorsTestConfiguration
-    dependsOn(symbolsTest)
+val symbolsTestImplementationResolver: Configuration by configurations.creating {
+    description = "Resolve dependencies for symbols tests (K2)"
+    resolvable()
+    extendsFrom(symbolsTestImplementation)
+    attributes { jvmJar(objects) }
 }
 
-val descriptorsTest = tasks.register<Test>("descriptorsTest") {
-    useJUnitPlatform {
-        excludeTags("onlySymbols")
-    }
-    classpath += descriptorsTestConfiguration
+val descriptorsTestImplementation: Configuration by configurations.creating {
+    description = "Dependencies for descriptors tests (K1)"
+    declarable()
 }
 
-tasks.check {
-    dependsOn(symbolsTest)
+val descriptorsTestImplementationResolver: Configuration by configurations.creating {
+    description = "Resolve dependencies for descriptors tests (K1)"
+    resolvable()
+    extendsFrom(descriptorsTestImplementation)
+    attributes { jvmJar(objects) }
 }
 
+@Suppress("UnstableApiUsage")
+testing {
+    suites {
+        val test by suites.getting(JvmTestSuite::class) {
+
+            // JUnit tags for descriptors (K1) and symbols (K2) are defined with annotations in test classes.
+            val onlyDescriptorTags = listOf("onlyDescriptors", "onlyDescriptorsMPP")
+            val onlySymbolsTags = listOf("onlySymbols")
+
+            // Modify the regular :test target to exclude symbols (K2) tests.
+            val testTarget = targets.named("test") {
+                testTask.configure {
+                    description = "Runs tests using descriptors-analysis (K1) (excluding tags: $onlySymbolsTags)"
+                    useJUnitPlatform {
+                        excludeTags.addAll(onlySymbolsTags)
+                    }
+                    classpath += descriptorsTestImplementationResolver.incoming.files
+                }
+            }
+
+            // Create a new target for _only_ running test compatible with descriptor-analysis (K1).
+            // Note: this target is the same as the regular test target, it is only created to provide a more descriptive name.
+            targets.register("testDescriptors") {
+                testTask.configure {
+                    description = "Runs tests using descriptors-analysis (K1) (excluding tags: ${onlySymbolsTags})"
+                    useJUnitPlatform {
+                        excludeTags.addAll(onlySymbolsTags)
+                    }
+                    classpath += descriptorsTestImplementationResolver.incoming.files
+                }
+            }
+
+            // Create a new target for _only_ running test compatible with symbols-analysis (K2).
+            val testSymbolsTarget = targets.register("testSymbols") {
+                testTask.configure {
+                    description = "Runs tests using symbols-analysis (K2) (excluding tags: ${onlyDescriptorTags})"
+                    useJUnitPlatform {
+                        excludeTags.addAll(onlyDescriptorTags)
+                    }
+                    classpath += symbolsTestImplementationResolver.incoming.files
+                }
+            }
+
+            // So that both K1 and K2 are tested, when running :test, also run :testSymbols
+            // (Running :descriptorsTest isn't required, because it has the same tags/dependencies as :test)
+            testTarget.configure {
+                testTask.configure {
+                    finalizedBy(testSymbolsTarget.map { it.testTask })
+                }
+            }
+        }
+    }
+}
diff --git a/build-logic/src/main/kotlin/dokkabuild/utils/gradle.kt b/build-logic/src/main/kotlin/dokkabuild/utils/gradle.kt
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package dokkabuild.utils
+
+import org.gradle.api.artifacts.Configuration
+import org.gradle.api.attributes.*
+import org.gradle.api.attributes.java.TargetJvmEnvironment
+import org.gradle.api.model.ObjectFactory
+import org.gradle.kotlin.dsl.named
+
+
+/**
+ * Mark this [Configuration] as one that should be used to declare dependencies in
+ * [org.gradle.api.Project.dependencies] block.
+ *
+ * Declarable Configurations should be extended by [resolvable] and [consumable] Configurations.
+ * They must not have attributes.
+ *
+ * ```
+ * isCanBeResolved = false
+ * isCanBeConsumed = false
+ * isCanBeDeclared = true
+ * ```
+ */
+internal fun Configuration.declarable(
+    visible: Boolean = false,
+) {
+    isCanBeResolved = false
+    isCanBeConsumed = false
+    @Suppress("UnstableApiUsage")
+    isCanBeDeclared = true
+    isVisible = visible
+}
+
+
+/**
+ * Mark this [Configuration] as one that will be consumed by other subprojects.
+ *
+ * Consumable Configurations must extend a [declarable] Configuration.
+ * They should have attributes.
+ *
+ * ```
+ * isCanBeResolved = false
+ * isCanBeConsumed = true
+ * isCanBeDeclared = false
+ * ```
+ */
+internal fun Configuration.consumable(
+    visible: Boolean = false,
+) {
+    isCanBeResolved = false
+    isCanBeConsumed = true
+    @Suppress("UnstableApiUsage")
+    isCanBeDeclared = false
+    isVisible = visible
+}
+
+
+/**
+ * Mark this [Configuration] as one that will consume artifacts from other subprojects (also known as 'resolving')
+ *
+ * Resolvable Configurations should have attributes.
+ *
+ * ```
+ * isCanBeResolved = true
+ * isCanBeConsumed = false
+ * isCanBeDeclared = false
+ * ```
+ */
+internal fun Configuration.resolvable(
+    visible: Boolean = false,
+) {
+    isCanBeResolved = true
+    isCanBeConsumed = false
+    @Suppress("UnstableApiUsage")
+    isCanBeDeclared = false
+    isVisible = visible
+}
+
+
+internal fun AttributeContainer.jvmJar(objects: ObjectFactory) {
+    attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage.JAVA_RUNTIME))
+    attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.LIBRARY))
+    attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL))
+    attribute(TargetJvmEnvironment.TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(TargetJvmEnvironment.STANDARD_JVM))
+    attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements.JAR))
+}
diff --git a/dokka-subprojects/analysis-kotlin-api/build.gradle.kts b/dokka-subprojects/analysis-kotlin-api/build.gradle.kts
@@ -20,8 +20,10 @@ dependencies {
 
     testImplementation(kotlin("test"))
 
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(
+        project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow")
+    )
 }
 
 disableTestFixturesPublishing()

diff --git a/dokka-subprojects/plugin-android-documentation/build.gradle.kts b/dokka-subprojects/plugin-android-documentation/build.gradle.kts
@@ -23,8 +23,8 @@ dependencies {
     testImplementation(projects.dokkaSubprojects.pluginBase)
     testImplementation(projects.dokkaSubprojects.coreTestApi)
 
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
     testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) {
         exclude(module = "analysis-kotlin-descriptors")
     }

diff --git a/dokka-subprojects/plugin-base/build.gradle.kts b/dokka-subprojects/plugin-base/build.gradle.kts
@@ -36,8 +36,8 @@ dependencies {
     testImplementation(kotlin("test"))
     testImplementation(libs.junit.jupiterParams)
 
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(
         project(
             path = ":dokka-subprojects:analysis-kotlin-descriptors",
             configuration = "shadow"
@@ -55,11 +55,11 @@ dependencies {
     }
 }
 
-// access the frontend files via the dependency on :plugins:base:frontend
-val dokkaHtmlFrontendFiles: Provider<FileCollection> =
+    // access the frontend files via the dependency on :plugins:base:frontend
+    val dokkaHtmlFrontendFiles: Provider<FileCollection> =
     configurations.dokkaHtmlFrontendFiles.map { frontendFiles ->
-        frontendFiles.incoming.artifacts.artifactFiles
-    }
+            frontendFiles.incoming.artifacts.artifactFiles
+        }
 
 val prepareDokkaHtmlFrontendFiles by tasks.registering(Sync::class) {
     description = "copy Dokka Base frontend files into the resources directory"

diff --git a/dokka-subprojects/plugin-javadoc/build.gradle.kts b/dokka-subprojects/plugin-javadoc/build.gradle.kts
@@ -25,8 +25,8 @@ dependencies {
     implementation(libs.kotlinx.coroutines.core)
 
     testImplementation(kotlin("test"))
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
     testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) {
         exclude(module = "analysis-kotlin-descriptors")
     }

diff --git a/dokka-subprojects/plugin-kotlin-as-java/build.gradle.kts b/dokka-subprojects/plugin-kotlin-as-java/build.gradle.kts
@@ -23,8 +23,8 @@ dependencies {
     testImplementation(kotlin("test"))
     testImplementation(libs.jsoup)
     testImplementation(projects.dokkaSubprojects.pluginBase)
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
     testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) {
         exclude(module = "analysis-kotlin-descriptors")
     }

diff --git a/dokka-subprojects/plugin-mathjax/build.gradle.kts b/dokka-subprojects/plugin-mathjax/build.gradle.kts
@@ -24,8 +24,8 @@ dependencies {
     testImplementation(projects.dokkaSubprojects.coreContentMatcherTestUtils)
     testImplementation(projects.dokkaSubprojects.coreTestApi)
 
-    symbolsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
-    descriptorsTestConfiguration(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
+    symbolsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-symbols", configuration = "shadow"))
+    descriptorsTestImplementation(project(path = ":dokka-subprojects:analysis-kotlin-descriptors", configuration = "shadow"))
     testImplementation(projects.dokkaSubprojects.pluginBaseTestUtils) {
         exclude(module = "analysis-kotlin-descriptors")
     }