🐞: Description using Javadoc includes @throws declarations

[netmikey]

What happened?

When using the Javadoc as description using @Description, it looks like @throws parts of the method's Javadoc are simply appended verbatim to the documentation.

Example:

    /**
     * This is my test description.
     * 
     * @throws Exception
     *             Thrown when the test unexpectedly fails.
     */
    @Test
    @Description
    public void testSomething() throws Exception {
        // ...
    }

Allure shows:

We would not expect the @throws Javadoc tag to be part of the message.

What Allure Integration are you using?

allure-junit5

What version of Allure Integration you are using?

2.27.0

What version of Allure Report you are using?

2.27.0

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[mr-possible]

@netmikey, Is this a good practice to provide description to tests in the manner mentioned? Can we simply not do something like what is given below? FYI, I am using TestNG as my test-runner for this example

    @Test(expectedExceptions = {IllegalStateException.class})
    @Description("This is my test description")
    public void testSomething() throws Exception {
        // ...
    }

Additionally, does it make sense to tell that a test throws some 'exception' in the description? Having said that, isn't throwing a general exception from a test an anti-pattern? But that's just me and I'll be happy to get corrected 😃

cc: @baev

[netmikey]

I'm not sure what exactly is the point you're making. This has also the potential to move into subjective opinionated territory very quickly so let's try to stay out of that here ;-)

The rationale behind why we write our code the way we do is the following (you might agree or disagree, I'm just trying to explain why we ended up doing it this way):

• Writing JavaDoc is a good thing
• There is a documented way how to write JavaDoc and what to include
• Tools like Checkstyle can (and do in our case) enforce that parameters and exceptions be well documented -> therefor you end up with the @throws line in the method's JavaDoc.
• We throw Exception on tests because it doesn't matter which exception gets thrown, any uncaught exception during test execution is considered a test failure and will be reported as such by the testing framework.

[baev]

I agree that we should process Javadoc somehow to clean it up. However, I don't know any reliable Java library that can parse the Javadocs. Micronaut uses https://github.com/chhorz/javadoc-parser for openapi generation; maybe we can also use it.