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.1.0-SNAPSHOT"))
	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.1.0-SNAPSHOT") (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.1.0-SNAPSHOT")
	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.1.0-SNAPSHOT")
		}
	}
}

Groovy DSL

testing {
	suites {
		test {
			useJUnitJupiter("6.1.0-SNAPSHOT")
		}
	}
}

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.1.0-SNAPSHOT")
	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")
	// ...
}

Configuring Logging (optional)

JUnit uses the Java Logging APIs in the java.util.logging package (a.k.a. JUL) to emit warnings and debug information. Please refer to the official documentation of LogManager for configuration options.

Alternatively, it’s possible to redirect log messages to other logging frameworks such as Log4j or Logback. To use a logging framework that provides a custom implementation of LogManager, set the java.util.logging.manager system property to the fully qualified class name of the LogManager implementation to use. The example below demonstrates how to configure Log4j 2.x (see Log4j JDK Logging Adapter for details).

test {
	systemProperty("java.util.logging.manager", "org.apache.logging.log4j.jul.LogManager")
	// Avoid overhead (see https://logging.apache.org/log4j/2.x/manual/jmx.html#enabling-jmx)
	systemProperty("log4j2.disableJmx", "true")
}

Other logging frameworks provide different means to redirect messages logged using java.util.logging. For example, for Logback you can use the JUL to SLF4J Bridge by adding it as a dependency to the test runtime classpath.

Maven

Maven Surefire and Maven Failsafe provide native support for executing tests on the JUnit Platform. The pom.xml file in the junit-jupiter-starter-maven project demonstrates how to use the Maven Surefire plugin and can serve as a starting point for configuring your Maven build.

Minimum required version of Maven Surefire/Failsafe

As of JUnit 6.0, the minimum required version of Maven Surefire/Failsafe is 3.0.0.

Aligning dependency versions

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.

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>org.junit</groupId>
			<artifactId>junit-bom</artifactId>
			<version>6.1.0-SNAPSHOT</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

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.

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

Configuring Test Engines

In order to have Maven Surefire or Maven Failsafe run any tests at all, at least one TestEngine implementation must be added to the test classpath.

To configure support for JUnit Jupiter based tests, configure test scoped dependencies on the JUnit Jupiter API and the JUnit Jupiter TestEngine implementation similar to the following.

<!-- ... -->
<dependencies>
	<!-- ... -->
	<dependency>
		<groupId>org.junit.jupiter</groupId>
		<artifactId>junit-jupiter</artifactId>
		<version>6.1.0-SNAPSHOT</version> <!-- can be omitted when using the BOM -->
		<scope>test</scope>
	</dependency>
	<!-- ... -->
</dependencies>
<build>
	<plugins>
		<plugin>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.5.4</version>
		</plugin>
		<plugin>
			<artifactId>maven-failsafe-plugin</artifactId>
			<version>3.5.4</version>
		</plugin>
	</plugins>
</build>
<!-- ... -->

Maven Surefire and Maven Failsafe can run JUnit 4 based tests alongside Jupiter tests as long as you configure test scoped dependencies on JUnit 4 and the JUnit Vintage TestEngine implementation similar to the following.

<!-- ... -->
<dependencies>
	<!-- ... -->
	<dependency>
		<groupId>junit</groupId>
		<artifactId>junit</artifactId>
		<version>4.13.2</version>
		<scope>test</scope>
	</dependency>
	<dependency>
		<groupId>org.junit.vintage</groupId>
		<artifactId>junit-vintage-engine</artifactId>
		<version>6.1.0-SNAPSHOT</version> <!-- can be omitted when using the BOM -->
		<scope>test</scope>
	</dependency>
	<!-- ... -->
</dependencies>
<!-- ... -->
<build>
	<plugins>
		<plugin>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.5.4</version>
		</plugin>
		<plugin>
			<artifactId>maven-failsafe-plugin</artifactId>
			<version>3.5.4</version>
		</plugin>
	</plugins>
</build>
<!-- ... -->

Filtering by Test Class Names

The Maven Surefire Plugin will scan for test classes whose fully qualified names match the following patterns.

**/Test*.java
**/*Test.java
**/*Tests.java
**/*TestCase.java

Moreover, it will exclude all nested classes (including static member classes) by default.

Note, however, that you can override this default behavior by configuring explicit include and exclude rules in your pom.xml file. For example, to keep Maven Surefire from excluding static member classes, you can override its exclude rules as follows.

Overriding exclude rules of Maven Surefire

<!-- ... -->
<build>
	<plugins>
		<plugin>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.5.4</version>
			<configuration>
				<excludes>
					<exclude/>
				</excludes>
			</configuration>
		</plugin>
	</plugins>
</build>
<!-- ... -->

Please see the Inclusions and Exclusions of Tests documentation for Maven Surefire for details.

Filtering by Tags

You can filter tests by tags or tag expressions using the following configuration properties.

to include tags or tag expressions, use groups.
to exclude tags or tag expressions, use excludedGroups.

<!-- ... -->
<build>
	<plugins>
		<plugin>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.5.4</version>
			<configuration>
				<groups>acceptance | !feature-a</groups>
				<excludedGroups>integration, regression</excludedGroups>
			</configuration>
		</plugin>
	</plugins>
</build>
<!-- ... -->

Configuration Parameters

You can set JUnit Platform configuration parameters to influence test discovery and execution by declaring the configurationParameters property and providing key-value pairs using the Java Properties file syntax (as shown below) or via the junit-platform.properties file.

<!-- ... -->
<build>
	<plugins>
		<plugin>
			<artifactId>maven-surefire-plugin</artifactId>
			<version>3.5.4</version>
			<configuration>
				<properties>
					<configurationParameters>
						junit.jupiter.conditions.deactivate = *
						junit.jupiter.extensions.autodetection.enabled = true
						junit.jupiter.testinstance.lifecycle.default = per_class
					</configurationParameters>
				</properties>
			</configuration>
		</plugin>
	</plugins>
</build>
<!-- ... -->

Ant

Starting with version 1.10.3, Ant has a junitlauncher task that provides native support for launching tests on the JUnit Platform. The junitlauncher task is solely responsible for launching the JUnit Platform and passing it the selected collection of tests. The JUnit Platform then delegates to registered test engines to discover and execute the tests.

The junitlauncher task attempts to align as closely as possible with native Ant constructs such as resource collections for allowing users to select the tests that they want executed by test engines. This gives the task a consistent and natural feel when compared to many other core Ant tasks.

Starting with version 1.10.6 of Ant, the junitlauncher task supports forking the tests in a separate JVM.

The build.xml file in the junit-jupiter-starter-ant project demonstrates how to use the task and can serve as a starting point.

Basic Usage

The following example demonstrates how to configure the junitlauncher task to select a single test class (i.e., com.example.project.CalculatorTests).

<path id="test.classpath">
	<!-- The location where you have your compiled classes -->
	<pathelement location="${build.classes.dir}" />
</path>

<!-- ... -->

<junitlauncher>
	<classpath refid="test.classpath" />
	<test name="com.example.project.CalculatorTests" />
</junitlauncher>

The test element allows you to specify a single test class that you want to be selected and executed. The classpath element allows you to specify the classpath to be used to launch the JUnit Platform. This classpath will also be used to locate test classes that are part of the execution.

The following example demonstrates how to configure the junitlauncher task to select test classes from multiple locations.

<path id="test.classpath">
	<!-- The location where you have your compiled classes -->
	<pathelement location="${build.classes.dir}" />
</path>
<!-- ... -->
<junitlauncher>
	<classpath refid="test.classpath" />
	<testclasses outputdir="${output.dir}">
		<fileset dir="${build.classes.dir}">
			<include name="org/example/**/demo/**/" />
		</fileset>
		<fileset dir="${some.other.dir}">
			<include name="org/myapp/**/" />
		</fileset>
	</testclasses>
</junitlauncher>

In the above example, the testclasses element allows you to select multiple test classes that reside in different locations.

For further details on usage and configuration options please refer to the official Ant documentation for the junitlauncher task.

Spring Boot

Spring Boot provides automatic support for managing the version of JUnit used in your project. In addition, the spring-boot-starter-test artifact automatically includes testing libraries such as JUnit Jupiter, AssertJ, Mockito, etc.

If your build relies on dependency management support from Spring Boot, you should not import JUnit’s Bill of Materials (BOM) in your build script since that would result in duplicate (and potentially conflicting) management of JUnit dependencies.

If you need to override the version of a dependency used in your Spring Boot application, you have to override the exact name of the version property defined in the BOM used by the Spring Boot plugin. For example, the name of the JUnit Jupiter version property in Spring Boot is junit-jupiter.version. The mechanism for changing a dependency version is documented for both Gradle and Maven.

With Gradle you can override the JUnit Jupiter version by including the following in your build.gradle file.

ext['junit-jupiter.version'] = '6.1.0-SNAPSHOT'

With Maven you can override the JUnit Jupiter version by including the following in your pom.xml file.

<properties>
	<junit-jupiter.version>6.1.0-SNAPSHOT</junit-jupiter.version>
</properties>