Disable caching of Dokka's integration tests (#2826)

1 files changed, 22 insertions, 1 deletions

diff --git a/integration-tests/build.gradle.kts b/integration-tests/build.gradle.kts
index 45e16097..226b4b6f 100644
--- a/integration-tests/build.gradle.kts
+++ b/integration-tests/build.gradle.kts
@@ -21,7 +21,28 @@ subprojects {
         implementation(project(":integration-tests"))
     }
 
-    val integrationTest by tasks.register<Test>("integrationTest") {
+    /**
+     * Dokka's integration test task is not cacheable because the HTML outputs
+     * it produces when running the tests are used for showcasing resulting documentation,
+     * which does not work well with caching.
+     *
+     * At the moment there are two problems that do not allow to make it cacheable:
+     *
+     * 1. The task's inputs are such that changes in Dokka's code do not invalidate the cache,
+     *    because it is run with the same version of Dokka ("DOKKA_VERSION") on the same
+     *    test project inputs.
+     * 2. The tests generate HTML output which is then used to showcase documentation.
+     *    The outputs are usually copied to a location from which it will be served.
+     *    However, if the test is cacheable, it produces no outputs, so no documentation
+     *    to showcase. It needs to be broken into two separate tasks: one cacheable for running
+     *    the tests and producing HTML output, and another non-cacheable for copying the output.
+     *
+     * @see [org.jetbrains.dokka.it.TestOutputCopier] for more details on showcasing documentation
+     */
+    @DisableCachingByDefault(because = "Contains incorrect inputs/outputs configuration, see the KDoc for details")
+    abstract class NonCacheableIntegrationTest : Test()
+
+    val integrationTest by tasks.register<NonCacheableIntegrationTest>("integrationTest") {
         maxHeapSize = "2G"
         description = "Runs integration tests."
         group = "verification"