Introduce custom JavaDoc tags #565

utbot-framework-api/src/main/kotlin/org/utbot/framework/UtSettings.kt

@@ -183,6 +183,11 @@ object UtSettings {
  var testName by getBooleanProperty(true)
  var testDisplayName by getBooleanProperty(true)
 
+ /**
+ * Generate summaries using plugin's custom JavaDoc tags.
+ */
+ var useCustomJavaDocTags by getBooleanProperty(false)
+
  /**
  * Enable the machine learning module to generate summaries for methods under test.
  * True by default.

utbot-framework-api/src/main/kotlin/org/utbot/framework/plugin/api/Api.kt

@@ -1276,6 +1276,9 @@ class DocPreTagStatement(content: List<DocStatement>) : DocTagStatement(content)
  override fun hashCode(): Int = content.hashCode()
 }
 
+data class DocCustomTagStatement(val statements: List<DocStatement>) : DocTagStatement(statements) {
+ override fun toString(): String = content.joinToString(separator = "")
+}
 
 open class DocClassLinkStmt(val className: String) : DocStatement() {
  override fun toString(): String = className

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/model/tree/CgElement.kt

@@ -11,6 +11,7 @@ import org.utbot.framework.plugin.api.ClassId
 import org.utbot.framework.plugin.api.ConstructorId
 import org.utbot.framework.plugin.api.DocClassLinkStmt
 import org.utbot.framework.plugin.api.DocCodeStmt
+import org.utbot.framework.plugin.api.DocCustomTagStatement
 import org.utbot.framework.plugin.api.DocMethodLinkStmt
 import org.utbot.framework.plugin.api.DocPreTagStatement
 import org.utbot.framework.plugin.api.DocRegularStmt
@@ -52,6 +53,7 @@ interface CgElement {
  is CgMultilineComment -> visit(element)
  is CgDocumentationComment -> visit(element)
  is CgDocPreTagStatement -> visit(element)
+ is CgCustomTagStatement -> visit(element)
  is CgDocCodeStmt -> visit(element)
  is CgDocRegularStmt -> visit(element)
  is CgDocClassLinkStmt -> visit(element)
@@ -335,6 +337,11 @@ class CgDocPreTagStatement(content: List<CgDocStatement>) : CgDocTagStatement(co
  override fun hashCode(): Int = content.hashCode()
 }
 
+/**
+ * Represents a type for statements containing custom JavaDoc tags.
+ */
+data class CgCustomTagStatement(val statements: List<CgDocStatement>) : CgDocTagStatement(statements)
+
 class CgDocCodeStmt(val stmt: String) : CgDocStatement() {
  override fun isEmpty(): Boolean = stmt.isEmpty()
 
@@ -379,6 +386,10 @@ fun convertDocToCg(stmt: DocStatement): CgDocStatement {
  val stmts = stmt.content.map { convertDocToCg(it) }
  CgDocPreTagStatement(content = stmts)
  }
+ is DocCustomTagStatement -> {
+ val stmts = stmt.content.map { convertDocToCg(it) }
+ CgCustomTagStatement(statements = stmts)
+ }
  is DocRegularStmt -> CgDocRegularStmt(stmt = stmt.stmt)
  is DocClassLinkStmt -> CgDocClassLinkStmt(className = stmt.className)
  is DocMethodLinkStmt -> CgDocMethodLinkStmt(methodName = stmt.methodName, stmt = stmt.className)

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/model/visitor/CgAbstractRenderer.kt

@@ -16,6 +16,7 @@ import org.utbot.framework.codegen.model.tree.CgComment
 import org.utbot.framework.codegen.model.tree.CgCommentedAnnotation
 import org.utbot.framework.codegen.model.tree.CgComparison
 import org.utbot.framework.codegen.model.tree.CgContinueStatement
+import org.utbot.framework.codegen.model.tree.CgCustomTagStatement
 import org.utbot.framework.codegen.model.tree.CgDeclaration
 import org.utbot.framework.codegen.model.tree.CgDecrement
 import org.utbot.framework.codegen.model.tree.CgDoWhileLoop
@@ -309,11 +310,19 @@ internal abstract class CgAbstractRenderer(val context: CgContext, val printer:
  }
  override fun visit(element: CgDocPreTagStatement) {
  if (element.content.all { it.isEmpty() }) return
-
  println("<pre>")
  for (stmt in element.content) stmt.accept(this)
  println("</pre>")
  }
+
+ override fun visit(element: CgCustomTagStatement) {
+ if (element.statements.all { it.isEmpty() }) return
+
+ for (stmt in element.statements) {
+ stmt.accept(this)
+ }
+ }
+
  override fun visit(element: CgDocCodeStmt) {
  if (element.isEmpty()) return
 

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/model/visitor/CgVisitor.kt

@@ -22,6 +22,7 @@ import org.utbot.framework.codegen.model.tree.CgDocClassLinkStmt
 import org.utbot.framework.codegen.model.tree.CgDocCodeStmt
 import org.utbot.framework.codegen.model.tree.CgDocMethodLinkStmt
 import org.utbot.framework.codegen.model.tree.CgDocPreTagStatement
+import org.utbot.framework.codegen.model.tree.CgCustomTagStatement
 import org.utbot.framework.codegen.model.tree.CgDocRegularStmt
 import org.utbot.framework.codegen.model.tree.CgDocumentationComment
 import org.utbot.framework.codegen.model.tree.CgElement
@@ -122,6 +123,7 @@ interface CgVisitor<R> {
 
  // Comment statements
  fun visit(element: CgDocPreTagStatement): R
+ fun visit(element: CgCustomTagStatement): R
  fun visit(element: CgDocCodeStmt): R
  fun visit(element: CgDocRegularStmt): R
  fun visit(element: CgDocClassLinkStmt): R

utbot-framework/src/test/kotlin/org/utbot/examples/UtValueTestCaseChecker.kt

@@ -31,6 +31,7 @@ import org.utbot.framework.coverage.toAtLeast
 import org.utbot.framework.plugin.api.CodegenLanguage
 import org.utbot.framework.plugin.api.DocClassLinkStmt
 import org.utbot.framework.plugin.api.DocCodeStmt
+import org.utbot.framework.plugin.api.DocCustomTagStatement
 import org.utbot.framework.plugin.api.DocMethodLinkStmt
 import org.utbot.framework.plugin.api.DocPreTagStatement
 import org.utbot.framework.plugin.api.DocRegularStmt
@@ -2746,6 +2747,7 @@ private fun flattenDocStatements(summary: List<DocStatement>): List<DocStatement
  is DocMethodLinkStmt -> flatten.add(s)
  is DocCodeStmt -> flatten.add(s)
  is DocRegularStmt -> flatten.add(s)
+ is DocCustomTagStatement -> flatten.add(s)
  }
  }
  return flatten

utbot-intellij/src/main/kotlin/org/utbot/intellij/plugin/javadoc/UtCustomJavaDocTagProvider.kt

@@ -0,0 +1,32 @@
+package org.utbot.intellij.plugin.javadoc
+
+import com.intellij.psi.PsiElement
+import com.intellij.psi.PsiMethod
+import com.intellij.psi.PsiReference
+import com.intellij.psi.javadoc.CustomJavadocTagProvider
+import com.intellij.psi.javadoc.JavadocTagInfo
+import com.intellij.psi.javadoc.PsiDocTagValue
+import org.utbot.summary.comment.CustomJavaDocTag
+import org.utbot.summary.comment.CustomJavaDocTagProvider
+
+/**
+ * Provides plugin's custom JavaDoc tags to make test summaries structured.
+ */
+class UtCustomJavaDocTagProvider : CustomJavadocTagProvider {
+ override fun getSupportedTags(): List<UtCustomTagInfo> =
+ CustomJavaDocTagProvider().getPluginCustomTags().map { UtCustomTagInfo(it) }
+
+ class UtCustomTagInfo(private val tag: CustomJavaDocTag) : JavadocTagInfo {
+ override fun getName(): String = tag.name
+
+ fun getMessage(): String = tag.message
+
+ override fun isInline() = false
+
+ override fun checkTagValue(value: PsiDocTagValue?): String? = null
+
+ override fun getReference(value: PsiDocTagValue?): PsiReference? = null
+
+ override fun isValidInContext(element: PsiElement?): Boolean = element is PsiMethod
+ }
+}

utbot-intellij/src/main/kotlin/org/utbot/intellij/plugin/javadoc/UtDocumentationProvider.kt

@@ -0,0 +1,46 @@
+package org.utbot.intellij.plugin.javadoc
+
+import com.intellij.codeInsight.javadoc.JavaDocExternalFilter
+import com.intellij.codeInsight.javadoc.JavaDocInfoGeneratorFactory
+import com.intellij.lang.java.JavaDocumentationProvider
+import com.intellij.psi.PsiDocCommentBase
+import com.intellij.psi.PsiJavaDocumentedElement
+
+/**
+ * To render UtBot custom JavaDoc tags messages, we need to override basic behaviour of [JavaDocumentationProvider].
+ * The IJ platform knows only custom tag names, so we need to add their messages in rendered comments to make it look nice.
+ */
+class UtDocumentationProvider : JavaDocumentationProvider() {
+ override fun generateRenderedDoc(comment: PsiDocCommentBase): String? {
+ val target = comment.owner ?: comment
+
+ if (target !is PsiJavaDocumentedElement) {
+ return ""
+ }
+
+ val baseJavaDocInfoGenerator = JavaDocInfoGeneratorFactory.getBuilder(target.getProject())
+ .setPsiElement(target)
+ .setIsGenerationForRenderedDoc(true)
+ .create()
+
+ val finalDocContent = replaceTagNamesWithMessages(baseJavaDocInfoGenerator.generateRenderedDocInfo())
+
+ return JavaDocExternalFilter.filterInternalDocInfo(finalDocContent)
+ }
+
+ /**
+ * Replaces names of plugin's custom JavaDoc tags with their messages in the comment generated by the IJ platform.
+ * Example: utbot.MethodUnderTest -> Method under test.
+ */
+ private fun replaceTagNamesWithMessages(comment: String?) =
+ comment?.let {
+ val docTagProvider = UtCustomJavaDocTagProvider()
+ docTagProvider.supportedTags.fold(it) { result, tag ->
+ if (result.contains(tag.name)) {
+ result.replace(tag.name, "${tag.getMessage()}:")
+ } else {
+ result
+ }
+ }
+ } ?: ""
+}

utbot-intellij/src/main/resources/META-INF/plugin.xml

@@ -34,6 +34,9 @@
  <registryKey defaultValue="false" description="Enable editing Kotlin test files" key="kotlin.ultra.light.classes.empty.text.range"/>
  <postStartupActivity implementation="org.utbot.intellij.plugin.ui.GotItTooltipActivity"/>
  <projectModelModifier implementation="org.utbot.intellij.plugin.util.UtProjectModelModifier"/>
+ <!--Documentation-->
+ <customJavadocTagProvider implementation="org.utbot.intellij.plugin.javadoc.UtCustomJavaDocTagProvider"/>
+ <lang.documentationProvider language="JAVA" order="first" implementationClass="org.utbot.intellij.plugin.javadoc.UtDocumentationProvider"/>
  </extensions>
 
  <!-- Minimum and maximum build of IDE compatible with the plugin -->

utbot-summary-tests/src/test/kotlin/examples/CustomJavaDocTagsEnabler.kt

@@ -0,0 +1,25 @@
+package examples
+
+import org.junit.jupiter.api.extension.AfterEachCallback
+import org.junit.jupiter.api.extension.BeforeEachCallback
+import org.junit.jupiter.api.extension.ExtensionContext
+import org.utbot.framework.UtSettings
+
+/**
+ * Controls the value of useCustomJavaDocTags global variable.
+ *
+ * Should be used in summary tests containing custom JavaDoc tags.
+ * To use it, add an annotation @ExtendWith(CustomJavaDocTagsEnabler::class) under test class.
+ */
+class CustomJavaDocTagsEnabler(private val enable: Boolean = true) : BeforeEachCallback, AfterEachCallback {
+ private var previousValue = false
+
+ override fun beforeEach(context: ExtensionContext?) {
+ previousValue = UtSettings.useCustomJavaDocTags
+ UtSettings.useCustomJavaDocTags = enable
+ }
+
+ override fun afterEach(context: ExtensionContext?) {
+ UtSettings.useCustomJavaDocTags = previousValue
+ }
+}

utbot-summary-tests/src/test/kotlin/examples/controlflow/SummaryConditionsTest.kt

@@ -0,0 +1,54 @@
+package examples.controlflow
+
+import examples.CustomJavaDocTagsEnabler
+import examples.SummaryTestCaseGeneratorTest
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.utbot.examples.DoNotCalculate
+import org.utbot.examples.controlflow.Conditions
+import org.utbot.framework.plugin.api.MockStrategyApi
+
+@ExtendWith(CustomJavaDocTagsEnabler::class)
+class SummaryConditionsTest : SummaryTestCaseGeneratorTest(
+ Conditions::class
+) {
+ @Test
+ fun testSimpleCondition() {
+ val summary1 = "@utbot.classUnderTest {@link Conditions}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.controlflow.Conditions#simpleCondition(boolean)}\n" +
+ "@utbot.executesCondition {@code (condition): False}\n" +
+ "@utbot.returnsFrom {@code return 0;}"
+
+ val summary2 = "@utbot.classUnderTest {@link Conditions}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.controlflow.Conditions#simpleCondition(boolean)}\n" +
+ "@utbot.executesCondition {@code (condition): True}\n" +
+ "@utbot.returnsFrom {@code return 1;}"
+
+ val methodName1 = "testSimpleCondition_NotCondition"
+ val methodName2 = "testSimpleCondition_Condition"
+
+ val displayName1 = "condition : False -> return 0"
+ val displayName2 = "condition : True -> return 1"
+
+ val summaryKeys = listOf(
+ summary1,
+ summary2
+ )
+
+ val displayNames = listOf(
+ displayName1,
+ displayName2
+ )
+
+ val methodNames = listOf(
+ methodName1,
+ methodName2
+ )
+
+ val method = Conditions::simpleCondition
+ val mockStrategy = MockStrategyApi.NO_MOCKS
+ val coverage = DoNotCalculate
+
+ summaryCheck(method, mockStrategy, coverage, summaryKeys, methodNames, displayNames)
+ }
+}

utbot-summary-tests/src/test/kotlin/examples/exceptions/SummaryExceptionClusteringExamplesTest.kt

@@ -0,0 +1,77 @@
+package examples.exceptions
+
+import examples.CustomJavaDocTagsEnabler
+import examples.SummaryTestCaseGeneratorTest
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.utbot.examples.DoNotCalculate
+import org.utbot.examples.exceptions.ExceptionClusteringExamples
+import org.utbot.framework.plugin.api.MockStrategyApi
+
+@ExtendWith(CustomJavaDocTagsEnabler::class)
+class SummaryExceptionClusteringExamplesTest : SummaryTestCaseGeneratorTest(
+ ExceptionClusteringExamples::class
+) {
+ @Test
+ fun testDifferentExceptions() {
+ val summary1 = "@utbot.classUnderTest {@link ExceptionClusteringExamples}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.exceptions.ExceptionClusteringExamples#differentExceptions(int)}\n" +
+ "@utbot.executesCondition {@code (i == 0): True}\n" +
+ "@utbot.throwsException {@link java.lang.ArithmeticException} in: return 100 / i;"
+
+ val summary2 = "@utbot.classUnderTest {@link ExceptionClusteringExamples}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.exceptions.ExceptionClusteringExamples#differentExceptions(int)}\n" +
+ "@utbot.executesCondition {@code (i == 0): False},\n" +
+ "{@code (i == 1): True}\n" +
+ "@utbot.throwsException {@link org.utbot.examples.exceptions.MyCheckedException} after condition: i == 1"
+ val summary3 = "@utbot.classUnderTest {@link ExceptionClusteringExamples}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.exceptions.ExceptionClusteringExamples#differentExceptions(int)}\n" +
+ "@utbot.executesCondition {@code (i == 0): False},\n" +
+ "{@code (i == 1): False},\n" +
+ "{@code (i == 2): True}\n" +
+ "@utbot.throwsException {@link java.lang.IllegalArgumentException} after condition: i == 2"
+ val summary4 = "@utbot.classUnderTest {@link ExceptionClusteringExamples}\n" +
+ "@utbot.methodUnderTest {@link org.utbot.examples.exceptions.ExceptionClusteringExamples#differentExceptions(int)}\n" +
+ "@utbot.executesCondition {@code (i == 0): False},\n" +
+ "{@code (i == 1): False},\n" +
+ "{@code (i == 2): False}\n" +
+ "@utbot.returnsFrom {@code return i * 2;}\n"
+
+ val methodName1 = "testDifferentExceptions_IEqualsZero"
+ val methodName2 = "testDifferentExceptions_IEquals1"
+ val methodName3 = "testDifferentExceptions_IEquals2"
+ val methodName4 = "testDifferentExceptions_INotEquals2"
+
+ val displayName1 = "return 100 / i : True -> ThrowArithmeticException"
+ val displayName2 = "i == 1 -> ThrowMyCheckedException"
+ val displayName3 = "i == 2 -> ThrowIllegalArgumentException"
+ val displayName4 = "i == 0 : False -> return i * 2"
+
+ val summaryKeys = listOf(
+ summary1,
+ summary2,
+ summary3,
+ summary4
+ )
+
+ val displayNames = listOf(
+ displayName1,
+ displayName2,
+ displayName3,
+ displayName4
+ )
+
+ val methodNames = listOf(
+ methodName1,
+ methodName2,
+ methodName3,
+ methodName4
+ )
+
+ val method = ExceptionClusteringExamples::differentExceptions
+ val mockStrategy = MockStrategyApi.NO_MOCKS
+ val coverage = DoNotCalculate
+
+ summaryCheck(method, mockStrategy, coverage, summaryKeys, methodNames, displayNames)
+ }
+}