There is a newer version available.
For the latest stable version, please use JUnit 6.0.1!

Display Names

Test classes and test methods can declare custom display names via @DisplayName — with spaces, special characters, and even emojis — that will be displayed in test reports and by test runners and IDEs.

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.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() {
	}

}

Control characters in text-based arguments in display names for parameterized tests are escaped by default. See Quoted Text-based Arguments for details.

Any remaining ISO control characters in a display name will be replaced as follows.

Original Replacement Description

\r

<CR>

Textual representation of a carriage return

\n

<LF>

Textual representation of a line feed

Other control character

�

Unicode replacement character (U+FFFD)

Display Name Generators

JUnit Jupiter supports custom display name generators that can be configured via the @DisplayNameGeneration annotation.

Generators can be created by implementing the DisplayNameGenerator API. The following table lists the default display name generators available in Jupiter.

DisplayNameGenerator Behavior

Standard

Matches the standard display name generation behavior in place since JUnit Jupiter was introduced.

Simple

Extends the functionality of Standard by removing 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.
Values provided via @DisplayName annotations always take precedence over display names generated by a DisplayNameGenerator.

The following example demonstrates the use of the ReplaceUnderscores display name generator.

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

	@Test
	void if_it_is_zero() {
	}

	@DisplayName("A negative value for year is not supported by the leap year computation.")
	@ParameterizedTest(name = "For example, year {0} is not supported.")
	@ValueSource(ints = { -1, -4 })
	void if_it_is_negative(int year) {
	}

}

Running the above test class results in the following display names.

A year is not supported ✔
├─ if it is zero ✔
└─ A negative value for year is not supported by the leap year computation. ✔
   ├─ For example, year -1 is not supported. ✔
   └─ For example, year -4 is not supported. ✔

With the IndicativeSentences display name generator, you can customize the separator and the underlying generator by using @IndicativeSentencesGeneration as shown in the following example.

@IndicativeSentencesGeneration(separator = " -> ", generator = ReplaceUnderscores.class)
class A_year_is_a_leap_year {

	@Test
	void if_it_is_divisible_by_4_but_not_by_100() {
	}

	@ParameterizedTest(name = "Year {0} is a leap year.")
	@ValueSource(ints = { 2016, 2020, 2048 })
	void if_it_is_one_of_the_following_years(int year) {
	}

}

Running the above test class results in the following display names.

A year is a leap year ✔
├─ A year is a leap year -> if it is divisible by 4 but not by 100 ✔
└─ A year is a leap year -> if it is one of the following years ✔
   ├─ Year 2016 is a leap year. ✔
   ├─ Year 2020 is a leap year. ✔
   └─ Year 2048 is a leap year. ✔

With IndicativeSentences, you can optionally specify custom sentence fragments via the @SentenceFragment annotation as demonstrated in the following example.

@SentenceFragment("A year is a leap year")
@IndicativeSentencesGeneration
class LeapYearTests {

	@SentenceFragment("if it is divisible by 4 but not by 100")
	@Test
	void divisibleBy4ButNotBy100() {
	}

	@SentenceFragment("if it is one of the following years")
	@ParameterizedTest(name = "{0}")
	@ValueSource(ints = { 2016, 2020, 2048 })
	void validLeapYear(int year) {
	}

}

Running the above test class results in the following display names.

A year is a leap year ✔
├─ A year is a leap year, if it is divisible by 4 but not by 100 ✔
└─ A year is a leap year, if it is one of the following years ✔
   ├─ 2016 ✔
   ├─ 2020 ✔
   └─ 2048 ✔

Setting the Default Display Name Generator

You can use the junit.jupiter.displayname.generator.default configuration parameter to specify the fully qualified class name of the DisplayNameGenerator you would like to use by default. Just like for display name generators configured via the @DisplayNameGeneration annotation, the supplied class has to implement the DisplayNameGenerator interface. The default display name generator will be used for all tests unless the @DisplayNameGeneration annotation is present on an enclosing test class or test interface. Values provided via @DisplayName annotations always take precedence over display names generated by a DisplayNameGenerator.

For example, to use the ReplaceUnderscores display name generator by default, you should set the configuration parameter to the corresponding fully qualified class name (e.g., in src/test/resources/junit-platform.properties):

junit.jupiter.displayname.generator.default = \
    org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores

Similarly, you can specify the fully qualified name of any custom class that implements DisplayNameGenerator.

In summary, the display name for a test class or method is determined according to the following precedence rules:

  1. value of the @DisplayName annotation, if present

  2. by calling the DisplayNameGenerator specified in the @DisplayNameGeneration annotation, if present

  3. by calling the default DisplayNameGenerator configured via the configuration parameter, if present

  4. by calling org.junit.jupiter.api.DisplayNameGenerator.Standard