JUnit 5 with Gradle

Learn to configure JUnit 5 with Gradle, its different modules and how to use them to create and execute tests.

Please note that JUnit 5 requires Java 8 at runtime.

1. JUnit 5 Gradle Dependencies

To run JUnit 5 tests through Gradle, you should include a minimum of these dependencies.

• junit-jupiter-api: It is the main module where all core annotations are located, such as @Test, Lifecycle method annotations and assertions.
• junit-jupiter-engine: It has test engine implementation which is required at runtime to execute the tests.
• junit-platform-suite: The @Suite support provided by this module to make the JUnitPlatform runner obsolete.
• junit-jupiter-params: Support for parameterized tests in JUnit 5.

dependencies {
    testRuntime("org.junit.jupiter:junit-jupiter-api:5.8.1")
    testRuntime("org.junit.jupiter:junit-jupiter-engine:5.8.1")
    testRuntime("org.junit.jupiter:junit-jupiter-params:5.8.1")
    testRuntime("org.junit.platform:junit-platform-suite:1.8.1")
}
test {
    useJUnitPlatform()
}

2. Execute JUnit 4 Tests with JUnit 5

To execute JUnit 4 tests in JUnit 5 environment, you will need to include junit-vintage-engine dependency. JUnit Vintage provides a TestEngine for running JUnit 4 based tests on the platform.

dependencies {
    //To run junit 4 tests
    testCompile("junit:junit:4.12")
    testRuntime("org.junit.vintage:junit-vintage-engine:4.12.0-M4")
}

By configuring the above in build.gradle, now you can run your old JUnit 4 tests with JUnit 5 Jupiter.

3. JUnit 5 Gradle Example

A sample build.gradle file for running tests built with junit 5 is as follow:

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

repositories {
	mavenCentral()
}

ext.junit4Version        = '4.12'
ext.junitVintageVersion  = '4.12.2'
ext.junitPlatformVersion = '1.8.1'
ext.junitJupiterVersion  = '5.8.1'
ext.log4jVersion         = '2.9.0'

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

jar {
	baseName = 'junit5-gradle-consumer'
	version = '1.0.0-SNAPSHOT'
}

compileTestJava {
	sourceCompatibility = 1.8
	targetCompatibility = 1.8
	options.compilerArgs += '-parameters'
}

junitPlatform {
	// platformVersion '1.0.2'
	filters {
		engines {
			// include 'junit-jupiter', 'junit-vintage'
			// exclude 'custom-engine'
		}
		tags {
			// include 'fast'
			exclude 'slow'
		}
		// includeClassNamePattern '.*Test'
	}
	// configurationParameter 'junit.jupiter.conditions.deactivate', '*'
	// enableStandardTestTask true
	// reportsDir file('build/test-results/junit-platform') // this is the default
	logManager 'org.apache.logging.log4j.jul.LogManager'
}

dependencies {
	// JUnit Jupiter API and TestEngine implementation
	testCompile("org.junit.jupiter:junit-jupiter-api:${junitJupiterVersion}")
	testRuntime("org.junit.jupiter:junit-jupiter-engine:${junitJupiterVersion}")

	// If you also want to support JUnit 3 and JUnit 4 tests
	testCompile("junit:junit:${junit4Version}")
	testRuntime("org.junit.vintage:junit-vintage-engine:${junitVintageVersion}")

	// To avoid compiler warnings about @API annotations in JUnit code
	testCompileOnly('org.apiguardian:apiguardian-api:1.0.0')

	// To use Log4J's LogManager
	testRuntime("org.apache.logging.log4j:log4j-core:${log4jVersion}")
	testRuntime("org.apache.logging.log4j:log4j-jul:${log4jVersion}")

	// Only needed to run tests in an (IntelliJ) IDE(A) that bundles an older version
	testRuntime("org.junit.platform:junit-platform-launcher:${junitPlatformVersion}")
}

task wrapper(type: Wrapper) {
	description = 'Generates gradlew[.bat] scripts'
	gradleVersion = '4.3.1'
}

Happy Learning !!

Further Reading:

JUnit 5 Maven Dependency Gradle – Convert Maven Project to Gradle Project JUnit 5 – Execute Tests in Eclipse