[JUnit] @DisplayName으로 테스트를 문서처럼 읽기 좋게 만드는 방법

1. 왜 @DisplayName을 사용해야 할까?

JUnit 테스트는 기본적으로 메소드 이름이 그대로 테스트 제목으로 사용됩니다.
하지만 메소드 이름으로는 테스트 의도를 충분히 표현하기 어려운 경우가 많습니다.

예를 들어,

void testDeposit() { ... }

이런 이름만 보면
“입금이 어떤 조건에서 어떻게 동작하는 것인지”
정확히 파악하기 어렵습니다.

@DisplayName을 사용하면 테스트 이름을 자연어 형태로 읽기 쉽게 표현할 수 있어,
테스트가 마치 문서처럼 읽히며 테스트 목적을 명확하게 전달할 수 있습니다.

 

2. @DisplayName 기본 사용법

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

class DisplayNameTest {

    @Test
    @DisplayName("입금하면 잔액이 증가한다")
    void deposit_increases_balance() {
        int balance = 1000 + 500;
        org.junit.jupiter.api.Assertions.assertEquals(1500, balance);
    }
}

설명

• @DisplayName("입금하면 잔액이 증가한다")
• 메소드 이름은 의미 전달에 제한적이지만
  DisplayName은 사람이 읽는 문장 그대로 테스트 제목을 표현할 수 있습니다.

 

3. 테스트 클래스에도 사용할 수 있다

@DisplayName("BankAccount 클래스 테스트")
class BankAccountTest { ... }

효과

• 테스트 실행 결과에서 클래스 이름 대신 더 설명적인 제목이 표시됩니다.
• 테스트 보고서가 문서처럼 자연스럽게 읽힙니다.

 

4. 이모지나 특수 문자도 사용할 수 있다

JUnit 5에서는 DisplayName에서 이모지 사용도 가능합니다.

@Test
@DisplayName("비밀번호는 8자 이상이어야 한다")
void validatePassword() {
    String password = "12345678";
    org.junit.jupiter.api.Assertions.assertTrue(password.length() >= 8);
}

효과

• 테스트 목록이 더 친근하고 직관적으로 변합니다.
• 복잡한 도메인 로직의 테스트도 분위기를 부드럽게 만들 수 있습니다.

 

5. 도메인 규칙을 명확히 드러내는 예제

특히 복잡한 조건을 테스트할 때 DisplayName이 큰 효과를 발휘합니다.

@Test
@DisplayName("나이가 0 미만이면 회원 생성에 실패한다")
void create_user_fails_when_age_negative() {
    int age = -1;
    org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class, () -> {
        if (age < 0) throw new IllegalArgumentException();
    });
}

설명

• 테스트 제목만 읽어도 도메인 규칙이 무엇인지 바로 이해할 수 있습니다.

 

6. BDD 스타일과 함께 사용하기

DisplayName은 BDD(Given-When-Then) 스타일과 매우 잘 어울립니다.

@Test
@DisplayName("Given 성인이 아닌 회원 When 회원가입을 시도하면 Then 가입이 거부된다")
void signup_reject_when_minor() {
    int age = 15;
    org.junit.jupiter.api.Assertions.assertThrows(IllegalStateException.class, () -> {
        if (age < 18) throw new IllegalStateException();
    });
}

설명

• 테스트가 시나리오 문서처럼 읽혀 협업자(동료 개발자, QA, 기획자)도 쉽게 이해합니다.

 

7. @DisplayName 사용 시 팁

1. 테스트 목적을 한 문장으로 요약해서 적는다.
   “무엇을 테스트하는지” + “어떤 조건인지”가 포함되면 가장 좋습니다.
2. 메소드 이름은 짧고 기술적으로, DisplayName은 설명적으로 작성한다.
   예:
   • 메소드 이름: deposit_increases_balance()
   • DisplayName: "입금하면 잔액이 증가한다"
3. 한글 사용을 적극적으로 고려한다.
   테스트는 개발자의 문서이므로, 팀에서 읽기 쉬운 언어를 쓰는 것이 가장 좋습니다.
4. 중첩 테스트(@Nested)와 함께 쓰면 더 강력하다.
   계층 구조를 가진 테스트 문서를 만들 수 있습니다.