JUnit @DisplayName Annotation

JUnit is a popular testing framework in the Java ecosystem that simplifies writing and running tests. The @DisplayName annotation in JUnit 5 is used to provide a custom display name for test classes and test methods. This guide covers the basics of using the @DisplayName annotation to make your tests more readable and expressive.

Table of Contents

1. Introduction
2. Steps to Use @DisplayName
3. Real-World Use Case
4. Conclusion

Introduction

The @DisplayName annotation allows you to specify a custom name for your test classes and test methods. This is useful for making your tests more readable and understandable, especially when the default method names are not descriptive enough.

Steps to Use @DisplayName

Step 1: Add Maven Dependency

To use JUnit in your project, you need to add the JUnit dependency to your pom.xml file. Use the latest version of JUnit 5:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.9.2</version>
    <scope>test</scope>
</dependency>

Step 2: Create the Class to be Tested

Create a Java class with methods that you want to test. For example, a simple Calculator class:

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }

    public int subtract(int a, int b) {
        return a - b;
    }
}

Step 3: Create the Test Class with Custom Display Names

Create a test class in the src/test/java directory. Use the @DisplayName annotation to specify custom names for your test class and test methods.

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

@DisplayName("Calculator Test Suite")
public class CalculatorTest {
    private final Calculator calculator = new Calculator();

    @Test
    @DisplayName("Test Addition of Two Numbers")
    void testAddition() {
        assertEquals(5, calculator.add(2, 3), "2 + 3 should equal 5");
    }

    @Test
    @DisplayName("Test Subtraction of Two Numbers")
    void testSubtraction() {
        assertEquals(1, calculator.subtract(3, 2), "3 - 2 should equal 1");
    }
}

In this example, the CalculatorTest class is annotated with @DisplayName("Calculator Test Suite"), and each test method has a custom display name specified using the @DisplayName annotation.

Step 4: Run the Test

You can run the test using your IDE, Maven, or Gradle.

Using an IDE:

Most IDEs, like IntelliJ IDEA and Eclipse, have built-in support for running JUnit tests. Simply right-click on your test class or method and select “Run.”

Using Maven:

If you’re using Maven, you can run your tests with the following command:

mvn test

Using Gradle:

If you’re using Gradle, you can run your tests with the following command:

gradle test

Real-World Use Case

In real-world applications, custom display names can make your test reports more readable and understandable. For example, a BookService class might have methods for adding, updating, and deleting books. Custom display names can make the purpose of each test clear.

Create the Class to be Tested

Create a Java class that contains business logic. For example, a BookService class:

public class BookService {
    private Map<String, String> books = new HashMap<>();

    public boolean addBook(String isbn, String title) {
        if (books.containsKey(isbn)) {
            return false;
        }
        books.put(isbn, title);
        return true;
    }

    public boolean updateBook(String isbn, String title) {
        if (!books.containsKey(isbn)) {
            return false;
        }
        books.put(isbn, title);
        return true;
    }

    public boolean deleteBook(String isbn) {
        if (!books.containsKey(isbn)) {
            return false;
        }
        books.remove(isbn);
        return true;
    }

    public String getBook(String isbn) {
        return books.get(isbn);
    }
}

Create the Test Class with Custom Display Names

Create a test class for the BookService in the src/test/java directory. Use the @DisplayName annotation to specify custom names for your test class and test methods.

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertEquals;

@DisplayName("Book Service Test Suite")
public class BookServiceTest {
    private final BookService bookService = new BookService();

    @Test
    @DisplayName("Test Adding a New Book")
    void testAddBook() {
        assertTrue(bookService.addBook("123456", "JUnit 5 Guide"), "Book should be added successfully");
    }

    @Test
    @DisplayName("Test Adding a Duplicate Book")
    void testAddDuplicateBook() {
        bookService.addBook("123456", "JUnit 5 Guide");
        assertFalse(bookService.addBook("123456", "JUnit 5 Guide"), "Duplicate book should not be added");
    }

    @Test
    @DisplayName("Test Updating an Existing Book")
    void testUpdateBook() {
        bookService.addBook("123456", "JUnit 5 Guide");
        assertTrue(bookService.updateBook("123456", "JUnit 5 Advanced Guide"), "Book should be updated successfully");
    }

    @Test
    @DisplayName("Test Deleting an Existing Book")
    void testDeleteBook() {
        bookService.addBook("123456", "JUnit 5 Guide");
        assertTrue(bookService.deleteBook("123456"), "Book should be deleted successfully");
    }

    @Test
    @DisplayName("Test Retrieving a Book")
    void testGetBook() {
        bookService.addBook("123456", "JUnit 5 Guide");
        assertEquals("JUnit 5 Guide", bookService.getBook("123456"), "Retrieved book should match the added book");
    }
}

In this example, the BookServiceTest class is annotated with @DisplayName("Book Service Test Suite"), and each test method has a custom display name specified using the @DisplayName annotation.

Running the Tests

You can run the tests using your IDE, Maven, or Gradle.

Using an IDE:

Most IDEs, like IntelliJ IDEA and Eclipse, have built-in support for running JUnit tests. Simply right-click on your test class or method and select “Run.”

Using Maven:

If you’re using Maven, you can run your tests with the following command:

mvn test

Using Gradle:

If you’re using Gradle, you can run your tests with the following command:

gradle test

Conclusion

The @DisplayName annotation in JUnit makes it easy to provide custom names for your test classes and test methods. This is useful for making your tests more readable and understandable, especially when the default method names are not descriptive enough.