JUnit 4 到 JUnit 5：Java 测试框架的迁移与实战

Mon, 14 Sep 2020 15:30:00 +0800

为什么要从 JUnit 4 升级到 JUnit 5

很多团队的 pom.xml 里至今还躺着 junit:junit:4.x。JUnit 4 已经停止主线维护多年，但因为足够"够用"，迟迟没人动。

升级到 JUnit 5 不是为了赶时髦，而是它解决了 JUnit 4 时代积攒的几个核心痛点：

架构臃肿：JUnit 4 把整个框架塞在一个 jar 里，运行器（Runner）和扩展点（Rule）冲突，不能叠加
没有原生参数化测试：要靠 Parameterized Runner，写法别扭
嵌套测试丑陋：要用 @RunWith(Enclosed.class)
断言能力弱：复合断言、异常断言要靠第三方库
不支持 Java 8+ Lambda：很多优雅写法用不上

JUnit 5 推倒重来，拆成三个模块：

flowchart LR
 Platform["JUnit Platform
(运行平台)"]
 Jupiter["JUnit Jupiter
(JUnit 5 编程模型)"]
 Vintage["JUnit Vintage
(兼容跑 JUnit 3/4)"]

 Platform --> Jupiter
 Platform --> Vintage

Platform：测试引擎的标准接口，IDE/Maven/Gradle 都对它编程
Jupiter：你写的 @Test 用的就是它
Vintage：让 JUnit 4 测试在 Platform 上继续跑，平滑迁移

下面我们用一个个能跑的例子，把 JUnit 5 的常用与进阶用法过一遍。

一、最小可运行例子

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CalculatorTest {
 @Test
 void add_should_return_sum() {
 Calculator c = new Calculator();
 assertEquals(5, c.add(2, 3));
 }
}

注意——类和方法都不再需要 public，包私有就够了，因为 JUnit 5 用反射访问。这是个微小但很贴心的改进。

二、生命周期注解

JUnit 4 → JUnit 5 注解对照：

JUnit 4	JUnit 5
`@Before`	`@BeforeEach`
`@After`	`@AfterEach`
`@BeforeClass`	`@BeforeAll`
`@AfterClass`	`@AfterAll`
`@Ignore`	`@Disabled`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class LifecycleTest {

 @BeforeAll
 static void beforeAll() { /* 整个测试类前执行一次 */ }

 @BeforeEach
 void beforeEach() { /* 每个 @Test 前执行 */ }

 @Test
 void test1() { /* ... */ }

 @AfterEach
 void afterEach() { /* 每个 @Test 后执行 */ }

 @AfterAll
 static void afterAll() { /* 整个测试类后执行一次 */ }
}

@BeforeAll/@AfterAll 默认必须 static。如果不想写 static，把测试类加上 @TestInstance(Lifecycle.PER_CLASS) ，整个类用一个实例，方法就不必 static 了——但要注意此时测试方法之间会共享实例字段。

三、断言：丰富又优雅

JUnit 5 的 Assertions 是终于"现代化"了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


@Test
void richAssertions() {
 User u = userService.get(1L);

 // 基础
 assertNotNull(u);
 assertEquals("张三", u.getName());

 // 带 message（lambda 形式，断言失败前才计算字符串）
 assertEquals(20, u.getAge(), () -> "用户 " + u.getId() + " 年龄异常");

 // 一次性断言多个条件，全部都要执行
 assertAll("user properties",
 () -> assertEquals("张三", u.getName()),
 () -> assertEquals(20, u.getAge()),
 () -> assertTrue(u.getEmail().endsWith("@example.com"))
 );

 // 异常断言
 Exception ex = assertThrows(IllegalArgumentException.class,
 () -> userService.get(-1L));
 assertEquals("id must be positive", ex.getMessage());

 // 不抛异常断言
 assertDoesNotThrow(() -> userService.get(1L));

 // 超时断言（同步）
 assertTimeout(Duration.ofMillis(500), () -> userService.heavyTask());
 // 超时断言（一旦超时立刻终止任务）
 assertTimeoutPreemptively(Duration.ofMillis(500), () -> userService.heavyTask());
}

四、参数化测试：JUnit 5 的杀手锏

参数化测试是 JUnit 5 最值得单独学的特性。一个测试方法，多套输入，输出是多个独立测试用例——失败时 IDE 里能看到每个用例的结果。

需要额外依赖：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter-params</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

1. `@ValueSource` 单参数

1
2
3
4
5


@ParameterizedTest
@ValueSource(strings = {" ", "\t", "\n"})
void blank_strings_should_be_blank(String input) {
 assertTrue(StringUtils.isBlank(input));
}

2. `@CsvSource` 多参数

1
2
3
4
5
6
7
8
9


@ParameterizedTest(name = "[{index}] {0} + {1} = {2}")
@CsvSource({
 "1, 1, 2",
 "2, 3, 5",
 "10, 20, 30"
})
void add(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

name 属性让每个用例在 IDE 里有清晰的标签，强烈推荐。

3. `@CsvFileSource` 从 CSV 文件读

1
2
3
4
5


@ParameterizedTest
@CsvFileSource(resources = "/test-cases.csv", numLinesToSkip = 1)
void fromCsv(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

适合和测试人员协作——他们维护 CSV，开发不动代码。

4. `@MethodSource` 复杂数据

参数复杂时用方法源：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@ParameterizedTest
@MethodSource("userTestData")
void create(UserDTO input, boolean expectedValid) {
 assertEquals(expectedValid, userValidator.isValid(input));
}

static Stream<Arguments> userTestData() {
 return Stream.of(
 Arguments.of(new UserDTO("张三", 20), true),
 Arguments.of(new UserDTO("", 20), false),
 Arguments.of(new UserDTO("李四", -1), false)
 );
}

5. `@EnumSource` 遍历枚举

1
2
3
4
5


@ParameterizedTest
@EnumSource(value = OrderStatus.class, mode = Mode.EXCLUDE, names = {"DELETED"})
void allActiveStatusesShouldDisplayCorrectly(OrderStatus s) {
 assertNotNull(s.getDisplayName());
}

五、嵌套测试：让用例分组更优雅

@Nested 让测试类按场景分层，IDE 里看上去就是一棵树：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


class UserServiceTest {

 @Nested
 @DisplayName("当用户已存在时")
 class WhenUserExists {
 @BeforeEach void setup() { /* 准备已存在用户 */ }

 @Test void getById_returns_user() { ... }
 @Test void update_should_succeed() { ... }
 }

 @Nested
 @DisplayName("当用户不存在时")
 class WhenUserNotFound {
 @Test void getById_returns_null() { ... }
 @Test void update_should_throw() { ... }
 }
}

@DisplayName 把测试名换成中文/句子式描述，让测试报告读起来像需求文档。

六、条件执行：根据环境跳过

JUnit 5 提供了一组 @EnabledOn* / @DisabledOn*：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Test
@EnabledOnOs(OS.LINUX)
void only_on_linux() { ... }

@Test
@EnabledIfSystemProperty(named = "env", matches = "ci")
void only_on_ci() { ... }

@Test
@DisabledIfEnvironmentVariable(named = "SKIP_HEAVY", matches = "true")
void heavy_test() { ... }

比 @Ignore 灵活得多。

七、扩展模型：替代 JUnit 4 的 Rule

JUnit 4 的 @Rule 不能多个叠加、不能跨类复用。JUnit 5 用统一的 Extension 模型替代：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@ExtendWith(MockitoExtension.class)
class UserServiceTest {

 @Mock UserRepository repo;
 @InjectMocks UserService service;

 @Test
 void getById_returns_user() {
 when(repo.findById(1L)).thenReturn(Optional.of(new User()));
 assertNotNull(service.getById(1L));
 }
}

@ExtendWith 可以叠加多个，也可以在方法级生效，灵活性远超 @Rule。

自定义 Extension 实现各种生命周期接口（BeforeEachCallback、AfterEachCallback、ParameterResolver 等），可以做到" 在每个测试方法前自动初始化数据"、“自动清理数据库”、“自动注入参数"等。

八、Spring Boot 测试整合

Spring Boot 2.2+ 默认就用 JUnit 5。不需要任何额外配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@SpringBootTest
@AutoConfigureMockMvc
class UserControllerIT {

 @Autowired MockMvc mvc;
 @MockBean UserService service;

 @Test
 void getUser_should_return_200() throws Exception {
 when(service.get(1L)).thenReturn(new User(1L, "张三"));

 mvc.perform(get("/users/1"))
 .andExpect(status().isOk())
 .andExpect(jsonPath("$.name").value("张三"));
 }
}

值得一提的几个 Spring Boot 测试切片注解（瘦身的 @SpringBootTest）：

注解	用途
`@WebMvcTest`	只加载 Controller 层
`@DataJpaTest`	只加载 JPA 仓库
`@JsonTest`	只测试 JSON 序列化
`@DataRedisTest`	只加载 Redis 相关 Bean
`@RestClientTest`	测试 RestTemplate / FeignClient

切片测试启动快得多，单测就用切片，集成测试再用 @SpringBootTest。

九、JUnit 4 兼容：渐进式迁移

老项目里两套测试可以共存——保留 junit:junit 作为 Vintage 引擎，新增测试用 Jupiter：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.vintage</groupId>
 <artifactId>junit-vintage-engine</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

迁移建议：

先把 BUILD 配置好，让两套都能跑
新写的测试一律 Jupiter
改老代码时顺手把对应测试迁移过去
一两个迭代后，老测试全部迁完，移除 vintage 依赖

十、踩坑提醒

@BeforeAll/@AfterAll 默认要 static——除非用 @TestInstance(PER_CLASS)
@Test 不要再带 expected = Xxx.class——JUnit 5 没有这个属性，用 assertThrows
包还是 org.junit.jupiter.api——别混用 org.junit.*
Maven Surefire 要 ≥ 2.22，否则跑不起来 Jupiter 测试
参数化测试单独依赖 junit-jupiter-params
@SpringBootTest 不要乱用——它会启动整个上下文，单测应该用切片

小结

JUnit 5 不是"JUnit 4 的小升级”，是为 Lambda、模块化、现代 Java 重新设计的测试框架。

把这一篇压一句：

**写新测试用 Jupiter，老测试靠 Vintage 兼容，慢慢迁；高频场景吃透 assertAll / 参数化 / @Nested，这三个特性能把单测写得像文档。 **

测试本身不是负担，写得好的测试是最准确的需求说明书。JUnit 5 给了你写出这种文档的工具，能不能用好是另一回事。

JUnit5 on 牛哥聊技术