从JUnit 4迁移到JUnit 5：完整指南与实战经验分享 1. 项目概述为什么我们需要从 JUnit 4 迁移到 JUnit 5如果你和我一样在 Java 项目里泡了有些年头那 JUnit 4 绝对是你最熟悉的“老伙计”。从Test到Before这套 API 我们闭着眼睛都能写出来。但技术栈的演进从不等人当 JUnit 5 带着全新的架构和特性登场时我们这些老开发者就面临一个现实问题是继续守着成熟的 JUnit 4还是拥抱更现代、更强大的 JUnit 5这个迁移过程远不止是改几个注解那么简单它涉及到依赖管理、测试架构、扩展机制乃至团队协作习惯的全面升级。今天我就结合自己主导的几个大型项目迁移经验把从 JUnit 4 平稳过渡到 JUnit 5 的完整路径、核心差异、实操细节以及那些容易踩的“坑”给你掰开揉碎了讲清楚。无论你是正在规划迁移的技术负责人还是需要动手改造的一线开发者这篇文章都能给你一份可直接“抄作业”的指南。2. 迁移前的战略规划与依赖准备在动手改代码之前清晰的战略规划能避免后续的混乱。JUnit 5 的设计哲学是“平滑迁移”它允许 JUnit 4 和 JUnit 5 的测试用例在同一个项目中并存运行。这为我们制定“渐进式”迁移策略提供了可能。2.1 理解 JUnit 5 的模块化架构JUnit 4 是一个“大一统”的库而 JUnit 5 则拆分为三个清晰独立的模块这是理解其所有变化的基础JUnit Platform这是测试执行的基石。它定义了在 JVM 上启动测试框架的稳定 API。你的构建工具Maven、Gradle或 IDEIntelliJ IDEA、Eclipse通过这个平台来发现和执行测试。你可以把它想象成测试世界的“操作系统”。JUnit Jupiter这是编写新测试和扩展的核心编程模型和 API。所有新的注解如Test、BeforeEach和断言Assertions都在这个模块里。我们迁移时主要就是把 JUnit 4 的代码改写成符合 Jupiter API 的代码。JUnit Vintage这是一个为了向后兼容而存在的测试引擎。它的唯一职责就是识别和执行那些用 JUnit 3 或 JUnit 4 编写的旧测试。在迁移过渡期我们必须依赖它来保证旧的测试用例还能正常运行。这个架构带来的最大好处是解耦。比如你可以用 Jupiter 写新测试同时用 Vintage 跑旧测试互不干扰。这也意味着你的构建工具和 IDE 只需要与 JUnit Platform 对接一次就能支持所有基于 JUnit 的测试引擎。2.2 构建工具依赖配置详解依赖配置是迁移的第一步也是最容易出错的一步。配置错了测试可能直接跑不起来。对于 Maven 项目你需要在pom.xml中配置maven-surefire-plugin版本 2.22.0 或以上以支持 JUnit Platform并添加必要的依赖。properties junit.jupiter.version5.10.0/junit.jupiter.version !-- 建议使用较新稳定版 -- /properties build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId version3.1.2/version !-- 使用较新版本以获得更好支持 -- configuration !-- 确保平台被激活 -- /configuration /plugin /plugins /build dependencies !-- JUnit Jupiter API 和引擎用于编写和运行JUnit5测试 -- dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter/artifactId version${junit.jupiter.version}/version scopetest/scope /dependency !-- JUnit Vintage 引擎用于运行JUnit4测试 -- dependency groupIdorg.junit.vintage/groupId artifactIdjunit-vintage-engine/artifactId version${junit.jupiter.version}/version scopetest/scope /dependency /dependencies注意junit-jupiter依赖本身是一个聚合依赖BOM它包含了junit-jupiter-api编写测试、junit-jupiter-engine运行测试和junit-jupiter-params参数化测试。通常直接引入它就够了。对于 Gradle 项目配置更为简洁。你需要在build.gradle或build.gradle.kts中启用 JUnit Platform 并添加依赖。plugins { id java } test { useJUnitPlatform() // 这是关键启用JUnit Platform支持 } dependencies { // JUnit Jupiter testImplementation platform(org.junit:junit-bom:5.10.0) // 使用BOM管理版本 testImplementation org.junit.jupiter:junit-jupiter // JUnit Vintage testRuntimeOnly org.junit.vintage:junit-vintage-engine }这里有一个非常重要的实操心得在大型多模块项目中我强烈建议在父 POMMaven或使用subprojects/allprojectsGradle中统一配置这些依赖和插件。这能确保所有子模块的测试环境一致避免因配置分散导致的“这个模块能跑那个模块报错”的诡异问题。2.3 制定可行的迁移路线图依赖配好测试能同时跑了接下来就是制定代码层面的迁移计划。我推荐采用“由外向内由简到繁”的策略第一阶段并行运行建立信心。确保在 Vintage 引擎的支持下所有旧的 JUnit 4 测试用例依然能 100% 通过。这是迁移的底线。第二阶段新测试新标准。所有新增的测试用例一律使用 JUnit 5Jupiter编写。让团队逐渐熟悉新的 API。第三阶段批量处理简单迁移。利用 IDE 的“查找替换”功能批量修改那些只涉及基础注解如Test、Before和断言Assert-Assertions的测试类。这部分改动小风险低。第四阶段攻坚复杂逻辑。集中处理使用了RunWith、自定义Rule、复杂参数化测试Parameterized的“硬骨头”类。这类测试需要深入理解 JUnit 5 的扩展模型建议由经验丰富的同事主导。第五阶段清理与优化。移除junit-vintage-engine依赖清理可能残留的 JUnit 4 依赖如junit:junit并统一代码风格例如将public测试方法改为包私有或protected。这个路线图不是线性的你可以根据项目模块的优先级分模块进行。例如先迁移一个相对独立、测试覆盖率高的小模块积累经验后再推向核心模块。3. 注解、断言与假设的迁移实战这是迁移工作中量最大但也是最机械的部分。掌握了规律大部分改动可以靠 IDE 的“重构”功能半自动完成。3.1 生命周期注解的一一对应JUnit 4 和 JUnit 5 的生命周期注解在功能上是对应的但包名和部分名称发生了变化。下表是核心映射关系JUnit 4 注解 (org.junit)JUnit 5 注解 (org.junit.jupiter.api)作用域与说明TestTest标记测试方法。注意JUnit 5 的Test不再有expected和timeout属性。BeforeBeforeEach每个测试方法之前执行。命名更语义化。AfterAfterEach每个测试方法之后执行。BeforeClassBeforeAll所有测试方法之前执行一次。方法必须是static。AfterClassAfterAll所有测试方法之后执行一次。方法必须是static。IgnoreDisabled禁用测试类或方法。新名称更直观。实操要点包名变更这是最普遍的改动。将import org.junit.Test;改为import org.junit.jupiter.api.Test;。IDE 的“优化导入”Optimize Imports功能可以帮你快速清理无效导入。方法可见性JUnit 4 要求测试方法必须是public。JUnit 5 放宽了限制可以是public,protected, 包私有默认但不能是private。我个人的习惯是改为包私有这能更好地体现测试是类的内部行为也减少了不必要的公开 API。// JUnit 4 public class OldTest { Test public void testSomething() { ... } } // JUnit 5 (推荐) class NewTest { Test void testSomething() { ... } // 包私有更简洁 }3.2 断言的升级与 Lambda 表达式妙用断言是测试的灵魂。JUnit 5 的断言 API 移到了org.junit.jupiter.api.Assertions类中。大部分方法是相似的但有两个关键改进可选消息参数位置变化在 JUnit 4 中可选的失败消息是第一个参数。在 JUnit 5 中它被移到了最后一个参数。这个改动更符合“可选参数放最后”的编程习惯但也是迁移时编译错误的主要来源之一。// JUnit 4 import org.junit.Assert; Assert.assertEquals(The user ID should match, expectedUserId, actualUserId); // JUnit 5 import org.junit.jupiter.api.Assertions; Assertions.assertEquals(expectedUserId, actualUserId, The user ID should match);支持 Lambda 表达式生成消息这是 JUnit 5 充分利用 Java 8 特性的一个亮点。你可以传递一个SupplierString作为失败消息。这样只有在断言失败时消息字符串才会被计算避免了无谓的字符串拼接开销尤其在循环或数据驱动的测试中性能提升明显。// 低效做法JUnit 4风格无论断言是否失败都会进行字符串拼接 Assertions.assertEquals(expected, actual, Expected: expected , but was: actual); // 高效做法JUnit 5风格仅在断言失败时计算消息 Assertions.assertEquals(expected, actual, () - Expected: expected , but was: actual);常见问题排查如果你在迁移后遇到关于assertThat的编译错误那是因为 JUnit 5 不再在自身的Assertions类中提供 Hamcrest 风格的assertThat方法。你需要直接使用 Hamcrest 的MatcherAssert。// JUnit 4 import org.junit.Assert; import static org.hamcrest.CoreMatchers.is; Assert.assertThat(actual, is(expected)); // JUnit 5 import org.hamcrest.MatcherAssert; import static org.hamcrest.CoreMatchers.is; MatcherAssert.assertThat(actual, is(expected));3.3 假设Assumptions的细微变化假设用于在特定条件不满足时跳过测试。它的迁移模式与断言类似包名变更消息参数移至最后。// JUnit 4 import org.junit.Assume; Assume.assumeTrue(Test skipped: not in CI environment, CI.equals(System.getenv(ENV))); // JUnit 5 import org.junit.jupiter.api.Assumptions; Assumptions.assumeTrue(CI.equals(System.getenv(ENV)), () - Test skipped: not in CI environment);需要注意的是JUnit 4 中的assumeNotNull和assumeNoException方法在 JUnit 5 中被移除了。你需要用assumeTrue配合相应的条件判断来达到相同目的。// 替代 assumeNotNull Assumptions.assumeTrue(object ! null, Object must not be null); // 替代 assumeNoException需要自己捕获并判断 try { somePotentiallyFailingOperation(); } catch (Exception e) { Assumptions.assumeTrue(false, Operation should not throw exception: e.getMessage()); }4. 高级特性迁移Runner、Rule 与扩展模型这是迁移中最具挑战性的部分因为 JUnit 5 用一套全新的、更强大的扩展模型Extension Model取代了 JUnit 4 的 Runner 和 Rule 机制。4.1 告别 RunWith拥抱 ExtendWith在 JUnit 4 中RunWith是一个重量级的机制一个测试类只能指定一个 Runner。这导致如果你想同时使用 Spring 和参数化测试等功能时会非常棘手通常需要自定义 Runner 或使用“规则链”等变通方案很复杂。JUnit 5 的ExtendWith是轻量级的一个测试类可以声明多个扩展。这些扩展通过关注点分离的方式协同工作比如一个扩展处理依赖注入另一个扩展处理参数解析。Spring 测试的迁移 如果你的项目使用 Spring Test迁移相对直接。// JUnit 4 Spring import org.junit.runner.RunWith; import org.springframework.test.context.junit4.SpringJUnit4ClassRunner; RunWith(SpringJUnit4ClassRunner.class) ContextConfiguration(classes TestConfig.class) public class MySpringTest { ... } // JUnit 5 Spring (需要 Spring 5.2 以获得最佳支持) import org.junit.jupiter.api.extension.ExtendWith; import org.springframework.test.context.junit.jupiter.SpringExtension; ExtendWith(SpringExtension.class) ContextConfiguration(classes TestConfig.class) class MySpringTest { ... }注意如果你不幸还停留在 Spring 4.x官方没有提供直接的 JUnit 5 扩展。你需要依赖一个第三方库如spring-test-junit5但这只是过渡方案强烈建议将 Spring 升级到 5.x 或更高版本。Mockito 测试的迁移 Mockito 也提供了官方的 JUnit 5 扩展。// JUnit 4 Mockito import org.junit.runner.RunWith; import org.mockito.junit.MockitoJUnitRunner; RunWith(MockitoJUnitRunner.class) public class MyMockitoTest { Mock private Dependency dependency; InjectMocks private ServiceUnderTest service; Test public void test() { ... } } // JUnit 5 Mockito import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.junit.jupiter.MockitoExtension; ExtendWith(MockitoExtension.class) class MyMockitoTest { Mock private Dependency dependency; InjectMocks private ServiceUnderTest service; Test void test() { ... } }你需要添加mockito-junit-jupiter依赖。dependency groupIdorg.mockito/groupId artifactIdmockito-junit-jupiter/artifactId version5.7.0/version !-- 使用与Mockito核心一致的版本 -- scopetest/scope /dependency4.2 规则Rule的迁移路径JUnit 4 的 Rule 机制非常灵活JUnit 5 通过扩展模型来替代它。迁移支持分为两步走第一步利用迁移支持模块快速兼容对于常用的内置 Rule如TemporaryFolder,ExpectedException,ErrorCollectorJUnit 5 提供了一个junit-jupiter-migrationsupport模块。添加依赖后你可以在测试类上使用EnableRuleMigrationSupport注解让这些 JUnit 4 的 Rule 在 JUnit 5 环境下继续工作。dependency groupIdorg.junit.jupiter/groupId artifactIdjunit-jupiter-migrationsupport/artifactId version5.10.0/version scopetest/scope /dependencyimport org.junit.jupiter.migrationsupport.rules.EnableRuleMigrationSupport; import org.junit.Rule; import org.junit.rules.ExpectedException; EnableRuleMigrationSupport // 启用规则迁移支持 class TemporaryCompatibilityTest { Rule public ExpectedException thrown ExpectedException.none(); Test void testException() { thrown.expect(IllegalArgumentException.class); thrown.expectMessage(invalid); throw new IllegalArgumentException(invalid argument); } }这是一个临时方案目的是让你能快速让测试跑起来为后续彻底重构争取时间。第二步重写为原生扩展彻底迁移长期来看你应该将 Rule 重写为 JUnit 5 的原生扩展。这需要实现特定的扩展接口如BeforeEachCallback、AfterEachCallback等。以TemporaryFolderRule 为例JUnit 5 提供了官方的TempDir扩展用法更简洁// JUnit 4 Rule public class TempFileTest { Rule public TemporaryFolder folder new TemporaryFolder(); Test public void test() throws IOException { File file folder.newFile(test.txt); // 使用 file } } // JUnit 5 Extension (原生支持) import org.junit.jupiter.api.io.TempDir; import java.nio.file.Path; class TempFileTest { TempDir Path tempDir; // 可以注入 Path 或 File Test void test() throws IOException { Path file tempDir.resolve(test.txt); Files.writeString(file, content); // 使用 file } }对于自定义的 Rule你需要分析其apply方法中的逻辑看它是在测试执行的哪个阶段介入如之前、之后、处理异常等然后实现对应的回调接口。例如一个在测试前后记录日志的 Rule// JUnit 4 自定义 Rule public class LoggingRule implements TestRule { Override public Statement apply(Statement base, Description description) { return new Statement() { Override public void evaluate() throws Throwable { System.out.println(Starting test: description.getMethodName()); try { base.evaluate(); } finally { System.out.println(Finished test: description.getMethodName()); } } }; } } // JUnit 5 自定义 Extension public class LoggingExtension implements BeforeEachCallback, AfterEachCallback { Override public void beforeEach(ExtensionContext context) { System.out.println(Starting test: context.getDisplayName()); } Override public void afterEach(ExtensionContext context) { System.out.println(Finished test: context.getDisplayName()); } } // 使用扩展 ExtendWith(LoggingExtension.class) class MyTest { ... }4.3 参数化测试的范式转变JUnit 4 的参数化测试通过RunWith(Parameterized.class)和一堆样板代码实现体验不佳。JUnit 5 的ParameterizedTest是质的飞跃它支持多种数据源ValueSource,CsvSource,MethodSource等写法优雅灵活。// JUnit 4 参数化测试 (冗长) RunWith(Parameterized.class) public class FibonacciTest { Parameterized.Parameters(name fib({0}) {1}) public static CollectionObject[] data() { return Arrays.asList(new Object[][] { {0, 0}, {1, 1}, {2, 1}, {3, 2}, {4, 3}, {5, 5} }); } private int input; private int expected; public FibonacciTest(int input, int expected) { this.input input; this.expected expected; } Test public void test() { assertEquals(expected, Fibonacci.compute(input)); } } // JUnit 5 参数化测试 (简洁清晰) import org.junit.jupiter.params.ParameterizedTest; import org.junit.jupiter.params.provider.MethodSource; import java.util.stream.Stream; class FibonacciTest { static StreamArguments dataProvider() { return Stream.of( Arguments.of(0, 0), Arguments.of(1, 1), Arguments.of(2, 1), Arguments.of(3, 2), Arguments.of(4, 3), Arguments.of(5, 5) ); } ParameterizedTest(name fib({0}) {1}) // 支持自定义显示名称 MethodSource(dataProvider) void testFibonacci(int input, int expected) { assertEquals(expected, Fibonacci.compute(input)); } }迁移时你需要将RunWith(Parameterized.class)替换为ParameterizedTest并将数据提供方法改造为返回Stream、Iterable等类型。MethodSource是最接近 JUnit 4 风格的方式但我强烈建议你探索一下CsvSource或CsvFileSource它们对于简单的数据对更加直观。ParameterizedTest CsvSource({ 0, 0, 1, 1, 2, 1 }) void testFibonacciWithCsv(int input, int expected) { assertEquals(expected, Fibonacci.compute(input)); }5. 迁移后的验证、常见问题与性能调优当所有代码都迁移完毕后工作只完成了一半。彻底的验证和优化才能确保迁移是成功且可持续的。5.1 构建与测试验证全量测试执行在移除junit-vintage-engine依赖之前运行项目的所有测试套件。确保通过率与迁移前完全一致。不仅要关注单元测试还要关注集成测试、端到端测试。IDE 兼容性检查在 IntelliJ IDEA 或 Eclipse 中打开项目确保 IDE 能正确识别并运行 JUnit 5 测试测试结果窗口能正常显示。有时需要刷新项目或重新导入 Maven/Gradle 配置。持续集成CI流水线验证在 CI 环境中如 Jenkins、GitLab CI触发一次完整的构建。确保测试在无头headless环境、不同的 JDK 版本下也能正确执行。CI 环境往往能暴露出本地环境没有的依赖或配置问题。5.2 常见问题排查实录以下是我在迁移过程中遇到的一些典型问题及其解决方案问题一测试类不执行控制台无输出。可能原因构建工具未正确配置 JUnit Platform。对于 Maven检查maven-surefire-plugin版本需 2.22.0及配置。对于 Gradle确认test块中已配置useJUnitPlatform()。排查命令运行mvn test -DtestYourTestClass或gradle test --tests YourTestClass观察详细日志。问题二BeforeAll/AfterAll方法必须声明为static的编译错误。原因JUnit 5 要求这些生命周期方法必须是static的因为它们在所有测试实例创建之前/之后执行。而 JUnit 4 的BeforeClass也有此要求但有时容易被忽略。解决将这些方法改为static。如果方法中需要访问非静态的测试实例字段说明你的测试设计可能需要调整考虑使用BeforeEach进行初始化或使用TestInstance(Lifecycle.PER_CLASS)注解改变测试实例的生命周期。问题三使用了ExtendWith(SpringExtension.class)但Autowired字段为null。可能原因测试类本身没有被 Spring 的组件扫描到或者上下文配置有误。解决确保测试类位于组件扫描的路径下或使用ContextConfiguration明确指定配置类。另外检查 Spring 版本是否 5.2。问题四迁移后某些基于时间的测试如Timeout变得不稳定。原因JUnit 4 的Test(timeout...)和 JUnit 5 的assertTimeout行为有细微差别。JUnit 5 的默认超时检查机制可能更严格或者线程模型不同。解决使用assertTimeoutPreemptively。它与 JUnit 4 的timeout行为更相似会在独立的线程中执行任务并提前中断。Test void shouldTimeout() { // 如果任务超时会从外部中断它 Assertions.assertTimeoutPreemptively(Duration.ofMillis(100), () - { Thread.sleep(200); // 这个睡眠会被中断 }); }5.3 性能考量与最佳实践迁移到 JUnit 5 本身不会带来显著的性能下降但新的特性如果用得好反而能提升测试体验。并行测试执行JUnit 5 原生支持并行运行测试。对于大型测试套件这能极大缩短反馈时间。在junit-platform.properties文件中配置# 启用并行执行 junit.jupiter.execution.parallel.enabled true junit.jupiter.execution.parallel.mode.default concurrent注意并行测试要求测试之间是独立的不能有共享状态。需要仔细评估你的测试用例。按标签Tag过滤测试JUnit 5 的Tag注解比 JUnit 4 的Category更灵活使用字符串而非类。你可以用它将测试分为“快”、“慢”、“集成”、“数据库”等类别然后在构建时选择性地运行。Test Tag(fast) void fastTest() { ... } Test Tag(integration) Tag(slow) void integrationTest() { ... }在 Maven 中运行特定标签的测试mvn test -Dgroupsfast mvn test -DexcludedGroupsslow,integration测试实例生命周期默认情况下JUnit 5 为每个测试方法创建一个新的测试类实例Lifecycle.PER_METHOD。如果你有大量且昂贵的初始化逻辑可以考虑使用TestInstance(Lifecycle.PER_CLASS)让整个测试类共享一个实例。这能减少初始化开销但要格外小心测试间的状态污染。TestInstance(TestInstance.Lifecycle.PER_CLASS) // 整个类一个实例 class SharedResourceTest { private ExpensiveResource resource; BeforeAll void init() { // 现在 BeforeAll 可以不是static的了 resource new ExpensiveResource(); } Test void test1() { resource.doSomething(); } Test void test2() { resource.doSomethingElse(); } }迁移到 JUnit 5 不是一个简单的版本升级而是一次对测试基础设施的现代化改造。它带来的 Lambda 支持、扩展模型、参数化测试改进等特性能让你写出更简洁、更强大、更易维护的测试代码。虽然迁移过程需要投入精力尤其是处理那些复杂的 Runner 和 Rule但这份投入是值得的。从我经历的项目来看迁移完成后团队编写新测试的效率提高了测试代码的可读性也更强了。最关键的是你为项目拥抱更现代的 Java 生态如模块化、GraalVM 等扫清了一个障碍。