Implement analysis test API #3184
Conversation
IgnatBeresnev
force-pushed
the
analysis-test-api
branch
from
3365459 to
b6a6ca8
Compare
| /** | ||
| * Should NOT be used outside of Dokka itself, there are no guarantees | ||
| * this class will continue to exist in future releases. | ||
| * | ||
| * This class resides in core because it is a non-trivial implementation | ||
| * for a core extension [CoreExtensions.documentableMerger], which is needed | ||
| * in modules that only have access to `dokka-core`. | ||
| */ | ||
| @InternalDokkaApi | ||
| public class DefaultDocumentableMerger(context: DokkaContext) : DocumentableMerger { |
There was a problem hiding this comment.
I moved this class to core since I need it for bootstrapping analysis tests.
Don't really understand why we need the DocumentableMerger extension point at all - I find it very difficult to believe someone will need to re-implement it or will even understand how it works (I don't). Should return to it some time in the future when we revisit all core extensions.
| moduleName = "java-module-name-for-unit-test" | ||
| } | ||
| javaFile(pathFromSrc = "org/jetbrains/dokka/test/java/Bar.java") { | ||
| +""" |
There was a problem hiding this comment.
Are we going to remove the plus operator for strings?
There was a problem hiding this comment.
I understand it might lead to some issues down the road, but I couldn't think of any substantial problems to justify changing it as our use case is rather simple.
This API is not public, so we'll have a chance to change it quickly if it's ever published externally.
...is-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/jvm/java/JavaAnalysisTest.kt
Outdated
Show resolved
Hide resolved
...tlin-api/src/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/TestProjectFactory.kt
Outdated
Show resolved
Hide resolved
| verifyFilePathStartsWithSlash("additionalSourceRoots", it) | ||
| } | ||
| additionalClasspath.forEach { | ||
| verifyFileExtension("additionalClasspath", it, ".jar") // should it include .klib? |
There was a problem hiding this comment.
It can be a list of JARs, KLIBs, folders with .class files.
There was a problem hiding this comment.
I'll fix the comment 👍. Let's change the actual check once we have the first related tests and are sure that they work.
There was a problem hiding this comment.
Have you checked that it works with JVM stdlib: kotlin/jvm/Strictfp.class?
There was a problem hiding this comment.
Oh, sorry, missed the reply.
Not sure what you mean exactly. The only place where kotlin/jvm/Strictfp.class is used is to find the .jar file that contains it - passing the .jar file here works, yeah. But for now there's no need and there are no tests that pass individual class files
There was a problem hiding this comment.
My bad. I thought jvmStdlibPath was an unpacked folder.
But for now there's no need and there are no tests that pass individual class files
Indeed, the stdlib jar is only used in the classpath.
// this check can be extended to accept .klib, .class or other files
I'm not sure Dokka's analysis can work with individual .class files. But it should work with directories containing .class files, e.g. someProject/build/classes/.
| import kotlin.test.Test | ||
| import kotlin.test.assertEquals | ||
|
|
||
| class JavaAnalysisTest { |
There was a problem hiding this comment.
Strict explicit API mode does not work here, in tests. It should have public
There was a problem hiding this comment.
Explicit API is deliberately disabled in tests, it only makes sense for main sources
...rc/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
Outdated
Show resolved
Hide resolved
...rc/testFixtures/kotlin/org/jetbrains/dokka/analysis/test/api/analysis/TestProjectAnalyzer.kt
Outdated
Show resolved
Hide resolved
| /** | ||
| * The main logger used for running Dokka and analyzing projects. | ||
| * | ||
| * Changing the level to [LoggingLevel.DEBUG] can help with debugging faulty tests |
There was a problem hiding this comment.
How a user can change a logging level?
There was a problem hiding this comment.
At the moment, the only user is us (it's not public), so I thought we would just be able to change it temporarily in the source code.
But in #3195 I needed to assert some logging messages, so this logger became the default logger, and you can just pass your own one to the parse function.
| * as the input user project. This allows us to simulate Dokka's behavior and results | ||
| * on a made-up project as if it were real and run via the CLI runner. | ||
| * | ||
| * Executes only a limited number of steps and uses a small subset of [CoreExtensions] |
There was a problem hiding this comment.
Is it used only one extension point CoreExtensions.sourceToDocumentableTranslator?
There was a problem hiding this comment.
For now I think yes. It would call the documentable merger extension point, but the only implementation is registered in dokka-base, so it's just created as a plain object for every invocation
| * | ||
| * Works only with single-module projects, where the source code of this project | ||
| * 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. |
There was a problem hiding this comment.
Currently, it works only with Kotlin/JVM, not KMP?
There was a problem hiding this comment.
At the moment there's API to test JVM projects only, but it doesn't mean it's not going to work for KMP projects :) Once KMP test project API is added - hopefully it'll just work, I don't see a reason why it shouldn't. Even if it doesn't - the KDoc clearly states that it must, so it will need to be adapted to support it
Adds convenient API for testing Kotlin analysis implementations.