Stabilize Sample analysis API (#3195)

10 files changed, 181 insertions, 48 deletions

diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt
index 9c0fa936..e000bb69 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProject.kt
@@ -8,10 +8,13 @@ import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.analysis.test.api.analysis.TestAnalysisContext
 import org.jetbrains.dokka.analysis.test.api.analysis.TestAnalysisServices
 import org.jetbrains.dokka.analysis.test.api.analysis.TestProjectAnalyzer
+import org.jetbrains.dokka.analysis.test.api.analysis.defaultAnalysisLogger
 import org.jetbrains.dokka.analysis.test.api.configuration.BaseTestDokkaConfigurationBuilder
 import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration
+import org.jetbrains.dokka.analysis.test.api.util.CollectingDokkaConsoleLogger
 import org.jetbrains.dokka.analysis.test.api.util.withTempDirectory
 import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.utilities.DokkaLogger
 
 /**
  * Represents a virtual test project (as if it's user-defined) that will be used to run Dokka.
@@ -66,8 +69,11 @@ interface TestProject {
  *
  * val module: DModule = testProject.parse()
  * ```
+ *
+ * @param logger logger to be used for running Dokka and tests. Custom loggers like [CollectingDokkaConsoleLogger]
+ *               can be useful in verifying the behavior.
  */
-fun TestProject.parse(): DModule = TestProjectAnalyzer.parse(this)
+fun TestProject.parse(logger: DokkaLogger = defaultAnalysisLogger): DModule = TestProjectAnalyzer.parse(this, logger)
 
 /**
  * Runs Dokka on the given [TestProject] and provides not only the resulting documentable model,
@@ -88,10 +94,16 @@ fun TestProject.parse(): DModule = TestProjectAnalyzer.parse(this)
  *     val allPackageDocs: SourceSetDependent<DocumentationNode> = moduleAndPackageDocumentationReader.read(pckg)
  * }
  * ```
+ *
+ * @param logger logger to be used for running Dokka and tests. Custom loggers like [CollectingDokkaConsoleLogger]
+ *               can be useful in verifying the behavior.
  */
-fun TestProject.useServices(block: TestAnalysisServices.(context: TestAnalysisContext) -> Unit) {
+fun TestProject.useServices(
+    logger: DokkaLogger = defaultAnalysisLogger,
+    block: TestAnalysisServices.(context: TestAnalysisContext) -> Unit
+) {
     withTempDirectory { tempDirectory ->
-        val (services, context) = TestProjectAnalyzer.analyze(this, tempDirectory)
+        val (services, context) = TestProjectAnalyzer.analyze(this, tempDirectory, logger)
         services.block(context)
     }
 }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
index ab70bbd4..f729838d 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestAnalysisServices.kt
@@ -6,7 +6,7 @@ package org.jetbrains.dokka.analysis.test.api.analysis
 
 import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 import org.jetbrains.dokka.analysis.kotlin.internal.ModuleAndPackageDocumentationReader
-import org.jetbrains.dokka.analysis.kotlin.internal.SampleProviderFactory
+import org.jetbrains.dokka.analysis.kotlin.sample.SampleAnalysisEnvironmentCreator
 
 /**
  * Services exposed in [KotlinAnalysisPlugin] that are ready to be used.
@@ -15,6 +15,6 @@ import org.jetbrains.dokka.analysis.kotlin.internal.SampleProviderFactory
  * It is analogous to calling `context.plugin<KotlinAnalysisPlugin>().querySingle { serviceName }`.
  */
 class TestAnalysisServices(
-    val sampleProviderFactory: SampleProviderFactory,
+    val sampleAnalysisEnvironmentCreator: SampleAnalysisEnvironmentCreator,
     val moduleAndPackageDocumentationReader: ModuleAndPackageDocumentationReader
 )
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
index 1668b53f..674c6d47 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
@@ -6,6 +6,7 @@ package org.jetbrains.dokka.analysis.test.api.analysis
 
 import org.jetbrains.dokka.CoreExtensions
 import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.analysis.kotlin.KotlinAnalysisPlugin
 import org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin
 import org.jetbrains.dokka.analysis.test.api.TestDataFile
 import org.jetbrains.dokka.analysis.test.api.TestProject
@@ -21,16 +22,14 @@ import org.jetbrains.dokka.transformers.documentation.DefaultDocumentableMerger
 import org.jetbrains.dokka.transformers.documentation.DocumentableMerger
 import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator
 import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
 import org.jetbrains.dokka.utilities.LoggingLevel
 import java.io.File
 
 /**
- * The main logger used for running Dokka and analyzing projects.
- *
- * Changing the level to [LoggingLevel.DEBUG] can help with debugging faulty tests
- * or tricky corner cases.
+ * The default logger used for running Dokka and analyzing projects.
  */
-val analysisLogger = DokkaConsoleLogger(minLevel = LoggingLevel.INFO)
+val defaultAnalysisLogger = DokkaConsoleLogger(minLevel = LoggingLevel.DEBUG)
 
 /**
  * Analyzer of the test projects, it is essentially a very simple Dokka runner.
@@ -47,7 +46,7 @@ val analysisLogger = DokkaConsoleLogger(minLevel = LoggingLevel.INFO)
  * resides in the root `src` directory. Works with multiple source sets and targets,
  * so both simple Kotlin/JVM and more complicated Kotlin Multiplatform project must work.
  */
-object TestProjectAnalyzer {
+internal object TestProjectAnalyzer {
 
     /**
      * A quick way to analyze a [TestProject], for cases when only the documentable
@@ -58,11 +57,11 @@ object TestProjectAnalyzer {
      *
      * @see [TestProject.parse] for a user-friendly way to call it
      */
-    fun parse(testProject: TestProject): DModule {
+    fun parse(testProject: TestProject, logger: DokkaLogger): DModule {
         // since we only need documentables, we can delete the input test files right away
-        return withTempDirectory(analysisLogger) { tempDirectory ->
-            val (_, context) = testProject.initialize(outputDirectory = tempDirectory)
-            generateDocumentableModel(context)
+        return withTempDirectory(logger) { tempDirectory ->
+            val (_, context) = testProject.initialize(outputDirectory = tempDirectory, logger)
+            generateDocumentableModel(context, logger)
         }
     }
 
@@ -80,14 +79,15 @@ object TestProjectAnalyzer {
      */
     fun analyze(
         testProject: TestProject,
-        persistentDirectory: File
+        persistentDirectory: File,
+        logger: DokkaLogger
     ): Pair<TestAnalysisServices, TestAnalysisContext> {
-        val (dokkaConfiguration, dokkaContext) = testProject.initialize(outputDirectory = persistentDirectory)
-        val analysisServices = createTestAnalysisServices(dokkaContext)
+        val (dokkaConfiguration, dokkaContext) = testProject.initialize(outputDirectory = persistentDirectory, logger)
+        val analysisServices = createTestAnalysisServices(dokkaContext, logger)
         val testAnalysisContext = TestAnalysisContext(
             context = dokkaContext,
             configuration = dokkaConfiguration,
-            module = generateDocumentableModel(dokkaContext)
+            module = generateDocumentableModel(dokkaContext, logger)
         )
         return analysisServices to testAnalysisContext
     }
@@ -96,28 +96,31 @@ object TestProjectAnalyzer {
      * Prepares this [TestProject] for analysis by creating
      * the test files, setting up context and configuration.
      */
-    private fun TestProject.initialize(outputDirectory: File): Pair<DokkaConfiguration, DokkaContext> {
-        analysisLogger.progress("Initializing and verifying project $this")
+    private fun TestProject.initialize(
+        outputDirectory: File,
+        logger: DokkaLogger
+    ): Pair<DokkaConfiguration, DokkaContext> {
+        logger.progress("Initializing and verifying project $this")
         this.verify()
         require(outputDirectory.isDirectory) {
             "outputDirectory has to exist and be a directory: $outputDirectory"
         }
-        this.initializeTestFiles(relativeToDir = outputDirectory)
+        this.initializeTestFiles(relativeToDir = outputDirectory, logger)
 
-        analysisLogger.progress("Creating configuration and context")
+        logger.progress("Creating configuration and context")
         val testDokkaConfiguration = this.getConfiguration()
         val dokkaConfiguration = testDokkaConfiguration.toDokkaConfiguration(projectDir = outputDirectory).also {
             it.verify()
         }
-        return dokkaConfiguration to createContext(dokkaConfiguration)
+        return dokkaConfiguration to createContext(dokkaConfiguration, logger)
     }
 
     /**
      * Takes the virtual [TestDataFile] of this [TestProject] and creates
      * the real files relative to the [relativeToDir] param.
      */
-    private fun TestProject.initializeTestFiles(relativeToDir: File) {
-        analysisLogger.progress("Initializing test files relative to the \"$relativeToDir\" directory")
+    private fun TestProject.initializeTestFiles(relativeToDir: File, logger: DokkaLogger) {
+        logger.progress("Initializing test files relative to the \"$relativeToDir\" directory")
 
         this.getTestData().getFiles().forEach {
             val testDataFile = relativeToDir.resolve(it.pathFromProjectRoot.removePrefix("/"))
@@ -128,7 +131,7 @@ object TestProjectAnalyzer {
                 throw IllegalStateException("Unable to create dirs \"${testDataFile.parentFile}\"", e)
             }
 
-            analysisLogger.debug("Creating \"${testDataFile.absolutePath}\"")
+            logger.debug("Creating \"${testDataFile.absolutePath}\"")
             check(testDataFile.createNewFile()) {
                 "Unable to create a test file: ${testDataFile.absolutePath}"
             }
@@ -163,11 +166,11 @@ object TestProjectAnalyzer {
         }
     }
 
-    private fun createContext(dokkaConfiguration: DokkaConfiguration): DokkaContext {
-        analysisLogger.progress("Creating DokkaContext from test configuration")
+    private fun createContext(dokkaConfiguration: DokkaConfiguration, logger: DokkaLogger): DokkaContext {
+        logger.progress("Creating DokkaContext from test configuration")
         return DokkaContext.create(
             configuration = dokkaConfiguration,
-            logger = analysisLogger,
+            logger = logger,
             pluginOverrides = listOf()
         )
     }
@@ -176,12 +179,12 @@ object TestProjectAnalyzer {
      * Generates the documentable model by using all available [SourceToDocumentableTranslator] extensions,
      * and then merging all the results into a single [DModule] by calling [DocumentableMerger].
      */
-    private fun generateDocumentableModel(context: DokkaContext): DModule {
-        analysisLogger.progress("Generating the documentable model")
+    private fun generateDocumentableModel(context: DokkaContext, logger: DokkaLogger): DModule {
+        logger.progress("Generating the documentable model")
         val sourceSetModules = context
             .configuration
             .sourceSets
-            .map { sourceSet -> translateSources(sourceSet, context) }
+            .map { sourceSet -> translateSources(sourceSet, context, logger) }
             .flatten()
 
         if (sourceSetModules.isEmpty()) {
@@ -196,12 +199,16 @@ object TestProjectAnalyzer {
      * Translates input source files to the documentable model by using
      * all registered [SourceToDocumentableTranslator] core extensions.
      */
-    private fun translateSources(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext): List<DModule> {
+    private fun translateSources(
+        sourceSet: DokkaConfiguration.DokkaSourceSet,
+        context: DokkaContext,
+        logger: DokkaLogger
+    ): List<DModule> {
         val translators = context[CoreExtensions.sourceToDocumentableTranslator]
         require(translators.isNotEmpty()) {
             "Need at least one source to documentable translator to run tests, otherwise no data will be generated."
         }
-        analysisLogger.debug("Translating sources for ${sourceSet.sourceSetID}")
+        logger.debug("Translating sources for ${sourceSet.sourceSetID}")
         return translators.map { it.invoke(sourceSet, context) }
     }
 
@@ -212,12 +219,18 @@ object TestProjectAnalyzer {
      * The idea is to provide the users with ready-to-use services,
      * without them having to know how to query or configure them.
      */
-    private fun createTestAnalysisServices(context: DokkaContext): TestAnalysisServices {
-        analysisLogger.progress("Creating analysis services")
-        val internalPlugin = context.plugin<InternalKotlinAnalysisPlugin>()
+    private fun createTestAnalysisServices(
+        context: DokkaContext,
+        logger: DokkaLogger
+    ): TestAnalysisServices {
+        logger.progress("Creating analysis services")
+        val publicAnalysisPlugin = context.plugin<KotlinAnalysisPlugin>()
+        val internalAnalysisPlugin = context.plugin<InternalKotlinAnalysisPlugin>()
         return TestAnalysisServices(
-            sampleProviderFactory = internalPlugin.querySingle { sampleProviderFactory },
-            moduleAndPackageDocumentationReader = internalPlugin.querySingle { moduleAndPackageDocumentationReader }
+            sampleAnalysisEnvironmentCreator = publicAnalysisPlugin.querySingle { sampleAnalysisEnvironmentCreator },
+            moduleAndPackageDocumentationReader = internalAnalysisPlugin.querySingle {
+                moduleAndPackageDocumentationReader
+            }
         )
     }
 }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt
index 156fc4e4..baabeed7 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaConfigurationBuilder.kt
@@ -49,7 +49,7 @@ class JavaTestSourceSetBuilder : BaseTestDokkaSourceSetBuilder() {
         return TestDokkaSourceSet(
             analysisPlatform = Platform.jvm,
             displayName = "JavaJvmSourceSet",
-            sourceSetID = DokkaSourceSetID(scopeId = "project", sourceSetName = "java"),
+            sourceSetID = JavaTestProject.DEFAULT_SOURCE_SET_ID,
             dependentSourceSets = setOf(),
             sourceRoots = additionalSourceRoots + setOf(JavaTestProject.DEFAULT_SOURCE_ROOT),
             classpath = additionalClasspath, // TODO [beresnev] is kotlin jvm stdlib needed here?
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt
index 39f0f0f6..9ce85961 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/java/JavaTestProject.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.analysis.test.api.jvm.java
 
+import org.jetbrains.dokka.DokkaSourceSetID
 import org.jetbrains.dokka.analysis.test.api.TestData
 import org.jetbrains.dokka.analysis.test.api.TestDataFile
 import org.jetbrains.dokka.analysis.test.api.TestProject
@@ -67,7 +68,8 @@ class JavaTestProject : TestProject, JavaFileCreator, MdFileCreator {
                 ")"
     }
 
-    internal companion object {
-        internal const val DEFAULT_SOURCE_ROOT = "/src/main/java"
+    companion object {
+        const val DEFAULT_SOURCE_ROOT = "/src/main/java"
+        val DEFAULT_SOURCE_SET_ID = DokkaSourceSetID(scopeId = "project", sourceSetName = "java")
     }
 }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt
index e5424ead..79028056 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmConfigurationBuilder.kt
@@ -44,7 +44,7 @@ class KotlinJvmTestSourceSetBuilder : BaseTestDokkaSourceSetBuilder() {
         return TestDokkaSourceSet(
             analysisPlatform = Platform.jvm,
             displayName = "KotlinJvmSourceSet",
-            sourceSetID = DokkaSourceSetID(scopeId = "project", sourceSetName = "kotlin"),
+            sourceSetID = KotlinJvmTestProject.DEFAULT_SOURCE_SET_ID,
             dependentSourceSets = setOf(),
             sourceRoots = additionalSourceRoots + setOf(KotlinJvmTestProject.DEFAULT_SOURCE_ROOT),
             classpath = additionalClasspath + setOf(getKotlinJvmStdlibJarPath()),
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmTestProject.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmTestProject.kt
index 178a1dc3..d67e1321 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmTestProject.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/kotlin/KotlinJvmTestProject.kt
@@ -4,6 +4,7 @@
 
 package org.jetbrains.dokka.analysis.test.api.jvm.kotlin
 
+import org.jetbrains.dokka.DokkaSourceSetID
 import org.jetbrains.dokka.analysis.test.api.TestData
 import org.jetbrains.dokka.analysis.test.api.TestDataFile
 import org.jetbrains.dokka.analysis.test.api.TestProject
@@ -85,8 +86,9 @@ class KotlinJvmTestProject : TestProject, KtFileCreator, MdFileCreator, KotlinSa
                 ")"
     }
 
-    internal companion object {
-        internal const val DEFAULT_SOURCE_ROOT = "/src/main/kotlin"
+    companion object {
+        const val DEFAULT_SOURCE_ROOT = "/src/main/kotlin"
+        val DEFAULT_SOURCE_SET_ID = DokkaSourceSetID(scopeId = "project", sourceSetName = "kotlin")
     }
 }
 
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestProject.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestProject.kt
index 32b7ce0a..45ca53e2 100644
--- a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestProject.kt
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/jvm/mixed/MixedJvmTestProject.kt
@@ -10,6 +10,9 @@ import org.jetbrains.dokka.analysis.test.api.TestProject
 import org.jetbrains.dokka.analysis.test.api.configuration.TestDokkaConfiguration
 import org.jetbrains.dokka.analysis.test.api.jvm.java.JavaTestProject
 import org.jetbrains.dokka.analysis.test.api.jvm.kotlin.KotlinJvmTestProject
+import org.jetbrains.dokka.analysis.test.api.kotlin.sample.KotlinSampleFileCreator
+import org.jetbrains.dokka.analysis.test.api.kotlin.sample.KotlinSampleTestData
+import org.jetbrains.dokka.analysis.test.api.kotlin.sample.KotlinSampleTestDataFile
 import org.jetbrains.dokka.analysis.test.api.markdown.MarkdownTestData
 import org.jetbrains.dokka.analysis.test.api.markdown.MarkdownTestDataFile
 import org.jetbrains.dokka.analysis.test.api.markdown.MdFileCreator
@@ -20,13 +23,14 @@ import org.jetbrains.dokka.analysis.test.api.util.flatListOf
 /**
  * @see mixedJvmTestProject for an explanation and a convenient way to construct this project
  */
-class MixedJvmTestProject : TestProject, MdFileCreator {
+class MixedJvmTestProject : TestProject, MdFileCreator, KotlinSampleFileCreator {
 
     private val projectConfigurationBuilder = MixedJvmTestConfigurationBuilder()
 
     private val kotlinSourceDirectory = MixedJvmTestData(pathToSources = KotlinJvmTestProject.DEFAULT_SOURCE_ROOT)
     private val javaSourceDirectory = MixedJvmTestData(pathToSources = JavaTestProject.DEFAULT_SOURCE_ROOT)
     private val markdownTestData = MarkdownTestData()
+    private val kotlinSampleTestData = KotlinSampleTestData()
 
     @AnalysisTestDslMarker
     fun dokkaConfiguration(fillConfiguration: MixedJvmTestConfigurationBuilder.() -> Unit) {
@@ -48,6 +52,15 @@ class MixedJvmTestProject : TestProject, MdFileCreator {
         markdownTestData.mdFile(pathFromProjectRoot, fillFile)
     }
 
+    @AnalysisTestDslMarker
+    override fun sampleFile(
+        pathFromProjectRoot: String,
+        fqPackageName: String,
+        fillFile: KotlinSampleTestDataFile.() -> Unit
+    ) {
+        kotlinSampleTestData.sampleFile(pathFromProjectRoot, fqPackageName, fillFile)
+    }
+
     override fun verify() {
         projectConfigurationBuilder.verify()
     }
@@ -62,7 +75,8 @@ class MixedJvmTestProject : TestProject, MdFileCreator {
                 return flatListOf(
                     this@MixedJvmTestProject.kotlinSourceDirectory.getFiles(),
                     this@MixedJvmTestProject.javaSourceDirectory.getFiles(),
-                    this@MixedJvmTestProject.markdownTestData.getFiles()
+                    this@MixedJvmTestProject.markdownTestData.getFiles(),
+                    this@MixedJvmTestProject.kotlinSampleTestData.getFiles()
                 )
             }
         }
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/DokkaLoggerUtils.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/DokkaLoggerUtils.kt
new file mode 100644
index 00000000..87de4540
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/DokkaLoggerUtils.kt
@@ -0,0 +1,63 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.test.api.util
+
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
+import org.jetbrains.dokka.utilities.LoggingLevel
+
+/**
+ * Prints messages to the console according to the passed `consoleMinLevel` parameter,
+ * and collects **ALL** log messages, regarding of the set logging level.
+ *
+ * Useful if you need to verify that user-friendly log messages were emitted,
+ * in case they outline actionable problems or help solve a problem and are
+ * considered to be a vital part of this product.
+ *
+ * The collected messages can be retrieved by invoking [collectedLogMessages].
+ */
+class CollectingDokkaConsoleLogger(
+    consoleMinLoggingLevel: LoggingLevel = LoggingLevel.INFO
+) : DokkaLogger {
+
+    private val consoleLogger = DokkaConsoleLogger(consoleMinLoggingLevel)
+    private val _collectedLogMessages = mutableListOf<String>()
+
+    val collectedLogMessages: List<String> = _collectedLogMessages
+
+    override var warningsCount: Int
+        get() = consoleLogger.warningsCount
+        set(value) { consoleLogger.warningsCount = value }
+
+    override var errorsCount: Int
+        get() = consoleLogger.errorsCount
+        set(value) { consoleLogger.errorsCount = value }
+
+
+    override fun debug(message: String) {
+        _collectedLogMessages.add(message)
+        consoleLogger.debug(message)
+    }
+
+    override fun info(message: String) {
+        _collectedLogMessages.add(message)
+        consoleLogger.info(message)
+    }
+
+    override fun progress(message: String) {
+        _collectedLogMessages.add(message)
+        consoleLogger.progress(message)
+    }
+
+    override fun warn(message: String) {
+        _collectedLogMessages.add(message)
+        consoleLogger.warn(message)
+    }
+
+    override fun error(message: String) {
+        _collectedLogMessages.add(message)
+        consoleLogger.error(message)
+    }
+}
diff --git a/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/TestAnalysisApiUtils.kt b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/TestAnalysisApiUtils.kt
new file mode 100644
index 00000000..18a04ae5
--- /dev/null
+++ b/dokka-subprojects/analysis-kotlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/util/TestAnalysisApiUtils.kt
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.analysis.test.api.util
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaSourceSetID
+import org.jetbrains.dokka.analysis.test.api.analysis.TestAnalysisContext
+import org.jetbrains.dokka.analysis.test.api.jvm.java.JavaTestProject
+import org.jetbrains.dokka.analysis.test.api.jvm.kotlin.KotlinJvmTestProject
+
+/**
+ * @return the only existing source set or an exception
+ */
+fun TestAnalysisContext.singleSourceSet(): DokkaConfiguration.DokkaSourceSet {
+    return this.configuration.sourceSets.single()
+}
+
+fun TestAnalysisContext.defaultKotlinSourceSet() = findSourceSetById(KotlinJvmTestProject.DEFAULT_SOURCE_SET_ID)
+fun TestAnalysisContext.defaultJavaSourceSet() = findSourceSetById(JavaTestProject.DEFAULT_SOURCE_SET_ID)
+
+fun TestAnalysisContext.findSourceSetById(dokkaSourceSetID: DokkaSourceSetID): DokkaConfiguration.DokkaSourceSet {
+    return this.configuration.sourceSets.single {
+        it.sourceSetID == dokkaSourceSetID
+    }
+}