Close

JUnit 5 - Create a Custom DisplayNameGenerator

[Last Updated: Dec 4, 2025]

JUnit 5 allows you to integrate a custom DisplayNameGenerator to convert test class and method names into human-readable display names. Implement your own generator when the built-in options don’t meet your project’s naming conventions or style requirements.

Overview

  • Implement org.junit.jupiter.api.DisplayNameGenerator.
  • Annotate your test class with @DisplayNameGeneration(YourGenerator.class).
  • Method-level @DisplayName always overrides a generator.
  • Nested tests can have their own generated display names.

Quick syntax

public class CustomDisplayNameGenerator implements DisplayNameGenerator {
   @Override
    public String generateDisplayNameForClass(Class<?> testClass) {
        .....
    }

    @Override
    public String generateDisplayNameForNestedClass(Class<?> nestedClass) {
        .....
    }

    @Override
    public String generateDisplayNameForMethod(Class<?> testClass, Method testMethod) {
        .....        
    }
}
@DisplayNameGeneration(CustomDisplayNameGenerator.class)
class MyTests { /* ... */ }

Example

The custom generator

Following is a small custom DisplayNameGenerator implementation that:
- Adds spaces to camelCase words
- Replaces underscores with spaces
- Capitalizes the first letter 

package com.logicbig.example.display;

import org.junit.jupiter.api.DisplayNameGenerator;
import java.lang.reflect.Method;

public class CustomDisplayNameGenerator implements DisplayNameGenerator {

    @Override
    public String generateDisplayNameForClass(Class<?> testClass) {
        return prettify(testClass.getSimpleName());
    }

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

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

    private static String prettify(String name) {
        // Replace underscores with spaces
        String s = name.replace('_', ' ');
        // Insert spaces before capitals in camelCase words
        s = s.replaceAll("(?<=[a-z])([A-Z])", " $1");
        // Trim and capitalize first letter
        s = s.trim();
        if (s.isEmpty())
            return s;
        return Character.toUpperCase(s.charAt(0)) + s.substring(1);
    }
}

Using the generator on a test class

package com.logicbig.example;

import com.logicbig.example.display.CustomDisplayNameGenerator;
import org.junit.jupiter.api.DisplayNameGeneration;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

@DisplayNameGeneration(CustomDisplayNameGenerator.class)
class CustomGeneratorUsageTest {

    @Test
    void calculatesTotalPrice() {
        assertEquals(7, 3 + 4);
    }

    @Test
    void my_test_method_with_underscores() {
        assertTrue(true);
    }
}

mvn test -Dtest=CustomGeneratorUsageTest

Output

D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator>mvn test -Dtest=CustomGeneratorUsageTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-custom-display-name-generator >-----
[INFO] Building junit-5-custom-display-name-generator 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-custom-display-name-generator ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-custom-display-name-generator ---
[INFO] Recompiling the module because of added or removed source files.
[INFO] Compiling 3 source files with javac [debug target 25] to target\test-classes
[INFO] /D:/LogicBig/example-projects/junit-5/junit-5-test-display-name/junit-5-custom-display-name-generator/src/test/java/com/logicbig/example/display/CustomDisplayNameGenerator.java: D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\test\java\com\logicbig\example\display\CustomDisplayNameGenerator.java uses or overrides a deprecated API.
[INFO] /D:/LogicBig/example-projects/junit-5/junit-5-test-display-name/junit-5-custom-display-name-generator/src/test/java/com/logicbig/example/display/CustomDisplayNameGenerator.java: Recompile with -Xlint:deprecation for details.
[INFO] 
[INFO] --- surefire:3.5.3:test (default-test) @ junit-5-custom-display-name-generator ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--Custom Generator Usage Test - 0.092 ss
[INFO] |  +-- [OK] Calculates Total Price - 0.042 ss
[INFO] |  '-- [OK] My test method with underscores - 0.013 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.943 s
[INFO] Finished at: 2025-12-03T19:02:59+08:00
[INFO] ------------------------------------------------------------------------

@DisplayName still overrides

package com.logicbig.example;

import com.logicbig.example.display.CustomDisplayNameGenerator;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.DisplayNameGeneration;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

@DisplayNameGeneration(CustomDisplayNameGenerator.class)
class MethodOverrideDisplayNameTest {

    @Test
    @DisplayName("custom name overrides generator")
    void shortMethod() {
        assertEquals(4, 2 + 2);
    }

    @Test
    void when_input_is_zero_then_result_is_zero() {
        assertEquals(0, 0);
    }
}

mvn test -Dtest=MethodOverrideDisplayNameTest

Output

D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator>mvn test -Dtest=MethodOverrideDisplayNameTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-custom-display-name-generator >-----
[INFO] Building junit-5-custom-display-name-generator 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-custom-display-name-generator ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-custom-display-name-generator ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] 
[INFO] --- surefire:3.5.3:test (default-test) @ junit-5-custom-display-name-generator ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--Method Override Display Name Test - 0.090 ss
[INFO] |  +-- [OK] custom name overrides generator - 0.043 ss
[INFO] |  '-- [OK] When input is zero then result is zero - 0.010 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.804 s
[INFO] Finished at: 2025-12-03T19:03:04+08:00
[INFO] ------------------------------------------------------------------------

Run all

mvn test

Output

D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator>mvn test
[INFO] Scanning for projects...
[INFO] 
[INFO] -----< com.logicbig.example:junit-5-custom-display-name-generator >-----
[INFO] Building junit-5-custom-display-name-generator 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-custom-display-name-generator ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-custom-display-name-generator ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-test-display-name\junit-5-custom-display-name-generator\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-custom-display-name-generator ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] 
[INFO] --- surefire:3.5.3:test (default-test) @ junit-5-custom-display-name-generator ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] +--Custom Generator Usage Test - 0.101 ss
[INFO] |  +-- [OK] Calculates Total Price - 0.053 ss
[INFO] |  '-- [OK] My test method with underscores - 0.009 ss
[INFO] +--Method Override Display Name Test - 0.008 ss
[INFO] |  +-- [OK] custom name overrides generator - 0.002 ss
[INFO] |  '-- [OK] When input is zero then result is zero - 0.002 ss
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.460 s
[INFO] Finished at: 2025-12-03T19:03:09+08:00
[INFO] ------------------------------------------------------------------------

Running in IntelliJ

Example Project

Dependencies and Technologies Used:

  • junit-jupiter-engine 6.0.1 (Module "junit-jupiter-engine" of JUnit)
     Version Compatibility: 5.7.0 - 6.0.1Version List
    ×

    Version compatibilities of junit-jupiter-engine with this example:

    • 5.7.0
    • 5.7.1
    • 5.7.2
    • 5.8.0
    • 5.8.1
    • 5.8.2
    • 5.9.0
    • 5.9.1
    • 5.9.2
    • 5.9.3
    • 5.10.0
    • 5.10.1
    • 5.10.2
    • 5.10.3
    • 5.10.4
    • 5.10.5
    • 5.11.0
    • 5.11.1
    • 5.11.2
    • 5.11.3
    • 5.11.4
    • 5.12.0
    • 5.12.1
    • 5.12.2
    • 5.13.0
    • 5.13.1
    • 5.13.2
    • 5.13.3
    • 5.13.4
    • 5.14.0
    • 5.14.1
    • 6.0.0
    • 6.0.1

    Versions in green have been tested.

  • JDK 25
  • Maven 3.9.11
JUnit 5 - Custom Name Display Generator Select All Download
  • junit-5-custom-display-name-generator
    • src
      • test
        • java
          • com
            • logicbig
              • example
                • display
                  • CustomDisplayNameGenerator.java

    See Also