Using JUnit 5 with Gradle – 在Gradle中使用JUnit 5

最后修改: 2018年 10月 16日

1. Overview


In this tutorial, we’re going to run tests on the new JUnit 5 platform with the Gradle build tool. 

在本教程中,我们将利用Gradle构建工具在新的JUnit 5平台上运行测试。

We’ll configure a project that supports both the old and the new version.


Feel free to read A Guide to JUnit 5 for more information about the new version. Or the Introduction to Gradle for in-depth information about the build tool.

欢迎阅读JUnit 5 指南,了解有关新版本的更多信息。或者阅读Gradle简介以了解有关构建工具的深入信息。

2. Gradle Setup


First, we verify if version 4.6 or higher of the build tool is installed since that is the earliest version that works with JUnit 5.

首先,我们验证是否安装了4.6或更高版本的构建工具,因为这是最早的与JUnit 5一起使用的版本。

The simplest way is to just run the gradle -v command:

最简单的方法是直接运行gradle -v命令。

$> gradle -v
Gradle 4.10.2

And, if necessary, we can follow the installation steps to get the right version.


Once we’ve installed everything, we then need to configure Gradle by using the build.gradle file.


We can start by supplying the unit test platform to the build tool:


test {

Now that we’ve specified the platform, we need to supply the JUnit dependencies. This is where we see a noteworthy difference between JUnit 5 and earlier versions.

现在我们已经指定了平台,我们需要提供JUnit的依赖性。这就是我们看到JUnit 5和早期版本之间值得注意的区别。

See, with earlier versions, we only needed one dependency. In JUnit 5, though, the API is separated from the runtime, meaning two dependencies.

看,在早期版本中,我们只需要一个依赖性。在JUnit 5中,API与运行时是分开的,这意味着有两个依赖性。

The API is manifest with junit-jupiter-api. The runtime is junit-jupiter-engine for JUnit 5, and junit-vintage-engine for JUnit 3 or 4.

API是用junit-jupiter-api表现的。运行时对于JUnit 5来说是junit-jupiter-engine,对于JUnit 3或4来说是junit-vintine

We’ll supply these two in testImplementation and timeRuntimeOnly, respectively:


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

3. Creating Tests


Let’s write our first test. It looks just like earlier versions:


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

Now, we can run the test by executing the gradle clean test command.

现在,我们可以通过执行gradle clean test命令来运行该测试

To verify that we’re using JUnit 5 we can look at the imports. The imports for @Test and assertEquals should have a package starting with org.junit.jupiter.api:

为了验证我们是否使用了JUnit 5,我们可以看一下导入。@TestassertEquals的导入应该有一个以org.junit.jupiter.api:开始的包。

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

So in the last example, we created a test with ‘old’ functionality that has been working for years. We’ll now create another example which uses some of the new functionality in JUnit 5:

所以在上一个例子中,我们创建了一个具有 “旧 “功能的测试,这个功能已经工作了多年。现在我们将创建另一个例子,它使用JUnit 5中的一些新功能。

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

assertThrows is a new assertion in JUnit5 that replaces the old style of @Test(expected=ArithmeticException.class).


4. Configuring JUnit 5 Tests With Gradle

4.用Gradle配置JUnit 5测试

Next, we’ll explore some deeper integration between Gradle and JUnit5.


Let’s say that we have two types of tests in our suite: long-running and short-running. We could use the JUnit 5 @Tag annotation:

假设我们的套件中有两种类型的测试:长运行和短运行。我们可以使用JUnit 5 @Tag 注释。

public class CalculatorJUnit5Test {
    public void testAddMaxInteger() {
        assertEquals(2147483646, Integer.sum(2147183646, 300000));
    public void testDivide() {
        assertThrows(ArithmeticException.class, () -> {
            Integer.divideUnsigned(42, 0);

Then, we tell the build tool which ones to execute. In our case, let’s just execute the short-running (fast) tests:


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

5. Enabling Support for Old Versions


Now, it’s still possible to create JUnit 3 and 4 tests with the new Jupiter engine. Even more, we can mix them with the new version in the same project, say, in a migration scenario.

现在,仍然可以用新的Jupiter引擎创建JUnit 3和4测试。甚至,我们可以在同一个项目中把它们和新的版本混在一起,比如说,在迁移的情况下。

To start we add some dependencies to the existing build configuration:


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

Note how our project now has both junit-jupiter-engine as well as junit-vintage-engine.


Now we create a new class and copy paste the testDivide method we created earlier. Then, we add the imports for @Test and assertEquals. However, this time we make sure to use the old version 4 packages starting which org.junit:


import static org.junit.Assert.assertEquals;
import org.junit.Test;
public class CalculatorJUnit4Test {
    public void testAdd() {
        assertEquals(42, Integer.sum(19, 23));

6. Conclusion


In this tutorial, we integrated Gradle with JUnit 5. Even more, we also added support for versions 3 and 4.

在本教程中,我们将Gradle与JUnit 5集成。更有甚者,我们还增加了对3和4版本的支持。

We’ve seen that the build tool provides excellent support for the old and new versions. Hence we can use the new features in an existing project without the need to change all our existing tests.


The complete code example is available in the GitHub project. Feel free to use it as a starting point for your own project.