feat(descriptions-javadoc): various improvements (fixes #982, fixes #962

, via #981)

allure-descriptions-javadoc/build.gradle.kts

@@ -3,8 +3,6 @@ description = "Allure Javadoc Descriptions"
 val agent: Configuration by configurations.creating
 
 dependencies {
-    api("commons-io:commons-io")
-    api(project(":allure-java-commons"))
     testImplementation("com.google.testing.compile:compile-testing")
     testImplementation("io.github.glytching:junit-extensions")
     testImplementation("org.assertj:assertj-core")
@@ -18,9 +16,11 @@ dependencies {
 
 tasks.jar {
     manifest {
-        attributes(mapOf(
+        attributes(
+            mapOf(
                 "Automatic-Module-Name" to "io.qameta.allure.description"
-        ))
+            )
+        )
     }
 }
 

allure-descriptions-javadoc/src/main/java/io/qameta/allure/description/ClassNames.java

@@ -0,0 +1,28 @@
+/*
+ *  Copyright 2023 Qameta Software OÜ
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package io.qameta.allure.description;
+
+/**
+ * @author charlie (Dmitry Baev).
+ */
+final class ClassNames {
+
+    static final String DESCRIPTION_ANNOTATION = "io.qameta.allure.Description";
+
+    private ClassNames() {
+        throw new IllegalStateException("do not instance");
+    }
+}

allure-descriptions-javadoc/src/main/java/io/qameta/allure/description/JavaDocDescriptionsProcessor.java

@@ -15,8 +15,6 @@
  */
 package io.qameta.allure.description;
 
-import io.qameta.allure.Description;
-
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.Filer;
 import javax.annotation.processing.Messager;
@@ -28,22 +26,27 @@
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
+import javax.lang.model.util.ElementFilter;
 import javax.lang.model.util.Elements;
 import javax.tools.Diagnostic;
 import javax.tools.FileObject;
 import javax.tools.StandardLocation;
 import java.io.IOException;
 import java.io.Writer;
+import java.math.BigInteger;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.util.List;
 import java.util.Set;
 import java.util.stream.Collectors;
 
-import static io.qameta.allure.util.ResultsUtils.generateMethodSignatureHash;
+import static io.qameta.allure.description.ClassNames.DESCRIPTION_ANNOTATION;
 
 /**
  * @author Egor Borisov ehborisov@gmail.com
  */
-@SupportedAnnotationTypes("io.qameta.allure.Description")
+@SupportedAnnotationTypes(DESCRIPTION_ANNOTATION)
 public class JavaDocDescriptionsProcessor extends AbstractProcessor {
 
     private static final String ALLURE_DESCRIPTIONS_FOLDER = "META-INF/allureDescriptions/";
@@ -68,24 +71,29 @@ public SourceVersion getSupportedSourceVersion() {
 
     @Override
     public boolean process(final Set<? extends TypeElement> annotations, final RoundEnvironment env) {
-        final Set<? extends Element> elements = env.getElementsAnnotatedWith(Description.class);
-        elements.forEach(el -> {
-            if (!el.getAnnotation(Description.class).useJavaDoc()) {
+        final TypeElement typeElement = elementUtils.getTypeElement(DESCRIPTION_ANNOTATION);
+        final Set<? extends Element> elements = env.getElementsAnnotatedWith(typeElement);
+        final Set<ExecutableElement> methods = ElementFilter.methodsIn(elements);
+        methods.forEach(method -> {
+            final String rawDocs = elementUtils.getDocComment(method);
+
+            if (rawDocs == null) {
                 return;
             }
-            final String docs = elementUtils.getDocComment(el);
-            final List<String> typeParams = ((ExecutableElement) el).getParameters().stream()
-                    .map(this::methodParameterTypeMapper)
-                    .collect(Collectors.toList());
-            final String name = el.getSimpleName().toString();
-            if (docs == null) {
-                messager.printMessage(Diagnostic.Kind.WARNING,
-                        "Unable to create resource for method " + name + typeParams
-                                + " as it does not have a docs comment");
+
+            final String docs = rawDocs.trim();
+            if ("".equals(docs)) {
                 return;
             }
 
-            final String hash = generateMethodSignatureHash(el.getEnclosingElement().toString(), name, typeParams);
+            final String name = method.getSimpleName().toString();
+            final List<String> typeParams = method.getParameters().stream()
+                    .map(this::methodParameterTypeMapper)
+                    .collect(Collectors.toList());
+
+            final String hash = generateMethodSignatureHash(
+                    method.getEnclosingElement().toString(), name, typeParams
+            );
             try {
                 final FileObject file = filer.createResource(StandardLocation.CLASS_OUTPUT, "",
                         ALLURE_DESCRIPTIONS_FOLDER + hash);
@@ -105,4 +113,29 @@ private String methodParameterTypeMapper(final VariableElement parameter) {
         final Element typeElement = processingEnv.getTypeUtils().asElement(parameter.asType());
         return typeElement != null ? typeElement.toString() : parameter.asType().toString();
     }
+
+    private static String generateMethodSignatureHash(final String className,
+                                                      final String methodName,
+                                                      final List<String> parameterTypes) {
+        final MessageDigest md = getMd5Digest();
+        md.update(className.getBytes(StandardCharsets.UTF_8));
+        md.update(methodName.getBytes(StandardCharsets.UTF_8));
+        parameterTypes.stream()
+                .map(string -> string.getBytes(StandardCharsets.UTF_8))
+                .forEach(md::update);
+        final byte[] bytes = md.digest();
+        return bytesToHex(bytes);
+    }
+
+    private static MessageDigest getMd5Digest() {
+        try {
+            return MessageDigest.getInstance("MD5");
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException("Can not find hashing algorithm", e);
+        }
+    }
+
+    private static String bytesToHex(final byte[] bytes) {
+        return new BigInteger(1, bytes).toString(16);
+    }
 }

allure-descriptions-javadoc/src/test/java/io/qameta/allure/description/ProcessDescriptionsTest.java

@@ -37,7 +37,7 @@ class ProcessDescriptionsTest {
     void captureDescriptionTest() {
         final String expectedMethodSignatureHash = "4e7f896021ef2fce7c1deb7f5b9e38fb";
 
-        JavaFileObject source = JavaFileObjects.forSourceLines(
+        final JavaFileObject source = JavaFileObjects.forSourceLines(
                 "io.qameta.allure.description.test.DescriptionSample",
                 "package io.qameta.allure.description.test;",
                 "import io.qameta.allure.Description;",
@@ -53,19 +53,55 @@ void captureDescriptionTest() {
                 "}"
         );
 
-        Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor())
+        final Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor())
                 .withOptions("-Werror");
-        Compilation compilation = compiler.compile(source);
-        assertThat(compilation).generatedFile(
-                StandardLocation.CLASS_OUTPUT,
+        final Compilation compilation = compiler.compile(source);
+        assertThat(compilation)
+                .generatedFile(
+                        StandardLocation.CLASS_OUTPUT,
+                        "",
+                        ALLURE_DESCRIPTIONS_FOLDER + expectedMethodSignatureHash
+                )
+                .contentsAsUtf8String()
+                .isEqualTo("Captured javadoc description");
+    }
+
+    @Test
+    void captureDescriptionTestIfNoUseJavadocIsSpecified() {
+        final String expectedMethodSignatureHash = "4e7f896021ef2fce7c1deb7f5b9e38fb";
+
+        final JavaFileObject source = JavaFileObjects.forSourceLines(
+                "io.qameta.allure.description.test.DescriptionSample",
+                "package io.qameta.allure.description.test;",
+                "import io.qameta.allure.Description;",
                 "",
-                ALLURE_DESCRIPTIONS_FOLDER + expectedMethodSignatureHash
+                "public class DescriptionSample {",
+                "",
+                "/**",
+                "* Captured javadoc description",
+                "*/",
+                "@Description",
+                "public void sampleTest() {",
+                "}",
+                "}"
         );
+
+        final Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor())
+                .withOptions("-Werror");
+        final Compilation compilation = compiler.compile(source);
+        assertThat(compilation)
+                .generatedFile(
+                        StandardLocation.CLASS_OUTPUT,
+                        "",
+                        ALLURE_DESCRIPTIONS_FOLDER + expectedMethodSignatureHash
+                )
+                .contentsAsUtf8String()
+                .contains("Captured javadoc description");
     }
 
     @Test
     void skipUncommentedMethodTest() {
-        JavaFileObject source = JavaFileObjects.forSourceLines(
+        final JavaFileObject source = JavaFileObjects.forSourceLines(
                 "io.qameta.allure.description.test.DescriptionSample",
                 "package io.qameta.allure.description.test;",
                 "import io.qameta.allure.Description;",
@@ -78,19 +114,16 @@ void skipUncommentedMethodTest() {
                 "}"
         );
 
-        Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
-        Compilation compilation = compiler.compile(source);
+        final Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
+        final Compilation compilation = compiler.compile(source);
         assertThat(compilation).succeeded();
-        assertThat(compilation)
-                .hadWarningContaining("Unable to create resource for method "
-                        + "sampleTestWithoutJavadocComment[] as it does not have a docs comment");
     }
 
     @Test
     void captureDescriptionParametrizedTestWithGenericParameterTest() {
         final String expectedMethodSignatureHash = "e90e26691bf14511db819d78624ba716";
 
-        JavaFileObject source = JavaFileObjects.forSourceLines(
+        final JavaFileObject source = JavaFileObjects.forSourceLines(
                 "io.qameta.allure.description.test.DescriptionSample",
                 "package io.qameta.allure.description.test;",
                 "import io.qameta.allure.Description;",
@@ -117,8 +150,8 @@ void captureDescriptionParametrizedTestWithGenericParameterTest() {
                 "}"
         );
 
-        Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
-        Compilation compilation = compiler.compile(source);
+        final Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
+        final Compilation compilation = compiler.compile(source);
         assertThat(compilation).generatedFile(
                 StandardLocation.CLASS_OUTPUT,
                 "",
@@ -130,7 +163,7 @@ void captureDescriptionParametrizedTestWithGenericParameterTest() {
     void captureDescriptionParametrizedTestWithPrimitivesParameterTest() {
         final String expectedMethodSignatureHash = "edeeeaa02f01218cc206e0c6ff024c7a";
 
-        JavaFileObject source = JavaFileObjects.forSourceLines(
+        final JavaFileObject source = JavaFileObjects.forSourceLines(
                 "io.qameta.allure.description.test.DescriptionSample",
                 "package io.qameta.allure.description.test;",
                 "import io.qameta.allure.Description;",
@@ -150,12 +183,15 @@ void captureDescriptionParametrizedTestWithPrimitivesParameterTest() {
                 "}"
         );
 
-        Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
-        Compilation compilation = compiler.compile(source);
-        assertThat(compilation).generatedFile(
-                StandardLocation.CLASS_OUTPUT,
-                "",
-                ALLURE_DESCRIPTIONS_FOLDER + expectedMethodSignatureHash
-        );
+        final Compiler compiler = javac().withProcessors(new JavaDocDescriptionsProcessor());
+        final Compilation compilation = compiler.compile(source);
+        assertThat(compilation)
+                .generatedFile(
+                        StandardLocation.CLASS_OUTPUT,
+                        "",
+                        ALLURE_DESCRIPTIONS_FOLDER + expectedMethodSignatureHash
+                )
+                .contentsAsUtf8String()
+                .isEqualTo("Captured javadoc description");
     }
 }

allure-java-commons/src/main/java/io/qameta/allure/Description.java

@@ -21,7 +21,7 @@
 import java.lang.annotation.Target;
 
 /**
- *  Annotation that allows to attach a description for a test.
+ * Annotation that allows to attach a description for a test.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
@@ -39,7 +39,9 @@
      * supports html markdown.
      *
      * @return boolean flag to enable description extraction from javadoc.
+     * @deprecated use {@link Description} without value specified instead.
      */
+    @Deprecated
     boolean useJavaDoc() default false;
 
 }

allure-java-commons/src/main/java/io/qameta/allure/util/ResultsUtils.java

@@ -389,11 +389,12 @@ public static void processDescription(final ClassLoader classLoader,
                                           final Consumer<String> setDescription,
                                           final Consumer<String> setDescriptionHtml) {
         if (method.isAnnotationPresent(Description.class)) {
-            if (method.getAnnotation(Description.class).useJavaDoc()) {
+            final Description annotation = method.getAnnotation(Description.class);
+            if ("".equals(annotation.value())) {
                 getJavadocDescription(classLoader, method)
                         .ifPresent(setDescriptionHtml);
             } else {
-                final String description = method.getAnnotation(Description.class).value();
+                final String description = annotation.value();
                 setDescription.accept(description);
             }
         }

allure-junit4/build.gradle.kts

@@ -6,6 +6,7 @@ dependencies {
     api(project(":allure-java-commons"))
     implementation("junit:junit:$junitVersion")
     implementation(project(":allure-test-filter"))
+    testAnnotationProcessor(project(":allure-descriptions-javadoc"))
     testImplementation("org.assertj:assertj-core")
     testImplementation("org.junit.jupiter:junit-jupiter-api")
     testImplementation("org.mockito:mockito-core")