JUnit Reports — Test Method Descriptions

Question

I am trying to see if there is a way to include "descriptive text" in my junit reports by way of javadocs. JUnit 4 doesnt seem to support the 'description' attribute for the @Test annotation like TestNG does.

So far from what I have researched there is only one tool out there called javadoc-junit (http://javadoc-junit.sourceforge.net/). However I could not get this to work since it seems to be incompatible with Junit 4.

What I want is some way to provide a sentence or two of text with my each test method in the JUnit report. JavaDoc is no good since the target audience will have to swtich between JavaDoc and the Junit Report to see documentation and/or test stats.

Anyone know of anything else I could use with minimal effort?

Best, Ray J

Answer 1

In JUnit 5 there is a way to annotate every test with a @DisplayName. The declared test classes can have text, special characters and emojis.

The declared text on each test is visible by test runners and test reports.

---

The Javadoc says:

public @interface DisplayName

@DisplayName is used to declare a custom display name for the annotated test class or test method. Display names are typically used for test reporting in IDEs and build tools and may contain spaces, special characters, and even emoji.

And the User Guide:

import org.junit.gen5.api.DisplayName;
import org.junit.gen5.api.Test;

@DisplayName("A special test case")
class DisplayNameDemo {

    @Test
    @DisplayName("Custom test name containing spaces")
    void testWithDisplayNameContainingSpaces() {
    }

    @Test
    @DisplayName("╯°□°）╯")
    void testWithDisplayNameContainingSpecialCharacters() {
    }

    @Test
    @DisplayName("😱")
    void testWithDisplayNameContainingEmoji() {
    }
}

Answer 2

There's also rather recent solution called Allure. That's a Java-based test execution report mainly based on adding supplementary annotations to the code. Existing annotations include:

• custom description: @Description("A cool test")
• grouping by features or stories: @Features({"feature1", "feature2"}), @Stories({"story1", "story2" })
• marking methods executed inside test case as steps: @Step (works even for private methods)
• attachments: @Attachment(name = "Page screenshot", type = "image/png")

See their wiki and example project for more details.

Answer 3

I don't put javadocs in JUnit tests. I usually make the name of the method descriptive enough so it's as good as or better than any comment I could come up with.

Answer 4

I could imagine, that the Framework for Integrated Tests (FIT) would be a nice and clean solution.

What does FIT do?
FIT is a framework that allows to write tests via a table in a Word document, a wiki table or an html table.
Every character outside of a table is ignored by FIT and let you enter documentation, description, requirements and so on.

How does on of these tables look like?

Imagine a function MyMath.square(int) that squares it's input parameter. You have to build a so called Fixture, being an adapter between your MyMath and the following table:

class.with.Fixture.Square
x    square()
2    4
5    25

The first column describes input values, the second the expected result. If it's not equal, this field is marked as red.

How does a Fixture look like?
For the given example, this would be the correct fixture:

package class.with.Fixture // Must be the same as in the fist row of the table

public class Square extends Fixture {
    public int x; // Must be the same as in the second row
    public int square() { // Must be the same as in the second row
        return MyMath.square(x);
    }
}

Probably, you can use FIT for your requirements.
Feel free to comment my answer or edit your question for more information!