Build Support

Gradle

Starting with version 4.6, Gradle provides native support for executing tests on the JUnit Platform. To enable it, you need to specify useJUnitPlatform() within a test task declaration in build.gradle:

test {
	useJUnitPlatform()
}

Filtering by tags, tag expressions, or engines is also supported:

test {
	useJUnitPlatform {
		includeTags("fast", "smoke & feature-a")
		// excludeTags("slow", "ci")
		includeEngines("junit-jupiter")
		// excludeEngines("junit-vintage")
	}
}

Please refer to the official Gradle documentation for a comprehensive list of options.

Aligning dependency versions

See Spring Boot for details on how to override the version of JUnit used in your Spring Boot application.

Unless you’re using Spring Boot which defines its own way of managing dependencies, it is recommended to use the JUnit Platform Bill of Materials (BOM) to align the versions of all JUnit artifacts.

Explicit platform dependency on the BOM

dependencies {
	testImplementation(platform("org.junit:junit-bom:6.0.3"))
	testImplementation("org.junit.jupiter:junit-jupiter")
	testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Using the BOM allows you to omit the version when declaring dependencies on all artifacts with the org.junit.platform, org.junit.jupiter, and org.junit.vintage group IDs.

Since all JUnit artifacts declare a platform dependency on the BOM, you usually don’t need to declare an explicit dependency on it yourself. Instead, it’s sufficient to declare one regular dependency that includes a version number. Gradle will then pull in the BOM automatically so you can omit the version for all other JUnit artifacts.

Implicit platform dependency on the BOM

dependencies {
	testImplementation("org.junit.jupiter:junit-jupiter:6.0.3") (1)
	testRuntimeOnly("org.junit.platform:junit-platform-launcher") (2)
}

1	Dependency declaration with explicit version. Pulls in the `junit-bom` automatically.
2	Dependency declaration without version. The version is supplied by the `junit-bom`.

Declaring a dependency on junit-platform-launcher

Even though pre-8.0 versions of Gradle don’t require declaring an explicit dependency on junit-platform-launcher, it is recommended to do so to ensure the versions of JUnit artifacts on the test runtime classpath are aligned.

Moreover, doing so is recommended and in some cases even required when importing the project into an IDE like Eclipse or IntelliJ IDEA.

Configuring Test Engines

In order to run any tests at all, a TestEngine implementation must be on the classpath.

To configure support for JUnit Jupiter based tests, configure a testImplementation dependency on the dependency-aggregating JUnit Jupiter artifact similar to the following.

dependencies {
	testImplementation("org.junit.jupiter:junit-jupiter:6.0.3")
	testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Alternatively, you can use Gradle’s JVM Test Suite support.

Kotlin DSL

testing {
	suites {
		named<JvmTestSuite>("test") {
			useJUnitJupiter("6.0.3")
		}
	}
}

Groovy DSL

testing {
	suites {
		test {
			useJUnitJupiter("6.0.3")
		}
	}
}

The JUnit Platform can run JUnit 4 based tests as long as you configure a testImplementation dependency on JUnit 4 and a testRuntimeOnly dependency on the JUnit Vintage TestEngine implementation similar to the following.

dependencies {
	testImplementation("junit:junit:4.13.2")
	testRuntimeOnly("org.junit.vintage:junit-vintage-engine:6.0.3")
	testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Configuration Parameters

The standard Gradle test task currently does not provide a dedicated DSL to set JUnit Platform configuration parameters to influence test discovery and execution. However, you can provide configuration parameters within the build script via system properties (as shown below) or via the junit-platform.properties file.

test {
	// ...
	systemProperty("junit.jupiter.conditions.deactivate", "*")
	systemProperty("junit.jupiter.extensions.autodetection.enabled", true)
	systemProperty("junit.jupiter.testinstance.lifecycle.default", "per_class")
	// ...
}