Add an option to generate summaries using custom JavaDoc tags #565

UnitTestBot · amandelpie · Aug 24, 2022 · Jul 22, 2022 · Jul 25, 2022 · Jul 26, 2022
commit 760594ff5cc05c1224550c02ff92adba27f88e19
diff --git a/utbot-framework-api/src/main/kotlin/org/utbot/framework/UtSettings.kt b/utbot-framework-api/src/main/kotlin/org/utbot/framework/UtSettings.kt
@@ -269,7 +269,7 @@ object UtSettings {
     /**
      * Set to true to start fuzzing if symbolic execution haven't return anything
      */
-    var useFuzzing: Boolean by getBooleanProperty(true)
+    var useFuzzing: Boolean by getBooleanProperty(false)
 
     /**
      * Set the total attempts to improve coverage by fuzzer.

diff --git a/...framework/src/main/kotlin/org/utbot/framework/codegen/model/visitor/CgAbstractRenderer.kt b/...framework/src/main/kotlin/org/utbot/framework/codegen/model/visitor/CgAbstractRenderer.kt
@@ -309,10 +309,7 @@ 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: CgDocCodeStmt) {
         if (element.isEmpty()) return

diff --git a/...-intellij/src/main/kotlin/org/utbot/intellij/plugin/javadoc/UtCustomJavaDocTagProvider.kt b/...-intellij/src/main/kotlin/org/utbot/intellij/plugin/javadoc/UtCustomJavaDocTagProvider.kt
@@ -19,6 +19,7 @@ class UtCustomJavaDocTagProvider : CustomJavadocTagProvider {
             UtCustomTag.ActualResult,
             UtCustomTag.Executes,
             UtCustomTag.Invokes,
+            UtCustomTag.Iterates,
             UtCustomTag.ReturnsFrom,
             UtCustomTag.ThrowsException,
         )
@@ -44,6 +45,7 @@ class UtCustomJavaDocTagProvider : CustomJavadocTagProvider {
         object ActualResult : UtCustomTag("utbot.actualResult", "Actual result")
         object Executes : UtCustomTag("utbot.executes", "Executes")
         object Invokes : UtCustomTag("utbot.invokes", "Invokes")
+        object Iterates : UtCustomTag("utbot.iterates", "Iterates")
         object ReturnsFrom : UtCustomTag("utbot.returnsFrom", "Returns from")
         object ThrowsException : UtCustomTag("utbot.throwsException", "Throws exception")
     }

diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/Summarization.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/Summarization.kt
@@ -5,6 +5,7 @@ import org.utbot.framework.UtSettings
 import org.utbot.framework.plugin.api.UtClusterInfo
 import org.utbot.framework.plugin.api.UtSymbolicExecution
 import org.utbot.framework.plugin.api.UtExecutionCluster
+import org.utbot.framework.plugin.api.UtExecutionCreator
 import org.utbot.framework.plugin.api.UtMethodTestSet
 import org.utbot.instrumentation.instrumentation.instrumenter.Instrumenter
 import org.utbot.summary.SummarySentenceConstants.NEW_LINE
@@ -28,6 +29,8 @@ import org.utbot.fuzzer.FuzzedValue
 import org.utbot.fuzzer.UtFuzzedExecution
 import org.utbot.summary.fuzzer.names.MethodBasedNameSuggester
 import org.utbot.summary.fuzzer.names.ModelBasedNameSuggester
+import org.utbot.summary.UtSummarySettings.USE_CUSTOM_JAVADOC_TAGS
+import org.utbot.summary.comment.CustomJavaDocCommentBuilder
 import soot.SootMethod
 
 private val logger = KotlinLogging.logger {}
@@ -154,7 +157,10 @@ class Summarization(val sourceFile: File?, val invokeDescriptions: List<InvokeDe
                 }
 
                 for (traceTags in clusterTraceTags.traceTags) {
-                    if (GENERATE_COMMENTS) {
+                    if (GENERATE_COMMENTS && USE_CUSTOM_JAVADOC_TAGS) {
+                        traceTags.execution.summary =
+                            CustomJavaDocCommentBuilder(traceTags, sootToAST).buildDocStatements(methodUnderTest)
+                    } else if (GENERATE_COMMENTS) {
                         traceTags.execution.summary =
                             SimpleCommentBuilder(traceTags, sootToAST).buildDocStmts(methodUnderTest)
                     }

diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/UtSummarySettings.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/UtSummarySettings.kt
@@ -11,6 +11,11 @@ object UtSummarySettings {
      */
     var GENERATE_CLUSTER_COMMENTS = true
 
+    /**
+     * Generate summaries using plugin's custom JavaDoc tags.
+     */
+    var USE_CUSTOM_JAVADOC_TAGS = true
+
     /**
      * If True names for tests will be generated
      */

diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/comment/CustomJavaDocComment.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/comment/CustomJavaDocComment.kt
@@ -0,0 +1,16 @@
+package org.utbot.summary.comment
+
+/**
+ * Represents a set of plugin's custom JavaDoc tags.
+ */
+data class CustomJavaDocComment(
+    val classUnderTest: String,
+    val methodUnderTest: String,
+    val expectedResult: String?,
+    val actualResult: String?,
+    var executes: String?,
+    var invokes: String?,
+    var iterates: String?,
+    var returnsFrom: String?,
+    val throwsException: String?
+)
diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/comment/CustomJavaDocCommentBuilder.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/comment/CustomJavaDocCommentBuilder.kt
@@ -0,0 +1,93 @@
+package org.utbot.summary.comment
+
+import org.utbot.framework.plugin.api.DocPreTagStatement
+import org.utbot.framework.plugin.api.DocRegularStmt
+import org.utbot.framework.plugin.api.DocStatement
+import org.utbot.framework.plugin.api.exceptionOrNull
+import org.utbot.summary.ast.JimpleToASTMap
+import org.utbot.summary.tag.TraceTagWithoutExecution
+import soot.SootMethod
+
+//TODO: polish code
+class CustomJavaDocCommentBuilder(
+    traceTag: TraceTagWithoutExecution,
+    sootToAST: MutableMap<SootMethod, JimpleToASTMap>
+) : SimpleCommentBuilder(traceTag, sootToAST, stringTemplates = StringsTemplatesPlural()) {
+
+    /**
+     * Collects statements for final JavaDoc comment.
+     */
+    fun buildDocStatements(method: SootMethod): List<DocStatement> {
+        val comment: CustomJavaDocComment = buildCustomJavaDocComment(method)
+        val docStatementList = mutableListOf<DocStatement>()
+
+        docStatementList += DocRegularStmt("@utbot.classUnderTest ${comment.classUnderTest}\n")
+        docStatementList += DocRegularStmt("@utbot.methodUnderTest ${comment.methodUnderTest}\n")
+        if (comment.expectedResult != null)
+            docStatementList += DocRegularStmt("@utbot.expectedResult ${comment.expectedResult}\n")
+        if (comment.actualResult != null)
+            docStatementList += DocRegularStmt("@utbot.actualResult ${comment.actualResult}\n")
+        if (comment.executes != null)
+            docStatementList += DocRegularStmt("@utbot.executes ${comment.executes}\n")
+        if (comment.invokes != null)
+            docStatementList += DocRegularStmt("@utbot.invokes ${comment.invokes}\n")
+        if (comment.iterates != null)
+            docStatementList += DocRegularStmt("@utbot.iterates ${comment.iterates}\n")
+        if (comment.returnsFrom != null)
+            docStatementList += DocRegularStmt("@utbot.returnsFrom ${comment.returnsFrom}\n")
+        if (comment.throwsException != null)
+            docStatementList += DocRegularStmt("@utbot.throwsException ${comment.throwsException}")
+
+        return listOf<DocStatement>(DocPreTagStatement(docStatementList))
+    }
+
+    private fun buildCustomJavaDocComment(currentMethod: SootMethod): CustomJavaDocComment {
+        val methodReference =
+            getMethodReference(currentMethod.declaringClass.name, currentMethod.name, currentMethod.parameterTypes)
+        val classReference = getClassReference(currentMethod.declaringClass.javaStyleName)
+
+        val thrownException = traceTag.result.exceptionOrNull()
+        val exceptionThrow: String? = if (thrownException == null) {
+            traceTag.result.exceptionOrNull()?.let { it::class.qualifiedName }
+        } else {
+            val exceptionName = thrownException.javaClass.simpleName
+            val reason = findExceptionReason(currentMethod, thrownException)
+            "{@link $exceptionName} $reason"
+        }
+
+        val customJavaDocComment = CustomJavaDocComment(
+            classUnderTest = classReference,
+            methodUnderTest = methodReference,
+            expectedResult = null,
+            actualResult = null,
+            executes = null,
+            invokes = null,
+            iterates = null,
+            returnsFrom = null,
+            throwsException = exceptionThrow
+        )
+
+        val rootSentenceBlock = SimpleSentenceBlock(stringTemplates = stringTemplates)
+
+        buildSentenceBlock(traceTag.rootStatementTag, rootSentenceBlock, currentMethod)
+
+        for (stmtDescription: StmtDescription in rootSentenceBlock.stmtTexts) {
+            when (stmtDescription.stmtType.name) {
+                "Invoke" -> {
+                    val info = stmtDescription.description
+                    customJavaDocComment.invokes = "{@code $info}"
+                }
+                "Return" -> {
+                    val info = stmtDescription.description
+                    customJavaDocComment.returnsFrom = "{@code $info}"
+                }
+                "Condition" -> {
+                    val info = stmtDescription.description
+                    customJavaDocComment.executes = "{@code $info}"
+                }
+            }
+        }
+
+        return customJavaDocComment
+    }
+}
diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/comment/SimpleClusterCommentBuilder.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/comment/SimpleClusterCommentBuilder.kt
@@ -63,7 +63,7 @@ class SimpleClusterCommentBuilder(
      * Builds sentence blocks as parent one,
      * but ignores few types of statementTag that are considered in SimpleCommentBuilder
      */
-    private fun buildSentenceBlock(
+    override fun buildSentenceBlock(
         statementTag: StatementTag?,
         sentenceBlock: SimpleSentenceBlock,
         currentMethod: SootMethod
@@ -93,7 +93,7 @@ class SimpleClusterCommentBuilder(
             sentenceInvoke.squashStmtText()
             if (!sentenceInvoke.isEmpty()) {
                 sentenceBlock.invokeSentenceBlock =
-                    Pair(invokeDescription(className, methodName, methodParameterTypes), sentenceInvoke)
+                    Pair(getMethodReference(className, methodName, methodParameterTypes), sentenceInvoke)
                 createNextBlock = true
                 invokeRegistered = true
             }

diff --git a/utbot-summary/src/main/kotlin/org/utbot/summary/comment/SimpleCommentBuilder.kt b/utbot-summary/src/main/kotlin/org/utbot/summary/comment/SimpleCommentBuilder.kt
@@ -62,22 +62,11 @@ open class SimpleCommentBuilder(
     }
 
     /**
-     * Creates List<DocStatement> from SimpleSentenceBlock
+     * Creates List<[DocStatement]> from [SimpleSentenceBlock].
      */
     open fun buildDocStmts(currentMethod: SootMethod): List<DocStatement> {
-        val root = SimpleSentenceBlock(stringTemplates = stringTemplates)
-
-        val thrownException = traceTag.result.exceptionOrNull()
-        if (thrownException == null) {
-            root.exceptionThrow = traceTag.result.exceptionOrNull()?.let { it::class.qualifiedName }
-        } else {
-            val exceptionName = thrownException.javaClass.simpleName
-            val reason = findExceptionReason(currentMethod, thrownException)
-            root.exceptionThrow = "$exceptionName $reason"
-        }
-        skippedIterations()
-        buildSentenceBlock(traceTag.rootStatementTag, root, currentMethod)
-        val docStmts = toDocStmts(root)
+        val sentenceBlock = buildSentenceBlock(currentMethod)
+        val docStmts = toDocStmts(sentenceBlock)
 
         if (docStmts.isEmpty()) {
             return listOf(DocRegularStmt(genWarnNotification())) //TODO SAT-1310
@@ -88,6 +77,22 @@ open class SimpleCommentBuilder(
         return listOf<DocStatement>(DocPreTagStatement(docStmts))
     }
 
+    private fun buildSentenceBlock(currentMethod: SootMethod): SimpleSentenceBlock {
+        val rootSentenceBlock = SimpleSentenceBlock(stringTemplates = stringTemplates)
+
+        val thrownException = traceTag.result.exceptionOrNull()
+        if (thrownException == null) {
+            rootSentenceBlock.exceptionThrow = traceTag.result.exceptionOrNull()?.let { it::class.qualifiedName }
+        } else {
+            val exceptionName = thrownException.javaClass.simpleName
+            val reason = findExceptionReason(currentMethod, thrownException)
+            rootSentenceBlock.exceptionThrow = "$exceptionName $reason"
+        }
+        skippedIterations()
+        buildSentenceBlock(traceTag.rootStatementTag, rootSentenceBlock, currentMethod)
+        return rootSentenceBlock
+    }
+
     protected fun genWarnNotification(): String = " " //why is it empty?
 
     /**
@@ -114,7 +119,7 @@ open class SimpleCommentBuilder(
         return stmts
     }
 
-    private fun findExceptionReason(currentMethod: SootMethod, thrownException: Throwable): String {
+    fun findExceptionReason(currentMethod: SootMethod, thrownException: Throwable): String {
         val path = traceTag.path
         if (path.isEmpty()) {
             if (thrownException is ConcreteExecutionFailureException) {
@@ -161,7 +166,7 @@ open class SimpleCommentBuilder(
     /**
      * Sentence blocks are built based on unique and partly unique statement tags.
      */
-    private fun buildSentenceBlock(
+    open fun buildSentenceBlock(
         statementTag: StatementTag?,
         sentenceBlock: SimpleSentenceBlock,
         currentMethod: SootMethod
@@ -191,7 +196,7 @@ open class SimpleCommentBuilder(
             sentenceInvoke.squashStmtText()
             if (!sentenceInvoke.isEmpty()) {
                 sentenceBlock.invokeSentenceBlock =
-                    Pair(invokeDescription(className, methodName, methodParameterTypes), sentenceInvoke)
+                    Pair(getMethodReference(className, methodName, methodParameterTypes), sentenceInvoke)
                 createNextBlock = true
                 invokeRegistered = true
             }
@@ -317,7 +322,7 @@ open class SimpleCommentBuilder(
             sentenceBlock.stmtTexts.add(
                 StmtDescription(
                     StmtType.Invoke,
-                    invokeDescription(className, methodName, methodParameterTypes),
+                    getMethodReference(className, methodName, methodParameterTypes),
                     frequency
                 )
             )
@@ -349,7 +354,7 @@ open class SimpleCommentBuilder(
      * In case when an enclosing class in nested, we need to replace '$' with '.'
      * to render the reference.
      */
-    fun invokeDescription(className: String, methodName: String, methodParameterTypes: List<Type>): String {
+    protected fun getMethodReference(className: String, methodName: String, methodParameterTypes: List<Type>): String {
         val prettyClassName: String = className.replace("$", ".")
 
         return if (methodParameterTypes.isEmpty()) {
@@ -360,6 +365,14 @@ open class SimpleCommentBuilder(
         }
     }
 
+    /**
+     * Returns a reference to the class.
+     * Replaces '$' with '.' in case a class is nested.
+     */
+    fun getClassReference(fullClasName: String): String {
+        return "{@link ${fullClasName.replace("$", ".")}}"
+    }
+
     protected fun buildIterationsBlock(
         iterations: List<StatementTag>,
         activatedStep: Step,