allure-framework
Use a system property to use Javadoc descriptions per default (feature request)
Use a system property to use Javadoc descriptions per default, to use existing test code unmodified and still generate descriptions from Javadoc for all test methods globally.
I'm submitting a ...
- [X] feature request
What is the current behavior?
All test classes need an additional annotation line to generate the description from Javadoc.
@Description(useJavaDoc = true)
What is the expected behavior?
Always generate the test description from Javadoc
What is the motivation / use case for changing the behavior?
Allow to easily use Allure2 together with lots of existing tests with Javadoc as descriptions without adding the additional annotation above every test case:
@Description(useJavaDoc = true)
Code ideas / @suggestions
Either use a bool system property or in allure.properties
Boolean alwaysUseDescriptionFromJavadoc= Boolean.getBoolean("allure.description.fromjavadoc")
Add (!alwaysUseDescriptionFromJavadoc || !el.getAnnotation(Description.class).useJavaDoc())
https://github.com/allure-framework/allure-java/blob/111378afc46f5314047fd156a730140267b1ea68/allure-descriptions-javadoc/src/main/java/io/qameta/allure/description/JavaDocDescriptionsProcessor.java#L67
since the java docs are deleted during compilation and is not available in runtime, we are using JSR 269 (pluggable annotation processing API) to process java docs on test methods during compile time and store them to resources. So the annotation is required on method in order to process it.
the other option would be to rely on test frameworks annotations, but this way it would require more complex configuration (for example, for JUnit 5 you can create custom annotations for your tests, so you'll need to make sure to specify all the annotations you are using for your tests) plus in some frameworks you can write test methods without using annotations (for example, test methods can be discovered using naming convention) -- in that case some custom annotation will be still required.
speaking of your suggested solution -- I don't like having empty Description annotations in code base since it may confuse users. Maybe it would be more clear to have a separate JavaDocDescription annotation for that
That sounds reasonable and I did not think about other test frameworks that might not be using Annotations to find tests. My suggested solution would have not not eliminated the need for the @Description annotation. I can see that now and you can decline the proposed code change - this was not thought through and started off as quick idea.
But maybe you have a better idea on how we could make this the default behaviour since we only have Maven Java projects running tests either in JUnit4 or some already using JUnit5.
Our idea was to save the Description line and just use the DisplayName in JUnit5 where the Javadoc is not descriptive enough.
/**
* JUnit5 Disabled Test Case (was JUnit4 {@literal @}Ignore). An inactive Test that is not getting executed.<br>
* Ideally this is also the HTML description in the test report which would also allow some in detail description with formatting.
*/
@Test
@DisplayName("Inactive Test. Adding additional details using JUnit5 DisplayName annotation.")
@Disabled("This test is deactivated to show the @Disabled feature in JUnit5.")
// we would like to save this additional line and make this the "standard"
// @Description(useJavaDoc = true)
@Issue("JIRA-1234")
@Severity(SeverityLevel.CRITICAL)
void disabledTest() {
assertTrue(Boolean.TRUE);
}
Closing this request because it is not needed anymore and use case was not fully valid.