aboutsummaryrefslogtreecommitdiff
path: root/testApi
diff options
context:
space:
mode:
Diffstat (limited to 'testApi')
-rw-r--r--testApi/build.gradle.kts18
-rw-r--r--testApi/src/main/kotlin/testApi/context/MockContext.kt47
-rw-r--r--testApi/src/main/kotlin/testApi/logger/TestLogger.kt48
-rw-r--r--testApi/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt45
-rw-r--r--testApi/src/main/kotlin/testApi/testRunner/TestRunner.kt271
-rw-r--r--testApi/src/main/kotlin/testApi/utils/assertIsInstance.kt17
6 files changed, 446 insertions, 0 deletions
diff --git a/testApi/build.gradle.kts b/testApi/build.gradle.kts
new file mode 100644
index 00000000..fc882f44
--- /dev/null
+++ b/testApi/build.gradle.kts
@@ -0,0 +1,18 @@
+import org.jetbrains.registerDokkaArtifactPublication
+
+plugins {
+ `maven-publish`
+ id("com.jfrog.bintray")
+}
+
+dependencies {
+ api(project(":core"))
+ implementation(project(":kotlin-analysis"))
+ implementation("junit:junit:4.13") // TODO: remove dependency to junit
+ implementation(kotlin("stdlib"))
+ implementation(kotlin("reflect"))
+}
+
+registerDokkaArtifactPublication("dokkaTestApi") {
+ artifactId = "dokka-test-api"
+}
diff --git a/testApi/src/main/kotlin/testApi/context/MockContext.kt b/testApi/src/main/kotlin/testApi/context/MockContext.kt
new file mode 100644
index 00000000..97347695
--- /dev/null
+++ b/testApi/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/testApi/src/main/kotlin/testApi/logger/TestLogger.kt b/testApi/src/main/kotlin/testApi/logger/TestLogger.kt
new file mode 100644
index 00000000..1dbe4a48
--- /dev/null
+++ b/testApi/src/main/kotlin/testApi/logger/TestLogger.kt
@@ -0,0 +1,48 @@
+package 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)
+ }
+}
diff --git a/testApi/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt b/testApi/src/main/kotlin/testApi/testRunner/DokkaTestGenerator.kt
new file mode 100644
index 00000000..414919dc
--- /dev/null
+++ b/testApi/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/testApi/src/main/kotlin/testApi/testRunner/TestRunner.kt b/testApi/src/main/kotlin/testApi/testRunner/TestRunner.kt
new file mode 100644
index 00000000..9aae4b0c
--- /dev/null
+++ b/testApi/src/main/kotlin/testApi/testRunner/TestRunner.kt
@@ -0,0 +1,271 @@
+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.utilities.DokkaConsoleLogger
+import org.junit.rules.TemporaryFolder
+import testApi.logger.TestLogger
+import java.io.File
+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 var logger = 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.toPath().toAbsolutePath().toString()
+ )
+ DokkaTestGenerator(
+ newConfiguration,
+ logger,
+ testMethods,
+ pluginOverrides
+ ).generate()
+ }
+
+ protected fun testInline(
+ query: String,
+ configuration: DokkaConfigurationImpl,
+ cleanupOutput: Boolean = true,
+ pluginOverrides: List<DokkaPlugin> = emptyList(),
+ 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)
+ logger.info("Output generated under: ${testDirPath.toAbsolutePath()}")
+ val newConfiguration =
+ configuration.copy(
+ outputDir = testDirPath.toAbsolutePath().toString(),
+ sourceSets = configuration.sourceSets.map {
+ it.copy(sourceRoots = it.sourceRoots.map { it.copy(path = "${testDirPath.toAbsolutePath()}/${it.path}") })
+ }
+ )
+ DokkaTestGenerator(
+ newConfiguration,
+ logger,
+ 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 = outputDir,
+ cacheRoot = cacheRoot,
+ offlineMode = offlineMode,
+ sourceSets = sourceSets,
+ 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,
+ sourceRoots = sourceRoots.map { SourceRootImpl(it) },
+ dependentSourceSets = dependentSourceSets,
+ samples = samples,
+ includes = includes,
+ includeNonPublic = includeNonPublic,
+ includeRootPackage = includeRootPackage,
+ reportUndocumented = reportUndocumented,
+ skipEmptyPackages = skipEmptyPackages,
+ skipDeprecated = skipDeprecated,
+ jdkVersion = jdkVersion,
+ sourceLinks = sourceLinks,
+ perPackageOptions = perPackageOptions,
+ externalDocumentationLinks = externalDocumentationLinks,
+ languageVersion = languageVersion,
+ apiVersion = apiVersion,
+ noStdlibLink = noStdlibLink,
+ noJdkLink = noJdkLink,
+ suppressedFiles = suppressedFiles,
+ 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", "")
+ }
+
+ 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
+)
diff --git a/testApi/src/main/kotlin/testApi/utils/assertIsInstance.kt b/testApi/src/main/kotlin/testApi/utils/assertIsInstance.kt
new file mode 100644
index 00000000..279dbafa
--- /dev/null
+++ b/testApi/src/main/kotlin/testApi/utils/assertIsInstance.kt
@@ -0,0 +1,17 @@
+package testApi.utils
+
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.contract
+
+@OptIn(ExperimentalContracts::class)
+inline fun <reified T> assertIsInstance(obj: Any?): T {
+ contract {
+ returns() implies (obj is T)
+ }
+
+ if (obj is T) {
+ return obj
+ }
+
+ throw AssertionError("Expected instance of type ${T::class.qualifiedName} but found $obj")
+}
generated by cgit (git 2.46.0) at 2024-12-27 09:50:24 +0000