diff options
Diffstat (limited to 'core/test-api/src')
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 +) |