必须正确配置Maven或Gradle依赖及路径：Maven需在pom.xml添加junit-jupiter，Gradle需testImplementation和testRuntimeOnly；测试类放src/test/java、以Test结尾、public非final；@Test方法须public void无参数；IDE需关闭自动构建并委托给构建工具。

确认项目用了 Maven 还是 Gradle

JUnit 5 的依赖写法和构建工具强绑定，搞错就根本跑不起来。Maven 和 Gradle 的坐标/语法不同，不是改个名字就能通用。

常见错误现象：java.lang.NoClassDefFoundError: org/junit/jupiter/api/Test，八成是依赖没拉下来，或者版本冲突。

• Maven 项目必须在 pom.xml 中添加 junit-jupiter 依赖（不是 junit 或 junit-vintage-engine）
• Gradle 项目用 testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'，别漏掉 testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine' —— 否则 @Test 方法会被忽略
• Spring Boot 2.4+ 默认排除了旧版 JUnit，如果手动加了 junit:junit:4.13.2，反而会压垮 JUnit 5 的启动器

测试类命名和位置不能乱放

IDE 和构建工具默认只扫描特定路径下的特定命名模式的类。放错地方，mvn test 或 IDE 的“Run Test”按钮就完全看不到你的测试。

• 测试类必须放在 src/test/java 下，不能和主代码混在 src/main/java
• 类名建议以 Test 结尾（如 UserServiceTest），否则某些老版插件可能跳过
• 类不能是 private 或 final，否则 JUnit 5 的反射实例化会失败，报 Cannot invoke a non-static inner class without an enclosing instance

@Test 方法签名有硬性限制

JUnit 5 对测试方法的要求比 JUnit 4 更严格，不是加个注解就万事大吉。签名不对，运行时直接跳过或抛异常。

deep-java-review

Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...

下载

立即学习“Java免费学习笔记（深入）”；

• 方法必须是 public（不是 default、protected 或包私有）
• 返回类型必须是 void；返回 String 或 int 会导致 MethodSource 类型错误
• 参数只能是注入类（如 TestInfo、TestReporter）或通过 @ParameterizedTest 配合 @ValueSource 等提供，不能写普通参数如 String name
• 别在 @Test 方法里调 System.exit(0) —— 它会让整个 JVM 退出，Maven 进程直接中断

运行测试前先关掉 IDE 的自动构建陷阱

IntelliJ 和 Eclipse 有时会缓存旧的编译结果或使用内置测试引擎，导致你改了依赖、加了注解，却还在跑 JUnit 4 的逻辑。

• IntelliJ：检查 Settings > Build > Build Tools > Maven > Runner 是否勾选了 Delegate IDE build/run actions to Maven；没勾的话，IDE 可能用自己那套 ClassLoader 加载测试，绕过你配的 junit-jupiter
• Eclipse：右键项目 → Properties > Java Build Path > Libraries，确认 junit-jupiter-api 和 junit-jupiter-engine 在 test 范围，且没被 junit-4.13.2.jar 覆盖
• 最稳的方式：终端执行 mvn clean test -Dtest=UserServiceTest#shouldCreateUser，绕过 IDE 干扰，看真实输出

最容易被忽略的是测试类路径和构建工具配置的耦合点——不是写对了注解就能跑，而是整个工具链得对齐。哪怕只差一个 testRuntimeOnly，@Test 就只是个普通方法。