@DisplayName Annotation in JUnit 5

The @DisplayName annotation is used to provide a custom name for your JUnit 5 test method. Let’s have a look how it is used in Java code.

Below, is a very simple code example of a JUnit 5 test method.  Notice how the @DisplayName annotation is used to provide a custom name for the text method.

@DisplayName("Test 4/2 = 2")
@Test
void testIntegerDivision_WhenFourIsDividedByTwo_ShouldReturnTwo() {
   // Arrange 

  // Act

  // Assert 
}

If @DisplayName annotation is not used then the name of the test method will be used in the test report instead.

Using Special Characters or Emoji in the @DisplayName Annotation in JUnit 5

JUnit 5’s @DisplayName annotation allows us to use a more descriptive and human-readable name for our tests, making it easier for anyone reviewing the test results to understand what the test is about. One of the exciting features of @DisplayName is that it supports special characters and even emoji. This allows us to make our tests more expressive and engaging.

Special characters can be directly inserted in the display name string, and for emojis, we can use unicode representations.

@DisplayName("🔢 Testing integer division: 4 ➗ 2 = 2️⃣")
@Test
void testIntegerDivision_WhenFourIsDividedByTwo_ShouldReturnTwo() {
    // Arrange 

    // Act

    // Assert 
}

In this example, we have used a few emojis to make our test name more expressive. The unicode for the emojis are placed directly within the string.

Here’s how you do it:

1. Annotating the Test Method: To add a display name to a test method, we annotate the method with @DisplayName.
2. Adding Special Characters: You can add special characters directly to the display name. Just make sure the characters are supported by your IDE and the systems that will display the test results.
3. Adding Emoji: You can add emoji by copying and pasting the emoji directly or by adding their unicode. Some popular places to find emoji and their unicode include websites like Emojipedia.
4. Running the Test: When you run the test, the custom display name including the special characters and emoji will appear in the test results.

Remember, while it can be fun and expressive to use special characters and emoji in your test names, it’s important to ensure that the names remain descriptive and meaningful. The goal is to make the tests easier to understand for anyone who is reading the test report.

Can we use @DisplayName on a test class and its methods?

The short answer is yes, you certainly can! But let’s break it down in detail for absolute beginners.

@DisplayName on a Test Class

Firstly, you can apply the @DisplayName annotation at the class level. This means you can provide a custom name for the entire test class, which will be shown in the test reports instead of the class name. This is especially helpful when you want to provide a more descriptive or readable name for your test class.

Here’s an example:

@DisplayName("Our first test class")
public class FirstTest {
    // test methods go here
}

In the above example, we have a test class named FirstTest. But in our test reports, it would be referred to as “Our first test class”, which is the name we’ve provided using the @DisplayName annotation.

@DisplayName on Both Test Class and Test Methods

You can combine the two approaches above and use @DisplayName on both the test class and its methods. Here’s an example:

@DisplayName("Our first test class")
public class FirstTest {

    @DisplayName("Testing if two plus two equals four")
    @Test
    void testAddition() {
        // Arrange
        int a = 2;
        int b = 2;

        // Act
        int sum = a + b;

        // Assert
        assertEquals(4, sum);
    }

    // more test methods can go here
}

In this example, we’ve used @DisplayName on both the class and one of its methods. The test reports will now use these custom names instead of the class and method names.

Using @DisplayName with Parameterized Tests

Now, let’s get into the crux of the matter: how to use @DisplayName with parameterized tests. In its simplest form, you can directly use @DisplayName with a parameterized test just like with any other test. Here’s how:

@DisplayName("Testing integer division with different divisors")
@ParameterizedTest
@ValueSource(ints = {2, 4, 6, 8})
void testIntegerDivision_WhenFourIsDividedByDifferentNumbers(int divisor) {
    // Arrange
    int dividend = 4;

    // Act
    int quotient = dividend / divisor;

    // Assert
    assertTrue(quotient >= 0 && quotient <= 4);
}

Here, we’re adding a @DisplayName annotation to the test, giving it a custom name that will be displayed in test reports.

Customizing @DisplayName for Each Test Invocation

While the above use is good, it doesn’t allow us to customize the name for each invocation of the test. What if we want a custom name for each different parameter we’re testing with? That’s where the {0}, {1}, …, {n} placeholders come in. You can use these placeholders in your @DisplayName to refer to the parameters.

Here’s an example:

@DisplayName("Testing integer division when four is divided by {0}")
@ParameterizedTest
@ValueSource(ints = {2, 4, 6, 8})
void testIntegerDivision_WhenFourIsDividedByDifferentNumbers(int divisor) {
    // Arrange
    int dividend = 4;

    // Act
    int quotient = dividend / divisor;

    // Assert
    assertTrue(quotient >= 0 && quotient <= 4);
}

In this example, the {0} in the @DisplayName will be replaced by the current divisor for each invocation of the test. This way, you’ll have a custom display name for each run of your test method!

And there you have it! That’s how the @DisplayName annotation works

Frequently Asked Questions

1. Can I use special characters or emoji in the display name?
   Yes, you can use special characters and even emoji in the display name. This allows you to make the display names more expressive and user-friendly.
2. Will the @DisplayName replace the method name in test reports?
   Yes, if provided, the value of the @DisplayName annotation will be used in the test reports instead of the method or class name. It’s important to note, however, that it does not change the actual name of the method or class.
3. Can I use @DisplayName on a test class and its methods?
   Yes, you can use the @DisplayName annotation on both test classes and test methods. If used on a class, it changes the display name of the class in the test report. If used on a method, it changes the display name of that particular method.
4. Does @DisplayName have any impact on the execution order of tests?
   No, the @DisplayName annotation is purely cosmetic and does not affect the execution order of the tests.
5. What is the difference between @DisplayName and the method name?
   The method name is how you refer to the method in your code, while the display name is a more human-readable name used in test reports and can include special characters and spaces, which are not allowed in method names.
6. Does @DisplayName work with parameterized tests?
   Yes, @DisplayName works with parameterized tests. You can use it to provide a custom display name for the test. For dynamic generation of display names in parameterized tests, you can use @DisplayNameGeneration along with a custom DisplayNameGenerator.

Video Tutorial

This was a very short tutorial. If you are interested in learning more about JUnit, then Visit the Testing Java Code page where you’ll find valuable tutorials that will equip you with the knowledge to create finely structured and optimized test cases.