How to use JUnit 5 with Gradle?

Question

I am trying to use JUnit 5 with Gradle after I succeeded in running a JUnit 4 test.

Expected result: Tthe JUnit 4 test gave a nice \'passed\' in the

Answer 1

New: JUnit 5 support in Gradle 4.6

As pointed out in this GitHub issue from Gradle 4.6 onwards JUnit 5 is supported! Official release notes of 4.6 (at the moment of editing the latest, but check the GitHub releases page to make sure you use the latest version) at docs.gradle.org. The old setup will still work, but using this makes the build file a lot cleaner.

[Edit May 2019] As @deFreitas pointed out in his answer, the JUnit documentation has improved and now they provide a complete example at https://github.com/junit-team/junit5-samples/tree/r5.4.0/junit5-jupiter-starter-gradle, see especially the build.gradle there. Fortunately it turns out to be effectively the same as the one from this answer.

Update Gradle

First, make sure you are using the latest Gradle version, check latest releases at their GitHub releases. If that is for example 4.6, run in a terminal in your project location gradlew wrapper --gradle-version=4.6 or make sure to update this line in your gradle/wrapper/gradle-wrapper.properties file: distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-all.zip.

How to use the built-in JUnit 5

Then with the java files, directory structure etc. from the question the build.gradle file will be (using the new plugins block)

plugins {
    id 'java'
}

repositories {
    mavenCentral()
    mavenLocal()
}

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

// These lines can be removed when you use the default directories src/main/kotlin and src/test/kotlin
sourceSets {
    main.java.srcDirs += 'src'
    main.resources.srcDirs += 'src'
    test.java.srcDirs += 'test'
    test.resources.srcDirs += 'test'
}

// Java target version
sourceCompatibility = 1.8

test {
    // Enable JUnit 5 (Gradle 4.6+).
    useJUnitPlatform()

    // Always run tests, even when nothing changed.
    dependsOn 'cleanTest'

    // Show test results.
    testLogging {
        events "passed", "skipped", "failed"
    }
}

PS For the absolute minimal version, see Ray's answer.

Android

On Android I managed to run the JUnit 5 test from the question by adding the following to my app module build file. As you can see the dependencies are the same, but I didn't need useJUnitPlatform() and the test configuration block is slightly different.

apply plugin: 'com.android.application'
// In fact I am not sure you need this, but I had it included to run Spek tests anyway
apply plugin: 'de.mannodermaus.android-junit5' 

repositories {
    mavenCentral()
    jcenter()
}

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


android {
    // I'm omitting your other configurations like compileSdkVersion, buildTypes etc.

    testOptions {
        unitTests.all {

            // Always run tests, even when nothing changed.
            dependsOn 'clean'

            // Show test results.
            testLogging {
                events "passed", "skipped", "failed"
            }
        }
    }
}

however it only works for me when I execute the Gradle test task, not when I run the check task. As usual, I test this by creating a failing test and then I try if the Gradle task passes or fails.