4.4. Using JUnit 4 to run the JUnit Platform

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.

4.4.1. 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.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-launcher in test scope

• junit-platform-engine in test scope

• junit-platform-commons in test scope

• opentest4j in test scope

4.4.2. Display Names vs. Technical Names

To define a custom display name for the class run via @RunWith(JUnitPlatform.class) simply 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, simply declare the @UseTechnicalNames annotation alongside @RunWith(JUnitPlatform.class).

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

4.4.3. 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.platform.runner.JUnitPlatform;
import org.junit.runner.RunWith;
@RunWith(JUnitPlatform.class)
public class JUnitPlatformClassDemo {
    @Test
    void succeedingTest() {
        /* no-op */
    }
    @Test
    void failingTest() {
        fail("Failing for failing's sake.");
    }
}

4.4.4. 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.runner.JUnitPlatform;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.SuiteDisplayName;
import org.junit.runner.RunWith;
@RunWith(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.