Are you having trouble writing automated tests for your Spring or Spring Boot web app? If so, take a look at my Test With Spring course.

JUnit 5 Tutorial: Running Unit Tests With Gradle

This blog post describes how we can create a Gradle project that can compile and run unit tests which use JUnit 5. We will learn to get the required dependencies with Gradle, use the native JUnit 5 support provided by Gradle 4.6, and use the JUnit 5 Gradle plugin which is required if we use Gradle 4.5 (or older). Finally, we will find out how we can run our unit tests with Gradle.

Let’s start by creating our Gradle project when we use Gradle 4.6.

If you are using Gradle 4.5 (or older), you you should skip the next section and continue reading from this section.

Creating Our Gradle Project if We Use Gradle 4.6

Gradle 4.6 has a native support for JUnit 5. However, before we can enable this support, we have to get the required dependencies.

Getting the Required Dependencies

We can get the required dependencies by following these steps:

  1. Add the junit-jupiter-api (version 5.1.0) dependency to the testImplementation dependency configuration. This dependency provides the public API for writing tests and extensions.
  2. Add the used test engine implementations to the testRuntimeOnly dependency configuration. Because we want to run only unit tests which use JUnit 5, we have to add the junit-jupiter-engine (version 5.1.0) dependency to the testRuntimeOnly dependency configuration.

After we have declared the required dependencies, our build.gradle file looks as follows:

apply plugin: 'java'

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(
            'org.junit.jupiter:junit-jupiter-api:5.1.0'
    )
    testRuntimeOnly(
            'org.junit.jupiter:junit-jupiter-engine:5.1.0'
    )
}

If we want to run tests which use JUnit 4 or 3, we have to add the junit-vintage-engine dependency (version 5.1.0) to the testRuntimeOnly dependency configuration. Also, we have to add the correct JUnit dependency to the testCompileOnly dependency configuration.

For example, if we want to run tests which use JUnit 4, our build.gradle file looks as follows:

apply plugin: 'java'

repositories {
    mavenCentral()
}

dependencies {
    testCompileOnly(
            'junit:junit:4.12'
    )
    testImplementation(
            'org.junit.jupiter:junit-jupiter-api:5.1.0'
    )
    testRuntimeOnly(
            'org.junit.jupiter:junit-jupiter-engine:5.1.0',
            'org.junit.vintage:junit-vintage-engine:5.1.0'
    )
}

After we have declared the required dependencies, we have to enable the Gradle’s native JUnit 5 support. Next, we will find out how we can do it.

Enabling the Gradle’s Native JUnit 5 Support

Even though Gradle 4.6 has a native support for JUnit 5, this support is not enabled by default. If we want to enable it, we have to ensure that the test task uses JUnit 5 instead of JUnit 4. After we have done this, the source code of our build.gradle file looks as follows:

apply plugin: 'java'

repositories {
    mavenCentral()
}

dependencies {
    testCompileOnly(
            'junit:junit:4.12'
    )
    testImplementation(
            'org.junit.jupiter:junit-jupiter-api:5.1.0'
    )
    testRuntimeOnly(
            'org.junit.jupiter:junit-jupiter-engine:5.1.0',
            'org.junit.vintage:junit-vintage-engine:5.1.0'
    )
}

test {
    useJUnitPlatform()
}
If you are not using Gradle 4.5 (or older), you you should skip the next section and continue reading from this section.

Additional Reading:

Creating Our Gradle Project if We Use Gradle 4.5 (or Older)

Because Gradle 4.5 doesn’t have a native support for JUnit 5, we have to use the JUnit 5 Gradle plugin which integrates the JUnit Jupiter Platform with Gradle. Next, we will find out how we can configure the JUnit 5 Gradle plugin.

Configuring the JUnit 5 Gradle Plugin

The JUnit 5 Gradle plugin allows us to run tests which are supported by the used test engines. We can configure the JUnit 5 Gradle plugin by following these steps:

First, we have to configure the dependencies of our build script. We can do this by adding the junit-platform-gradle-plugin (version 1.1.0) dependency to the classpath configuration.

After we have done this, the source code of our build.gradle file looks as follows:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.junit.platform:junit-platform-gradle-plugin:1.1.0'
    }
}

Second, we have to apply the JUnit 5 Gradle plugin. After we have applied this plugin, the source code of our build.gradle file looks as follows:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.junit.platform:junit-platform-gradle-plugin:1.1.0'
    }
}

apply plugin: 'java'
apply plugin: 'org.junit.platform.gradle.plugin'

After we have configured the JUnit 5 Gradle plugin, we have to get the required dependencies. Let’s find out how we can do it.

Getting the Required Dependencies

We can get the required dependencies by following these steps:

  1. Add the junit-jupiter-api (version 5.1.0) dependency to the testCompile dependency configuration. This dependency provides the public API for writing tests and extensions.
  2. Add the used test engine implementations to the testRuntime configuration. Because we want to run only unit tests which use JUnit 5, we have to add the junit-jupiter-engine (version 5.1.0) dependency to the testRuntime dependency configuration.

After we have declared the required dependencies, our build.gradle file looks as follows:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.junit.platform:junit-platform-gradle-plugin:1.1.0'
    }
}

apply plugin: 'java'
apply plugin: 'org.junit.platform.gradle.plugin'

repositories {
    mavenCentral()
}

dependencies {
    testCompile(
            'org.junit.jupiter:junit-jupiter-api:5.1.0'
    )
    testRuntime(
            'org.junit.jupiter:junit-jupiter-engine:5.1.0'
    )
}
If we want to run tests which use either JUnit 4 or JUnit 3, we have to add the junit-vintage-engine (version 5.1.0) dependency to the testRuntime dependency configuration.

If we are using an IDE that is bundled with an older JUnit 5 version, it throws an exception when we try to run our unit tests by using our IDE. We can fix this problem by adding the following dependencies to the testRuntime dependency configuration:

  • The junit-vintage-engine (version 5.1.0) dependency adds support for unit tests that use JUnit 4 or JUnit 3.
  • The junit-platform-launcher (version 1.1.0) dependency provides a public API for configuring and launching tests. This API is typically used by IDEs and build tools.
  • The junit-platform-runner (version 1.1.0) dependency allows us to run tests and test suites in a JUnit 4 environment.

After we have declared the required dependencies, our build.gradle file looks as follows:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.junit.platform:junit-platform-gradle-plugin:1.1.0'
    }
}

apply plugin: 'java'
apply plugin: 'org.junit.platform.gradle.plugin'

repositories {
    mavenCentral()
}

dependencies {
    testCompile(
            'org.junit.jupiter:junit-jupiter-api:5.1.0'
    )
    testRuntime(
            'org.junit.jupiter:junit-jupiter-engine:5.1.0',
            'org.junit.vintage:junit-vintage-engine:5.1.0',
            'org.junit.platform:junit-platform-launcher:1.1.0',
            'org.junit.platform:junit-platform-runner:1.1.0'
    )
}

We have now created a Gradle project that can run unit tests which use JUnit 5. Let’s move on and write a simple unit test with JUnit 5.

Writing a Simple Test Class

Before we can write unit tests which use JUnit 5, we have to know these two things:

  • The src/test/java directory contains the source code of our unit tests.
  • The src/test/resources directory contains the resources of our unit tests.

Let’s create a new test class and add one test method to created class. This test method simply writes a message to System.out. The source code of our test class looks as follows:

import org.junit.jupiter.api.Test;

class JUnit5ExampleTest {

    @Test
    void justAnExample() {
        System.out.println("This test method should be run");
    }
}
I won’t describe this test class in this blog post because my upcoming blog posts will provide introduction to JUnit 5 test classes.

Also, we shouldn’t write tests which write messages to System.out. I use this technique here only because it is an easy to way see that our test method is run.

Let’s move on and find out how we can run our unit tests.

Running Unit Tests With Gradle

We can run our unit tests with Gradle by running the following command at command prompt:

gradle clean test

When we run our unit tests, we should see the following output:

$ gradle clean test

> Task :junitPlatformTest
This test method should be run
By default, the test task doesn’t show the information written to System.out or System.err. If we want to show this information, we can make the required changes to the configuration of the test task by following the instructions given in the blog post: Show Standard Out or Error Output from Tests.

As we can see, Gradle runs our unit test. Let’s summarize what we learned from this blog post.

Summary

This blog post has taught us four things:

  • The junit-jupiter-api dependency allows us to write tests and extensions which use JUnit 5.
  • The junit-jupiter-engine dependency allows us to run tests which use JUnit 5.
  • The junit-vintage-engine dependency allows us to run tests which use JUnit 3 or 4.
  • The JUnit 5 Gradle plugin allows us to run tests which are supported by the used test engines.

P.S. You can get the example application of this blog post from Github.

10 comments… add one
  • Hi Petri,

    thanks for this great article. I just try to get different test source sets used by the junit5-gradle-plugin, but unforunately tests in a new source set integration-tests won’t get executed.
    Do you plan to provide an update of the setup for Gradle using JUnit 5? Maybe as an update of your article “getting-started-with-gradle-integration-testing”?
    Thanks in advance
    Stefan

    Reply
    • This Stack Overflow article seems to go in the right direction, but I didn’t get it running …
      https://stackoverflow.com/questions/45297339/junit-5-under-gradle-with-multiple-source-sets
      Stefan

      Reply
      • No it works:

        task integrationTest(
        type: JavaExec,
        description: ‘Runs the integration tests.’,
        group: ‘Verification’
        ) {
        dependsOn testClasses
        mustRunAfter junitPlatformTest

        classpath = sourceSets.integrationTest.runtimeClasspath
        main = ‘org.junit.platform.console.ConsoleLauncher’
        args = [‘–scan-class-path’,
        sourceSets.integrationTest.output.getClassesDirs().asPath,
        ‘–reports-dir’, “${buildDir}/test-results/junit-e2e”]
        }
        check.dependsOn integrationTest

        With dependency

        testRuntime(“org.junit.platform:junit-platform-console:$junitPlatformVersion”)

        Stefan

        Reply
        • Hi Stefan,

          First, it’s good to hear that you were able to solve your problem while I was working. Also, thank you for posting your solution here. I am going to write a blog post about this in the future. This post will probably be a part of my JUnit 5 tutorial, but I have to also admit that I will probably wait until Gradle releases the official JUnit 5 support because I think that it will make things a bit easier.

          Reply
  • That was very helpful. thank you :)

    Reply
    • You are welcome!

      Reply
  • This is no longer needed. Gradle 4.6 supports JUnit5 natively, with:

    
    test { useJunitPlatform() }
    
    
    Reply
    • Good catch! I will add a note about this to the beginning of this blog post. I will update this blog post eventually, but I hope that the note will help people to avoid any extra work. By the way, thank you for reminding me about this.

      Reply

Leave a Comment