- Move `test` projects into semantic parent projects

- Implement new `:test-utils` project
- Resolve requirement for Android SDK installation

4 files changed, 460 insertions, 0 deletions

diff --git a/core/test-api/src/main/kotlin/testApi/context/MockContext.kt b/core/test-api/src/main/kotlin/testApi/context/MockContext.kt
new file mode 100644
index 00000000..97347695
--- /dev/null
+++ b/core/test-api/src/main/kotlin/testApi/context/MockContext.kt
@@ -0,0 +1,47 @@
+package org.jetbrains.dokka.testApi.context
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.ExtensionPoint
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import kotlin.reflect.KClass
+import kotlin.reflect.KMutableProperty
+import kotlin.reflect.full.memberProperties
+
+@Suppress("UNCHECKED_CAST") // It is only usable from tests so we do not care about safety
+class MockContext(
+    vararg extensions: Pair<ExtensionPoint<*>, (DokkaContext) -> Any>,
+    private val testConfiguration: DokkaConfiguration? = null,
+    private val unusedExtensionPoints: List<ExtensionPoint<*>>? = null
+) : DokkaContext {
+    private val extensionMap by lazy {
+        extensions.groupBy(Pair<ExtensionPoint<*>, (DokkaContext) -> Any>::first) {
+            it.second(this)
+        }
+    }
+
+    private val plugins = mutableMapOf<KClass<out DokkaPlugin>, DokkaPlugin>()
+
+    override fun <T : DokkaPlugin> plugin(kclass: KClass<T>): T? = plugins.getOrPut(kclass) {
+        kclass.constructors.single { it.parameters.isEmpty() }.call().also { it.injectContext(this) }
+    } as T
+
+    override fun <T : Any, E : ExtensionPoint<T>> get(point: E): List<T> = extensionMap[point].orEmpty() as List<T>
+
+    override fun <T : Any, E : ExtensionPoint<T>> single(point: E): T = get(point).single()
+
+    override val logger = DokkaConsoleLogger
+
+    override val configuration: DokkaConfiguration
+        get() = testConfiguration ?: throw IllegalStateException("This mock context doesn't provide configuration")
+
+    override val unusedPoints: Collection<ExtensionPoint<*>>
+        get() = unusedExtensionPoints
+            ?: throw IllegalStateException("This mock context doesn't provide unused extension points")
+}
+
+private fun DokkaPlugin.injectContext(context: DokkaContext) {
+    (DokkaPlugin::class.memberProperties.single { it.name == "context" } as KMutableProperty<*>)
+        .setter.call(this, context)
+}
diff --git a/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt b/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt
new file mode 100644
index 00000000..4f81f098
--- /dev/null
+++ b/core/test-api/src/main/kotlin/testApi/logger/TestLogger.kt
@@ -0,0 +1,79 @@
+package org.jetbrains.dokka.testApi.logger
+
+import org.jetbrains.dokka.utilities.DokkaLogger
+
+class TestLogger(private val logger: DokkaLogger) : DokkaLogger {
+    override var warningsCount: Int by logger::warningsCount
+    override var errorsCount: Int by logger::errorsCount
+
+    private var _debugMessages = mutableListOf<String>()
+    val debugMessages: List<String> get() = _debugMessages.toList()
+
+    private var _infoMessages = mutableListOf<String>()
+    val infoMessages: List<String> get() = _infoMessages.toList()
+
+    private var _progressMessages = mutableListOf<String>()
+    val progressMessages: List<String> get() = _progressMessages.toList()
+
+    private var _warnMessages = mutableListOf<String>()
+    val warnMessages: List<String> get() = _warnMessages.toList()
+
+    private var _errorMessages = mutableListOf<String>()
+    val errorMessages: List<String> get() = _errorMessages.toList()
+
+    override fun debug(message: String) {
+        _debugMessages.add(message)
+        logger.debug(message)
+    }
+
+    override fun info(message: String) {
+        _infoMessages.add(message)
+        logger.info(message)
+    }
+
+    override fun progress(message: String) {
+        _progressMessages.add(message)
+        logger.progress(message)
+    }
+
+    override fun warn(message: String) {
+        _warnMessages.add(message)
+        logger.warn(message)
+    }
+
+    override fun error(message: String) {
+        _errorMessages.add(message)
+        logger.error(message)
+    }
+}
+
+class FilteringLogger(
+    private val minLevel: Level,
+    private val downstream: DokkaLogger
+) : DokkaLogger {
+    enum class Level { Debug, Info, Progress, Warn, Error }
+
+    override var warningsCount: Int by downstream::warningsCount
+
+    override var errorsCount by downstream::errorsCount
+
+    override fun debug(message: String) {
+        if (minLevel <= Level.Debug) downstream.debug(message)
+    }
+
+    override fun info(message: String) {
+        if (minLevel <= Level.Info) downstream.info(message)
+    }
+
+    override fun progress(message: String) {
+        if (minLevel <= Level.Progress) downstream.progress(message)
+    }
+
+    override fun warn(message: String) {
+        if (minLevel <= Level.Warn) downstream.warn(message)
+    }
+
+    override fun error(message: String) {
+        if (minLevel <= Level.Error) downstream.error(message)
+    }
+}
diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt b/core/test-api/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt
new file mode 100644
index 00000000..414919dc
--- /dev/null
+++ b/core/test-api/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt
@@ -0,0 +1,45 @@
+package org.jetbrains.dokka.testApi.testRunner
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.utilities.DokkaLogger
+
+internal class DokkaTestGenerator(
+    private val configuration: DokkaConfiguration,
+    private val logger: DokkaLogger,
+    private val testMethods: TestMethods,
+    private val additionalPlugins: List<DokkaPlugin> = emptyList()
+) {
+
+    fun generate() = with(testMethods) {
+        val dokkaGenerator = DokkaGenerator(configuration, logger)
+
+        val context =
+            dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins)
+        pluginsSetupStage(context)
+
+        val modulesFromPlatforms = dokkaGenerator.createDocumentationModels(context)
+        documentablesCreationStage(modulesFromPlatforms)
+
+        val filteredModules = dokkaGenerator.transformDocumentationModelBeforeMerge(modulesFromPlatforms, context)
+        documentablesFirstTransformationStep(filteredModules)
+
+        val documentationModel = dokkaGenerator.mergeDocumentationModels(filteredModules, context)
+        documentablesMergingStage(documentationModel)
+
+        val transformedDocumentation = dokkaGenerator.transformDocumentationModelAfterMerge(documentationModel, context)
+        documentablesTransformationStage(transformedDocumentation)
+
+        val pages = dokkaGenerator.createPages(transformedDocumentation, context)
+        pagesGenerationStage(pages)
+
+        val transformedPages = dokkaGenerator.transformPages(pages, context)
+        pagesTransformationStage(transformedPages)
+
+        dokkaGenerator.render(transformedPages, context)
+        renderingStage(transformedPages, context)
+
+        dokkaGenerator.reportAfterRendering(context)
+    }
+}
diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt
new file mode 100644
index 00000000..a23c2713
--- /dev/null
+++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestRunner.kt
@@ -0,0 +1,289 @@
+package org.jetbrains.dokka.testApi.testRunner
+
+import com.intellij.openapi.application.PathManager
+import org.jetbrains.dokka.*
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
+import org.jetbrains.dokka.pages.RootPageNode
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.testApi.logger.TestLogger
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
+import org.junit.rules.TemporaryFolder
+import java.io.File
+import java.net.URL
+import java.nio.charset.Charset
+import java.nio.file.Files
+import java.nio.file.InvalidPathException
+import java.nio.file.Path
+import java.nio.file.Paths
+
+// TODO: take dokka configuration from file
+abstract class AbstractCoreTest(
+    protected val logger: TestLogger = TestLogger(DokkaConsoleLogger)
+) {
+    protected fun getTestDataDir(name: String) =
+        File("src/test/resources/$name").takeIf { it.exists() }?.toPath()
+            ?: throw InvalidPathException(name, "Cannot be found")
+
+    protected fun testFromData(
+        configuration: DokkaConfigurationImpl,
+        cleanupOutput: Boolean = true,
+        pluginOverrides: List<DokkaPlugin> = emptyList(),
+        block: TestBuilder.() -> Unit
+    ) {
+        val testMethods = TestBuilder().apply(block).build()
+        val tempDir = getTempDir(cleanupOutput)
+        if (!cleanupOutput)
+            logger.info("Output generated under: ${tempDir.root.absolutePath}")
+        val newConfiguration =
+            configuration.copy(
+                outputDir = tempDir.root
+            )
+        DokkaTestGenerator(
+            newConfiguration,
+            logger,
+            testMethods,
+            pluginOverrides
+        ).generate()
+    }
+
+    protected fun testInline(
+        query: String,
+        configuration: DokkaConfigurationImpl,
+        cleanupOutput: Boolean = true,
+        pluginOverrides: List<DokkaPlugin> = emptyList(),
+        loggerForTest: DokkaLogger = logger,
+        block: TestBuilder.() -> Unit
+    ) {
+        val testMethods = TestBuilder().apply(block).build()
+        val testDirPath = getTempDir(cleanupOutput).root.toPath()
+        val fileMap = query.toFileMap()
+        fileMap.materializeFiles(testDirPath.toAbsolutePath())
+        if (!cleanupOutput)
+            loggerForTest.info("Output generated under: ${testDirPath.toAbsolutePath()}")
+        val newConfiguration = configuration.copy(
+            outputDir = testDirPath.toFile(),
+            sourceSets = configuration.sourceSets.map { sourceSet ->
+                sourceSet.copy(
+                    sourceRoots = sourceSet.sourceRoots.map { file ->
+                        testDirPath.toFile().resolve(file)
+                    }.toSet(),
+                    suppressedFiles = sourceSet.suppressedFiles.map { file ->
+                        testDirPath.toFile().resolve(file)
+                    }.toSet(),
+                    sourceLinks = sourceSet.sourceLinks.map { link ->
+                        link.copy(
+                            localDirectory = testDirPath.toFile().resolve(link.localDirectory).canonicalPath
+                        )
+                    }.toSet()
+                )
+            }
+        )
+        DokkaTestGenerator(
+            newConfiguration,
+            loggerForTest,
+            testMethods,
+            pluginOverrides
+        ).generate()
+    }
+
+
+    private fun String.toFileMap(): Map<String, String> {
+        return this.trimIndent().trimMargin()
+            .replace("\r\n", "\n")
+            .sliceAt(filePathRegex)
+            .filter { it.isNotEmpty() && it.isNotBlank() && "\n" in it }
+            .map { fileDeclaration -> fileDeclaration.trim() }
+            .map { fileDeclaration ->
+                val filePathAndContent = fileDeclaration.split("\n", limit = 2)
+                val filePath = filePathAndContent.first().removePrefix("/").trim()
+                val content = filePathAndContent.last().trim()
+                filePath to content
+            }
+            .toMap()
+    }
+
+    private fun String.sliceAt(regex: Regex): List<String> {
+        val matchesStartIndices = regex.findAll(this).toList().map { match -> match.range.first }
+        return sequence {
+            yield(0)
+            yieldAll(matchesStartIndices)
+            yield(this@sliceAt.length)
+        }
+            .zipWithNext { startIndex: Int, endIndex: Int -> substring(startIndex, endIndex) }
+            .toList()
+            .also { slices ->
+                /* Post-condition verifying that no character is lost */
+                check(slices.sumBy { it.length } == length)
+            }
+    }
+
+    private fun Map<String, String>.materializeFiles(
+        root: Path = Paths.get("."),
+        charset: Charset = Charset.forName("utf-8")
+    ) = this.map { (path, content) ->
+        val file = root.resolve(path)
+        Files.createDirectories(file.parent)
+        Files.write(file, content.toByteArray(charset))
+    }
+
+    private fun getTempDir(cleanupOutput: Boolean) = if (cleanupOutput) {
+        TemporaryFolder().apply { create() }
+    } else {
+        object : TemporaryFolder() {
+            override fun after() {}
+        }.apply { create() }
+    }
+
+    protected class TestBuilder {
+        var pluginsSetupStage: (DokkaContext) -> Unit = {}
+        var documentablesCreationStage: (List<DModule>) -> Unit = {}
+        var documentablesFirstTransformationStep: (List<DModule>) -> Unit = {}
+        var documentablesMergingStage: (DModule) -> Unit = {}
+        var documentablesTransformationStage: (DModule) -> Unit = {}
+        var pagesGenerationStage: (RootPageNode) -> Unit = {}
+        var pagesTransformationStage: (RootPageNode) -> Unit = {}
+        var renderingStage: (RootPageNode, DokkaContext) -> Unit = { a, b -> }
+
+        @PublishedApi
+        internal fun build() = TestMethods(
+            pluginsSetupStage,
+            documentablesCreationStage,
+            documentablesFirstTransformationStep,
+            documentablesMergingStage,
+            documentablesTransformationStage,
+            pagesGenerationStage,
+            pagesTransformationStage,
+            renderingStage
+        )
+    }
+
+    protected fun dokkaConfiguration(block: DokkaConfigurationBuilder.() -> Unit): DokkaConfigurationImpl =
+        DokkaConfigurationBuilder().apply(block).build()
+
+    @DslMarker
+    protected annotation class DokkaConfigurationDsl
+
+    @DokkaConfigurationDsl
+    protected class DokkaConfigurationBuilder {
+        var outputDir: String = "out"
+        var format: String = "html"
+        var offlineMode: Boolean = false
+        var cacheRoot: String? = null
+        var pluginsClasspath: List<File> = emptyList()
+        var pluginsConfigurations: Map<String, String> = emptyMap()
+        var failOnWarning: Boolean = false
+        private val sourceSets = mutableListOf<DokkaSourceSetImpl>()
+        fun build() = DokkaConfigurationImpl(
+            outputDir = File(outputDir),
+            cacheRoot = cacheRoot?.let(::File),
+            offlineMode = offlineMode,
+            sourceSets = sourceSets.toList(),
+            pluginsClasspath = pluginsClasspath,
+            pluginsConfiguration = pluginsConfigurations,
+            modules = emptyList(),
+            failOnWarning = failOnWarning
+        )
+
+        fun sourceSets(block: SourceSetsBuilder.() -> Unit) {
+            sourceSets.addAll(SourceSetsBuilder().apply(block))
+        }
+    }
+
+    @DokkaConfigurationDsl
+    protected class SourceSetsBuilder : ArrayList<DokkaSourceSetImpl>() {
+        fun sourceSet(block: DokkaSourceSetBuilder.() -> Unit): DokkaSourceSet =
+            DokkaSourceSetBuilder().apply(block).build().apply(::add)
+    }
+
+    @DokkaConfigurationDsl
+    protected class DokkaSourceSetBuilder(
+        var moduleName: String = "root",
+        var moduleDisplayName: String? = null,
+        var name: String = "main",
+        var displayName: String = "JVM",
+        var classpath: List<String> = emptyList(),
+        var sourceRoots: List<String> = emptyList(),
+        var dependentSourceSets: Set<DokkaSourceSetID> = emptySet(),
+        var samples: List<String> = emptyList(),
+        var includes: List<String> = emptyList(),
+        var includeNonPublic: Boolean = false,
+        var includeRootPackage: Boolean = true,
+        var reportUndocumented: Boolean = false,
+        var skipEmptyPackages: Boolean = false,
+        var skipDeprecated: Boolean = false,
+        var jdkVersion: Int = 8,
+        var languageVersion: String? = null,
+        var apiVersion: String? = null,
+        var noStdlibLink: Boolean = false,
+        var noJdkLink: Boolean = false,
+        var suppressedFiles: List<String> = emptyList(),
+        var analysisPlatform: String = "jvm",
+        var perPackageOptions: List<PackageOptionsImpl> = emptyList(),
+        var externalDocumentationLinks: List<ExternalDocumentationLinkImpl> = emptyList(),
+        var sourceLinks: List<SourceLinkDefinitionImpl> = emptyList()
+    ) {
+        fun build() = DokkaSourceSetImpl(
+            moduleDisplayName = moduleDisplayName ?: moduleName,
+            displayName = displayName,
+            sourceSetID = DokkaSourceSetID(moduleName, name),
+            classpath = classpath.map(::File),
+            sourceRoots = sourceRoots.map(::File).toSet(),
+            dependentSourceSets = dependentSourceSets,
+            samples = samples.map(::File).toSet(),
+            includes = includes.map(::File).toSet(),
+            includeNonPublic = includeNonPublic,
+            reportUndocumented = reportUndocumented,
+            skipEmptyPackages = skipEmptyPackages,
+            skipDeprecated = skipDeprecated,
+            jdkVersion = jdkVersion,
+            sourceLinks = sourceLinks.toSet(),
+            perPackageOptions = perPackageOptions.toList(),
+            externalDocumentationLinks = externalDocumentationLinks.toSet(),
+            languageVersion = languageVersion,
+            apiVersion = apiVersion,
+            noStdlibLink = noStdlibLink,
+            noJdkLink = noJdkLink,
+            suppressedFiles = suppressedFiles.map(::File).toSet(),
+            analysisPlatform = Platform.fromString(analysisPlatform)
+        )
+    }
+
+    protected val jvmStdlibPath: String? by lazy {
+        PathManager.getResourceRoot(Strictfp::class.java, "/kotlin/jvm/Strictfp.class")
+    }
+
+    protected val jsStdlibPath: String? by lazy {
+        PathManager.getResourceRoot(Any::class.java, "/kotlin/jquery")
+    }
+
+    protected val commonStdlibPath: String? by lazy {
+        // TODO: feels hacky, find a better way to do it
+        ClassLoader.getSystemResource("kotlin/UInt.kotlin_metadata")
+            ?.file
+            ?.replace("file:", "")
+            ?.replaceAfter(".jar", "")
+    }
+
+    protected val stdlibExternalDocumentationLink = ExternalDocumentationLinkImpl(
+        URL("https://kotlinlang.org/api/latest/jvm/stdlib/"),
+        URL("https://kotlinlang.org/api/latest/jvm/stdlib/package-list")
+    )
+
+    companion object {
+        private val filePathRegex = Regex("""[\n^](/\w+)+(\.\w+)?\s*\n""")
+    }
+}
+
+data class TestMethods(
+    val pluginsSetupStage: (DokkaContext) -> Unit,
+    val documentablesCreationStage: (List<DModule>) -> Unit,
+    val documentablesFirstTransformationStep: (List<DModule>) -> Unit,
+    val documentablesMergingStage: (DModule) -> Unit,
+    val documentablesTransformationStage: (DModule) -> Unit,
+    val pagesGenerationStage: (RootPageNode) -> Unit,
+    val pagesTransformationStage: (RootPageNode) -> Unit,
+    val renderingStage: (RootPageNode, DokkaContext) -> Unit
+)