Using JUnit 4 to run the JUnit Platform

The JUnitPlatform runner has been deprecated

The JUnitPlatform runner was developed by the JUnit team as an interim solution for running test suites and tests on the JUnit Platform in a JUnit 4 environment.

In recent years, all mainstream build tools and IDEs provide built-in support for running tests directly on the JUnit Platform.

In addition, the introduction of @Suite support provided by the junit-platform-suite-engine module makes the JUnitPlatform runner obsolete. See JUnit Platform Suite Engine for details.

The JUnitPlatform runner and @UseTechnicalNames annotation have therefore been deprecated in JUnit Platform 1.8 and will be removed in JUnit Platform 2.0.

If you are using the JUnitPlatform runner, please migrate to the @Suite support.

The JUnitPlatform runner is a JUnit 4 based Runner which enables you to run any test whose programming model is supported on the JUnit Platform in a JUnit 4 environment — for example, a JUnit Jupiter test class.

Annotating a class with @RunWith(JUnitPlatform.class) allows it to be run with IDEs and build systems that support JUnit 4 but do not yet support the JUnit Platform directly.

Since the JUnit Platform has features that JUnit 4 does not have, the runner is only able to support a subset of the JUnit Platform functionality, especially with regard to reporting (see Display Names vs. Technical Names).

Setup

You need the following artifacts and their dependencies on the classpath. See Dependency Metadata for details regarding group IDs, artifact IDs, and versions.

Explicit Dependencies

junit-platform-runner in test scope: location of the JUnitPlatform runner
junit-4.13.2.jar in test scope: to run tests using JUnit 4
junit-jupiter-api in test scope: API for writing tests using JUnit Jupiter, including @Test, etc.
junit-jupiter-engine in test runtime scope: implementation of the TestEngine API for JUnit Jupiter

Transitive Dependencies

junit-platform-suite-api in test scope
junit-platform-suite-commons in test scope
junit-platform-launcher in test scope
junit-platform-engine in test scope
junit-platform-commons in test scope
opentest4j in test scope

Display Names vs. Technical Names

To define a custom display name for the class run via @RunWith(JUnitPlatform.class) annotate the class with @SuiteDisplayName and provide a custom value.

By default, display names will be used for test artifacts; however, when the JUnitPlatform runner is used to execute tests with a build tool such as Gradle or Maven, the generated test report often needs to include the technical names of test artifacts — for example, fully qualified class names — instead of shorter display names like the simple name of a test class or a custom display name containing special characters. To enable technical names for reporting purposes, declare the @UseTechnicalNames annotation alongside @RunWith(JUnitPlatform.class).

Note that the presence of @UseTechnicalNames overrides any custom display name configured via @SuiteDisplayName.

Single Test Class

One way to use the JUnitPlatform runner is to annotate a test class with @RunWith(JUnitPlatform.class) directly. Please note that the test methods in the following example are annotated with org.junit.jupiter.api.Test (JUnit Jupiter), not org.junit.Test (JUnit 4). Moreover, in this case the test class must be public; otherwise, some IDEs and build tools might not recognize it as a JUnit 4 test class.

import static org.junit.jupiter.api.Assertions.fail;

import org.junit.jupiter.api.Test;
import org.junit.runner.RunWith;

@RunWith(org.junit.platform.runner.JUnitPlatform.class)
public class JUnitPlatformClassDemo {

	@Test
	void succeedingTest() {
		/* no-op */
	}

	@Test
	void failingTest() {
		fail("Failing for failing's sake.");
	}

}

Test Suite

If you have multiple test classes you can create a test suite as can be seen in the following example.

import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.SuiteDisplayName;
import org.junit.runner.RunWith;

@RunWith(org.junit.platform.runner.JUnitPlatform.class)
@SuiteDisplayName("JUnit Platform Suite Demo")
@SelectPackages("example")
public class JUnitPlatformSuiteDemo {
}

The JUnitPlatformSuiteDemo will discover and run all tests in the example package and its subpackages. By default, it will only include test classes whose names either begin with Test or end with Test or Tests.

Additional Configuration Options

There are more configuration options for discovering and filtering tests than just @SelectPackages. Please consult the Javadoc of the org.junit.platform.suite.api package for further details.

Test classes and suites annotated with @RunWith(JUnitPlatform.class) cannot be executed directly on the JUnit Platform (or as a "JUnit 5" test as documented in some IDEs). Such classes and suites can only be executed using JUnit 4 infrastructure.