借助工具快速诊断

深入代码前先利用现有工具获取初步线索能事半功倍。

IDE的实时检查：像IntelliJ IDEA这类现代IDE能够实时检测注解格式错误、参数化测试缺少数据源、断言参数顺序错误等问题。看到代码上的红色波浪线或黄色高亮时，将鼠标悬停上去，一般IDE会直接给出修改建议。

Maven 依赖树分析：当怀疑依赖冲突或版本不正确时，在项目根目录下运行 mvn dependency:tree 命令，可以打印出完整的依赖层级关系。这是定位类找不到或方法不存在错误的高效手段。

阅读错误堆栈：遇到异常时，不要只看第一行错误描述。请从堆栈的最底部（Caused by 部分）开始向上排查，底层的异常往往是问题的根本原因。

代码方面错误

注解相关错误

“no runnable methods” 错误

这是最常见的JUnit错误，一般伴随着java.lang.Exception: No runnable methods的输出是：JUnit 运行器扫描了测试类，但没有发现任何合法的、可供执行的测试方法。

排查此问题时依次查看以下几点：

检查测试方法是不是使用了正确的@Test注解。如果方法没有标注任何注解，JUnit 自然会忽略它。

必须确定导入的包途径正确。JUnit 4 使用的是 org.junit.Test，而 JUnit 5 使用的是 org.junit.jupiter.api.Test。在混用 JUnit 4 和 JUnit 5 的过渡项目中，极易因为 IDE 的自动导包功能引入了错误的注解包，导致一侧的测试全部失效。

还需要留意是不是误引入了 TestNG 框架的 @Test 注解（包途径一般包含 org.testng）。

方法签名也必须符合规范。在JUnit 5中，测试方法必须是void且无参的（除非使用了参数化测试注解）。如果方法声明了返回值或参数，JUnit将无法识别。

参数化测试常见错误

参数化测试的配置相对复杂，更容易出错。如果参数化测试完全无法运行，先检查是不是在pom.xml或build.gradle中正确引入了junit-jupiter-params依赖，是JUnit 5参数化测试的引擎。

在JUnit 4环境下，如果使用了@RunWith(Parameterized.class) 但测试失败，一般是因为缺少数据源。JUnit 4要求必须存在一个标注了 @Parameters 的公共静态方法，且返回 Iterable<Object[]> 或二维数组来提供数据。

在JUnit 5环境下，常见的错误是同时在一个方法上标注了@Test和@ParameterizedTest。这是不允许的，参数化测试只能使用 @ParameterizedTest 注解。另一个容易忽视的问题是参数类型不一致。如，使用 @ValueSource(ints = {1, 2, 3}) 注解时，测试方法的参数类型必须是int或Integer，String类型就会导致参数分析失败。

断言失败错误

断言参数顺序错误

当断言失败时，控制台输出的预期值和实际值如果看起来是颠倒的，请不要怀疑是代码思路写反了，极大概率是assertEquals方法的参数顺序写错了。正确签名是 assertEquals(expected, actual)，即第一个参数是预期结果，第二个参数是实际结果。如果写反了，测试失败时的错误消息就会让人感到困惑，增加不必要的排查时间。

数组断言失败

在对数组内容进行证实时，如果使用了普通的assertEquals，JUnit 比较的是数组对象的引用地址而不是内容，这几乎总是会失败。必须使用专用的assertArrayEquals方法。方法要求数组元素的顺序和类型必须完全一致，如果只是元素相同但顺序不同，断言依然会失败。

正确测试异常弹出

测试代码是不是按预期抛出异常时，不推荐使用传统的try-catch块去捕获并手动断言，也不推荐对可能抛出异常的方法返回值做断言。JUnit 5提供了更优雅的方式-assertThrows方法。做法如下：

java

// 推荐做法（JUnit 5）

@Test

void shouldThrowException() {

    assertThrows(IllegalArgumentException.class, () -> {

        calculator.divide(10, 0);

    });

}

空指针异常（NPE）

空指针异常在测试中经常发生，不同场景下原因各不相同。

在Spring测试环境下，如果通过@Autowired 注入的服务为null，几乎可以肯定是测试类未能正确加载Spring上下文。请检查类上是不是添加了@SpringBootTest 注解（用于集成测试）或 @ExtendWith(SpringExtension.class) 注解（用于切片测试）。

如果在@BeforeEach或@BeforeAll标注的初始化方法中发生了NPE，说明资源初始化思路本身存在缺陷。需要检查初始化代码是不是依赖于尚未就绪的外部环境，或者是不是在初始化过程中抛出了未被捕获的异常。

JUnit 5的某些早期版本（如 1.11.x）存在已知缺陷：当测试类位于Java默认包（无包名）下且继承自非默认包的父类时，测试发现阶段会抛出NPE。如果遇到此诡异情况，修复方式是将测试类移入一个命名包中，或者升级JUnit 5到最新版本。

其他代码方面常见问题

除了上述问题，还有一些细节需要注意。

关于方法的可见性：JUnit 4要求测试方法必须是public的，如果使用了包私有或private修饰符，运行时会报No runnable methods错误。而JUnit 5放宽了限制，支持包私有方法，但仍建议保持public以避免不必要的混淆。

关于测试类的命名：虽然JUnit没有强制要求测试类必须以 Test 结尾，但某些创建工具或插件（尤其是针对特定框架如 MyBatis 的生成器）会依赖此命名约定来扫描测试类。如果发现Maven/Gradle命令找不到测试，而IDE可以运行，可以尝试将类名改为以Test结尾的格式。

关于未处理异常：如果测试方法抛出了未声明的受检异常（Checked Exception）且未被捕获，JUnit 会将其视为测试失败。正确的处理方式是：如果预期会抛出异常，请使用 assertThrows 进行包装断言；如果是意外异常，则应在方法签名上声明 throws。

运行时错误

InitializationError

当测试启动就崩溃，并弹出 java.lang.Exception: InitializationError，表示测试类的初始化过程失败了。通过查看伴随的Caused by信息可以锁定具体原因。

如果提示 NoClassDefFoundError: org/hamcrest/SelfDescribing，这是因为 JUnit 4 依赖于 Hamcrest 一致器库。在 Maven 中，除了引入 junit 依赖外，还必须同时引入 hamcrest-core 依赖，否则运行时类途径中会缺失相关类。

如果是 Spring 测试，InitializationError 一般意味着 ApplicationContext 加载失败。请检查 @ContextConfiguration 指定的配置文件途径是不是正确，或者是不是存在 Bean 定义冲突、循环依赖等问题。

此外，测试类自身的构造器或静态初始化块（static { ... }）中如果存在未捕获的异常，也会导致此错误。

测试未被发现/不运行

这类问题往往和环境配置或版本兼容性有关。

在升级到JUnit 5.12.0 及更高版本后，很多用户会突然遇到 TestEngine with ID 'junit-jupiter' failed to discover tests 的错误。这是因为新版本对引擎版本的一致性要求更严格了。最好实践是引入JUnit BOM（Bill of Materials）来统一管理所有JUnit相关组件的版本，避免junit-platform-engine 和 junit-platform-launcher 等底层包的版本不一致。

对于 Maven 项目，如果使用了较老版本的 maven-surefire-plugin，可能根本不认识JUnit 5。请保证将该插件升级到 3.5.3 或更高版本。

对于 Gradle 项目，需要显式添加平台启动器依赖作为测试运行时依赖，如：testRuntimeOnly 'org.junit.platform:junit-platform-launcher'。

测试超时

如果某个测试方法执行时间过长，甚至陷入死循环，会导致整个测试套件被卡住。在JUnit 5中，可以通过在方法或类上添加@Timeout注解来强制设置一个超时阈值。超过设定时间后，测试线程会被强制中断并标记为失败。如果测试代码中捕获了中断异常（InterruptedException）但什么也没做（空 catch 块），超时机制可能失效，代码会继续运行。

ComparisonFailure

当看到 org.junit.ComparisonFailure: expected:<...> but was:<...> 时，这是最常见的字符串断言失败。排查时先确定assertEquals参数顺序无误，然后检查待测代码中是不是存在多余的换行符、空格、或大小写转换思路。对于复杂对象的比较，如果频繁出现差别难以定位，建议重写该对象的 equals() 和 hashCode() 方法，而不是依赖默认的根据引用地址的比较。

环境配置问题

依赖缺失或冲突

依赖问题是测试失败的常见幕后黑手。如果编译时报程序包 org.junit 不存在，检查pom.xml中是不是正确添加了JUnit依赖，并且其 <scope> 是test。

如果运行时弹出 NoClassDefFoundError，说明编译时有的类在运行时找不到了，一般是依赖被标记为 provided 或 test 作用域，但在主代码中被引用。

如果抛出 NoSuchMethodError，这是典型的编译时和运行时 JUnit 版本不一致的症状。如，代码是针对JUnit 5.10 编写和编译的，但运行环境中引入了JUnit 5.8 的 jar包。解决方案是使用 Maven 的 dependencyManagement 或 Gradle的强制版本声明来统一版本。

另外，如果项目中同时存在JUnit 4和JUnit 5的依赖，可能会导致测试引擎混乱。如果确定只使用JUnit 5编写新测试，建议排除掉 junit:junit 这种老依赖。如果必须保留JUnit 4的老测试，则需要同时保留junit-vintage-engine来提供向后兼容的运行环境。

正确添加JUnit 5依赖：

为了彻底解决版本冲突，强烈建议使用 JUnit BOM 来管理版本。

xml

<dependencyManagement>

    <dependencies>

        <dependency>

            <groupId>org.junit</groupId>

            <artifactId>junit-bom</artifactId>

            <version>5.12.0</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

    </dependencies>

</dependencyManagement>

<dependencies>

    <dependency>

        <groupId>org.junit.jupiter</groupId>

        <artifactId>junit-jupiter</artifactId>

        <scope>test</scope>

    </dependency>

</dependencies>

版本兼容性问题

不同框架组合时有特定的版本要求。

对于Spring Boot项目，Spring Boot 2.2.x 及以上版本默认集成了JUnit 5支持。如果还在使用Spring Boot 1.x，则只能使用JUnit 4。

当使用Mockito配合JUnit 5时，不能在类上写 @RunWith(MockitoJUnitRunner.class)（这是 JUnit 4 的写法），而应该使用 @ExtendWith(MockitoExtension.class)。

Java版本也是一个硬性限制。JUnit 5 要求最低Java 8环境，如果在Java 7或更低版本中运行，会直接报错。

Spring Boot特定问题

在Spring Boot测试中，问题就是@Autowired注入的服务为 null。原因是测试类没有加载Spring上下文。如果只是单纯的单元测试不要加载上下文，直接手动new对象并手动注入Mock对象即可。如果是集成测试，则必须在测试类上添加 @SpringBootTest注解。

Spring Boot 3.6.0 版本在某些边缘情况下和JUnit Jupiter的@TestInstance(Lifecycle.PER_CLASS) 方式存在兼容性小bug。如果发现采用类单例方式运行测试时出现了不可解释的失败，可以尝试临时切换回默认的 Lifecycle.PER_METHOD方式。

IDE问题

如果代码在IDE里能跑通，但命令行mvn test失败，一般是依赖作用域或类途径顺序不同导致的。反之如果IDE里全是红叉，先尝试点击 Maven/Gradle 工具的刷新/重新导入按钮。

在IntelliJ IDEA中，即使依赖正确，IDE 缓存也可能损坏，导致无法分析 org.junit.jupiter.api。可以通过 File -> Invalidate Caches and Restart 解决。

在Eclipse中，如果测试类不被识别，请右键点击项目，选择 Build Path -> Configure Build Path，确定测试类所在的文件夹被标记为源文件夹（Source Folder）。

调试方法：

使用断点调试：在@BeforeEach初始化方法或测试方法第一行设置断点，逐行观察变量状态的变化。

从底部分析堆栈：面对几十行的错误堆栈，请直接滚动到最下方的Caused by: 部分。

编写最小化测试：暂时注释掉复杂的业务思路，只写一个最简单的assertTrue(true) 测试。如果这个测试都跑不起来一定是环境或框架配置的问题，不是业务代码的思路错误。

查看版本发布说明：在升级JUnit或Spring Boot大版本之前，必须翻阅官方的 Release Notes 或 Migration Guide。很多时候问题不是代码写错了，而是框架的默认行为发生了变更。