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

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

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/DisplayNameDemo.kt[tags=user_guide]
----
--
====

[TIP]
====
In Kotlin, you can use backtick-enclosed function names as an alternative to
`@DisplayName` for simple display names:

[source,kotlin,indent=0]
----
@Test
fun `custom test name containing spaces`() {
    // will be displayed as "custom test name containing spaces"
}
----
====

[NOTE]
====
Control characters in text-based arguments in display names for parameterized tests are
escaped by default. See xref:writing-tests/parameterized-classes-and-tests.adoc#display-names-quoted-text[Quoted Text-based Arguments]
for details.

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

[cols="25%,15%,60%"]
|===
| 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)
|===
====

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

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.

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

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[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.

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

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[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.

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

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/DisplayNameGeneratorDemo.kt[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`
