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");

@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");

@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();

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 {

@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

Prerequisites:

Step 1: Understand @DisplayName Annotation

Step 2: Explore Default DisplayNameGenerator

Step 3: Create a Custom DisplayNameGenerator

Conclusion

Recommend

How to write tests in Java - JUnit

Improve your tests with JUnit 5

Use GreenMail For Spring Mail (JavaMailSender) JUnit 5 Integration Tests

Use null values in JUnit 5 parameterized tests

Parameterized tests Junit using the file entry

Difference between JUnit theories and parametric tests

JUnit 5 - Writing Tests

Parallelize Only Java Unit Tests with JUnit 5 and Maven

JUnit 5 Parameterized Tests

How to run JUnit 5 Tests with JBang

About Joyk