JUnit 5: Using Custom DisplayNames for Tests

JUnit 5 provides a powerful feature called @DisplayName, which allows you to customize the display name of your tests for better readability. In this tutorial, we will explore how to take control of your test names using the JUnit 5 DisplayNameGenerator. This feature enables you to create expressive, informative, and dynamic test names, making your test suite more readable and maintainable.

Prerequisites:

Basic knowledge of JUnit 5 annotations.
A Java project with JUnit 5 dependencies.

If you are new to JUnit 5 we recommend checking this article: JUnit 5 : Step-by-step Tutorial

Step 1: Understand @DisplayName Annotation

The @DisplayName annotation is used to provide a custom name for your test method. It enhances the readability of your tests by allowing you to use spaces, special characters, and Unicode characters in your test names. For example:

@Test
@DisplayName("Adding two numbers")
void add_two_numbers() {
	Calculator calculator = new Calculator();
	assertEquals(2, calculator.add(1, 1), "1 + 1 should equal 2");
}

As you can see, by running the above Test will use as display name “Adding two numbers”:

Besides, be aware the the DisplayName will take precedence over the following annotation we will discuss in the next sections.

Step 2: Explore Default DisplayNameGenerator

JUnit 5 comes with a default DisplayNameGenerator that automatically generates display names based on the method names. While this works well for most cases, there are scenarios where you may need more control.

Here are some default DisplayNameGenerator available in Jupiter:

DisplayNameGenerator	Behavior
`Standard`	Matches the standard display name generation behavior in place since JUnit Jupiter 5.0 was released.
`Simple`	Removes trailing parentheses for methods with no parameters.
`ReplaceUnderscores`	Replaces underscores with spaces.
`IndicativeSentences`	Generates complete sentences by concatenating the names of the test and the enclosing classes.

For example, to replace underscore with spaces for all your Tests in a Class, you can use:

@DisplayNameGeneration(DisplayNameGenerator.ReplaceUnderscores.class)
class CalculatorTests {

	@Test
	void add_two_numbers() {
		Calculator calculator = new Calculator();
		assertEquals(2, calculator.add(1, 1), "1 + 1 should equal 2");
	}
}

This time the Test display name will be the following one:

Step 3: Create a Custom DisplayNameGenerator

To create a custom DisplayNameGenerator, implement the org.junit.jupiter.api.DisplayNameGenerator interface. This interface has the following methods which you need to override:

public class UppercaseDisplayNameGenerator implements DisplayNameGenerator {
    @Override
    public String generateDisplayNameForClass(Class<?> testClass) {
        return testClass.getSimpleName().toUpperCase();
    }

    @Override
    public String generateDisplayNameForNestedClass(Class<?> nestedClass) {
        return nestedClass.getSimpleName().toUpperCase();
    }

    @Override
    public String generateDisplayNameForMethod(Class<?> testClass, Method testMethod) {
        return testMethod.getName().toUpperCase();
    }
}

Our Custom UppercaseDisplayNameGenerator will transform to uppercase methods and classes in the Test Report.

Apply it as follows in your Class:

@DisplayNameGeneration(UppercaseDisplayNameGenerator.class)
class CalculatorTests {
}

Here is your Test Report:

Conclusion

In this tutorial, we explored the DisplayNameGenerator feature in JUnit 5, allowing us to create custom test names. By leveraging this capability, you can make your tests more descriptive, fostering better communication within your development team and making your test suite more maintainable in the long run.

Experiment with different display name strategies based on your project’s needs, and enjoy the benefits of cleaner and more informative test names. Happy testing!

Source code for this example: https://github.com/fmarchioni/mastertheboss/tree/master/test/junit5-namegeneration

Found the article helpful? if so please follow us on Socials