在 Gradle 中使用 JUnit 5 | Baeldung中文网

1. 概述

在本教程中，我们将介绍如何在 Gradle 构建工具中运行 JUnit 5 的测试。

我们会配置一个同时支持旧版本（JUnit 4）和新版本（JUnit 5）的项目。

如果你对 JUnit 5 还不熟悉，可以先阅读 JUnit 5 指南；如果对 Gradle 不熟，也可以参考 Gradle 入门。

2. Gradle 配置

首先，确认你使用的 Gradle 版本是 4.6 或更高版本，因为这是支持 JUnit 5 的最低版本。

最简单的检查方式是运行：

$> gradle -v
------------------------------------------------------------
Gradle 4.10.2
------------------------------------------------------------

如果版本过低，可以前往 Gradle 官网下载并安装合适的版本。

安装完成后，我们需要在 build.gradle 文件中进行配置。

首先启用 JUnit Platform：

test {
    useJUnitPlatform()
}

接着添加 JUnit 5 所需的依赖项。注意：JUnit 5 将 API 和运行时引擎进行了分离，这点和之前的版本不同。

junit-jupiter-api：用于编写测试的 API
junit-jupiter-engine：JUnit 5 的运行时引擎
junit-vintage-engine：用于运行 JUnit 3/4 的测试

在 build.gradle 中添加如下依赖：

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.1'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.1'
}

3. 编写测试

我们先写一个最基础的测试方法，和旧版本写法基本一致：

@Test
public void testAdd() {
    assertEquals(42, Integer.sum(19, 23));
}

运行测试的方式也很简单：

gradle clean test

确认是否使用了 JUnit 5，可以查看导入的包路径是否以 org.junit.jupiter.api 开头：

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

接下来我们再写一个使用 JUnit 5 新特性的测试：

@Test
public void testDivide() {
    assertThrows(ArithmeticException.class, () -> {
        Integer.divideUnsigned(42, 0);
    });
}

⚠️ 注意：assertThrows 是 JUnit 5 提供的新断言方式，取代了旧版本中 @Test(expected=...) 的写法。

4. 使用 Gradle 配置 JUnit 5 测试

JUnit 5 支持通过标签（Tag）对测试进行分类，我们可以结合 Gradle 的配置来控制运行哪些测试。

假设我们有两类测试：fast 和 slow，可以使用 @Tag 注解标记：

public class CalculatorJUnit5Test {
    @Tag("slow")
    @Test
    public void testAddMaxInteger() {
        assertEquals(2147483646, Integer.sum(2147183646, 300000));
    }
 
    @Tag("fast")
    @Test
    public void testDivide() {
        assertThrows(ArithmeticException.class, () -> {
            Integer.divideUnsigned(42, 0);
        });
    }
}

然后在 build.gradle 中配置只运行 fast 标签的测试：

test {
    useJUnitPlatform {
        includeTags 'fast'
        excludeTags 'slow'
    }
}

✅ 这样就能灵活控制测试执行范围，特别适合在 CI/CD 中分阶段运行测试。

5. 向后兼容旧版本 JUnit

JUnit 5 并没有抛弃旧版本，它通过 junit-vintage-engine 兼容 JUnit 3 和 4。

我们可以在同一个项目中混用新旧版本的测试，非常适合迁移场景。

首先添加兼容依赖：

testCompileOnly 'junit:junit:4.12' 
testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.8.1'

然后编写一个 JUnit 4 的测试类：

import static org.junit.Assert.assertEquals;
import org.junit.Test;

public class CalculatorJUnit4Test {
    @Test
    public void testAdd() {
        assertEquals(42, Integer.sum(19, 23));
    }
}

⚠️ 注意：此时导入的是 org.junit 包，而非 org.junit.jupiter。

这样就可以在同一个项目中运行 JUnit 4 和 JUnit 5 的测试，迁移起来更平滑。

6. 总结

本文展示了如何在 Gradle 中集成 JUnit 5，并保持对 JUnit 3/4 的兼容性。

通过合理配置，我们可以在现有项目中逐步引入 JUnit 5 的新特性，而无需一次性重构所有测试。

完整的示例代码可以在 GitHub 项目中找到，欢迎作为你项目的起点使用。

Persistence

REST

Security