= 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.

[source,java,indent=0]
----
include::example$java/example/DisplayNameDemo.java[tags=user_guide]
----

[[generator]]
== 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.

[cols="20,80"]
|===
| DisplayNameGenerator   | Behavior

| `Standard`            | Matches the standard display name generation behavior in place since JUnit Jupiter 5.0 was released.
| `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.
|===

NOTE: 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.

[source,java,indent=0]
----
include::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_replace_underscores]
----

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.

[source,java,indent=0]
----
include::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_indicative_sentences]
----

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.

[source,java,indent=0]
----
include::example$java/example/DisplayNameGeneratorDemo.java[tags=user_guide_custom_sentence_fragments]
----

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 ✔
```
======


[[generator-default]]
== Setting the Default Display Name Generator

You can use the `junit.jupiter.displayname.generator.default`
xref:running-tests/configuration-parameters.adoc[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`):

[source,properties,indent=0]
----
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`.

[[generator-precedence-rules]]
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`
