JUnit 5 版本依赖冲突导致测试无法执行

Question

在多模块Maven项目中，常因不同模块引入不兼容的JUnit 5版本（如junit-jupiter-api 5.7.0 与 junit-jupiter-engine 5.5.0）导致测试执行失败。尽管API版本一致，但引擎版本不匹配会引发 `ClassNotFoundException` 或 `TestEngine` 无法加载的问题。该冲突通常由传递依赖引入，难以察觉，最终导致构建通过但测试不执行或报“No tests were found”错误。

Answer 1

一、问题背景与典型现象

在大型多模块Maven项目中，JUnit 5作为主流测试框架被广泛使用。然而，由于各子模块可能依赖不同的第三方库，这些库又会传递性地引入不同版本的JUnit组件（如junit-jupiter-api和junit-jupiter-engine），极易导致版本不一致。

一个典型的场景是：模块A显式引入了junit-jupiter-api:5.7.0，而其依赖的模块B通过传递依赖引入了junit-jupiter-engine:5.5.0。尽管API版本较高，但底层执行引擎版本偏低，导致JVM在运行测试时无法正确加载TestEngine实现类，抛出ClassNotFoundException或静默失败——表现为“No tests were found”。

此类问题具有高度隐蔽性，因为Maven构建过程仍能成功（编译阶段仅需API），但测试阶段却失效，严重影响CI/CD流程的可靠性。

二、根本原因分析

1. JUnit 5架构分层机制：JUnit 5由多个独立模块组成，核心包括：
   • junit-jupiter-api：提供注解与编程模型
   • junit-jupiter-engine：负责测试发现与执行
   • junit-platform-launcher：启动平台服务
2. 版本对齐要求：API与Engine虽可独立发布，但在运行时必须保持版本兼容。官方推荐两者使用完全相同的版本号。
3. 依赖仲裁缺失：Maven默认采用“最近路径优先”策略解析冲突依赖，若低版本engine出现在较深依赖树中，不会被自动排除。
4. 插件配置盲区：maven-surefire-plugin未强制指定engine版本，导致其依赖classpath上的不稳定版本。

三、诊断方法与检测手段

工具/命令	用途说明	示例命令
mvn dependency:tree	查看完整依赖树，定位重复引入	mvn dependency:tree | grep junit
Maven Enforcer Plugin	强制统一版本规则	配置dependencyConvergence
IDE依赖分析视图	图形化展示冲突	IntelliJ → Maven → Show Dependencies
Bytecode Viewer	检查实际加载的class来源	Jar Explorer + Classpath Scan

四、解决方案与最佳实践

<properties>
    <junit.version>5.9.3</junit.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

通过<dependencyManagement>在父POM中统一管理版本，确保所有子模块继承一致的JUnit版本策略。

五、自动化防护机制设计

为防止未来再次出现此类问题，建议集成以下防护措施：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <id>enforce</id>
            <configuration>
                <rules>
                    <dependencyConvergence/>
                    <bannedDependencies>
                        <excludes>
                            <exclude>org.junit.jupiter:junit-jupiter-engine:5.[0-4].*</exclude>
                        </excludes>
                    </bannedDependencies>
                </rules>
            </configuration>
            <goals><goal>enforce</goal></goals>
        </execution>
    </executions>
</plugin>

六、可视化依赖冲突流程图

graph TD
            A[Root POM] --> B(Module A)
            A --> C(Module B)
            A --> D(Module C)
            B --> E[junit-jupiter-api:5.7.0]
            C --> F[junit-jupiter-engine:5.5.0]
            D --> G[third-party-lib]
            G --> F
            H[maven-surefire-plugin] --> I{Classpath}
            I --> E
            I --> F
            F -.-> J[Test Execution Failure]
            style J fill:#f8b8c8,stroke:#333