JUnit 5 并未提供 @Description 注解（该注解属于 JDK Flight Recorder，与测试无关）；真正用于提升测试可读性的标准方案是 @DisplayName，配合自定义 DisplayNameGenerator 或 Javadoc 文档化，即可清晰表达 Given-When-Then 等行为语义。
junit 5 并未提供 `@description` 注解（该注解属于 jdk flight recorder，与测试无关）；真正用于提升测试可读性的标准方案是 `@displayname`，配合自定义 `displaynamegenerator` 或 javadoc 文档化，即可清晰表达 given-when-then 等行为语义。
在 JUnit 5 中，开发者常误以为存在类似 @Description 的注解来为测试方法添加长文本说明（例如完整描述“Given a dog with name ‘Fido’ and weight 5.25kg, when comparing with an identical instance, then equals() returns true”），但事实是：org.junit.jupiter.api.Description 并不存在——这是常见误解，部分源于 IDE 自动补全误导或 AI 工具错误生成。
你当前使用的 @Description 来自 jdk.jfr.Description，它专用于 JDK Flight Recorder（JFR）性能事件标记，完全不被 JUnit 测试引擎识别或渲染，因此无论在 IntelliJ 运行窗口、Maven Surefire 报告，还是 TestNG 风格的 HTML 报告中，均不可见。
✅ 正确且官方支持的替代方案如下：
1. 使用 @DisplayName（最简直接）
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
class DogTest {
@Test
@DisplayName("Given two dogs with same name and weight, when compared via equals(), then return true")
void testComparisonOfDogObjects() {
Dog dog = new Dog("Fido", 5.25f);
Dog dogClone = new Dog("Fido", 5.25f);
assertEquals(dog, dogClone);
}
}
效果：IntelliJ 测试面板、Gradle/Maven 控制台输出及 IDE 运行器中将直接显示该长字符串，取代默认方法名 testComparisonOfDogObjects。
2. 全局启用驼峰/下划线转可读名（免手动加 @DisplayName）
在 src/test/resources/junit-platform.properties 中添加：
junit.jupiter.displayname.generator.default = org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores
然后命名测试方法为：
@Test
void given_two_dogs_with_same_name_and_weight_when_compared_via_equals_then_return_true() {
// ...
}
运行时自动渲染为 “Given two dogs with same name and weight when compared via equals then return true”。
3. 自定义 DisplayNameGenerator（高级定制）
适用于统一团队规范（如强制前置 GIVEN_, WHEN_, THEN_）：
public class GwtDisplayNameGenerator implements DisplayNameGenerator.Standard {
@Override
public String generateDisplayNameForMethod(Class> testClass, Method testMethod) {
String name = testMethod.getName();
return name.replaceFirst("^given_", "Given ")
.replaceFirst("^when_", "When ")
.replaceFirst("^then_", "Then ")
.replaceAll("_", " ");
}
}
并在 junit-platform.properties 中配置：
junit.jupiter.displayname.generator.default = com.example.GwtDisplayNameGenerator
⚠️ 注意事项
- ❌ 不要引入 junit4 的 org.junit.runner.Description：它仅服务于 JUnit 4 Runner，与 JUnit 5 引擎不兼容，混用可能导致测试不执行或 ClassLoader 冲突；
- ❌ 避免依赖非标准第三方 @Description 扩展：JUnit 官方生态未采纳该设计，维护性和 IDE 支持无保障；
- ✅ 推荐组合使用：@DisplayName（关键用例显式标注） + DisplayNameGenerator（常规用例自动化） + Javadoc（补充业务上下文，虽不实时显示于运行器，但对代码审查和文档生成至关重要）。
总结：JUnit 5 的设计理念强调简洁性与可组合性，而非堆砌元数据。@DisplayName 已足够承载行为描述职责，无需额外“描述注解”。坚持使用它，并辅以命名规范与文档习惯，即可构建出高可读、易维护、IDE 友好的测试套件。
