Skip to content

Commit

Permalink
Deprecate the JUnitPlatform runner in favor of @suite support
Browse files Browse the repository at this point in the history 
Closes #2712
  • Loading branch information
@sbrannen
sbrannen committed Sep 9, 2021
1 parent 3ad2d8c commit 8ac3dfb
Show file tree
Hide file tree
Showing 17 changed files with 61 additions and 37 deletions.
5 changes: 4 additions & 1 deletion documentation/src/docs/asciidoc/release-notes/release-notes-5.8.0.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

*Date of Release:* September ❓, 2021

*Scope:* ❓
*Scope:*

* Declarative test suites via `@Suite` classes
* `LauncherSession` and accompanying listener
Expand Down Expand Up @@ -45,6 +45,9 @@ on GitHub.

==== Deprecations and Breaking Changes

* The `JUnitPlatform` runner has been deprecated in favor of the new `@Suite` support. See
the warning in <<../user-guide/index.adoc#running-tests-junit-platform-runner, Using
JUnit 4 to run the JUnit Platform>> for details.
* For consistency with the rest of the JUnit Platform, the experimental
`LauncherDiscoveryListener` is now an interface instead of an abstract class.

Expand Down
22 changes: 20 additions & 2 deletions documentation/src/docs/asciidoc/user-guide/running-tests.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -604,6 +604,25 @@ subject to expansion.
[[running-tests-junit-platform-runner]]
=== Using JUnit 4 to run the JUnit Platform

[WARNING]
.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 has 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.
Expand All @@ -613,8 +632,7 @@ build systems that support JUnit 4 but do not yet support the JUnit Platform dir

NOTE: 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 <<running-tests-junit-platform-runner-technical-names>>). But for the
time being the `JUnitPlatform` runner is an easy way to get started.
to reporting (see <<running-tests-junit-platform-runner-technical-names>>).

[[running-tests-junit-platform-runner-setup]]
==== Setup
Expand Down
7 changes: 3 additions & 4 deletions documentation/src/test/java/example/DocumentationTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package example;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.ExcludeTags;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* <h3>Logging Configuration</h3>
Expand All @@ -29,9 +28,9 @@
*
* @since 5.0
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("example")
@IncludeClassNamePatterns(".+(Tests|Demo)$")
@ExcludeTags("exclude")
public class DocumentationTestSuite {
class DocumentationTestSuite {
}
6 changes: 4 additions & 2 deletions documentation/src/test/java/example/JUnitPlatformClassDemo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,12 @@
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)
//end::user_guide[]
@SuppressWarnings("deprecation")
//tag::user_guide[]
@RunWith(org.junit.platform.runner.JUnitPlatform.class)
public class JUnitPlatformClassDemo {

@Test
Expand Down
4 changes: 2 additions & 2 deletions documentation/src/test/java/example/JUnitPlatformSuiteDemo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@
package example;

//tag::user_guide[]
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)
@RunWith(org.junit.platform.runner.JUnitPlatform.class)
@SuiteDisplayName("JUnit Platform Suite Demo")
@SelectPackages("example")
//end::user_guide[]
@SuppressWarnings("deprecation")
@org.junit.platform.suite.api.ExcludeTags("exclude")
//tag::user_guide[]
public class JUnitPlatformSuiteDemo {
Expand Down
3 changes: 2 additions & 1 deletion junit-jupiter-engine/junit-jupiter-engine.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ dependencies {
compileOnlyApi(libs.apiguardian)

testImplementation(projects.junitPlatformLauncher)
testImplementation(projects.junitPlatformRunner)
testImplementation(projects.junitPlatformSuiteEngine)
testImplementation(projects.junitPlatformTestkit)
testImplementation(testFixtures(projects.junitPlatformCommons))
testImplementation(kotlin("stdlib"))
testImplementation(libs.junit4)
testImplementation(libs.kotlinx.coroutines)
testImplementation(libs.groovy3)
}
Expand Down
7 changes: 3 additions & 4 deletions junit-jupiter-engine/src/test/java/org/junit/jupiter/JupiterTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package org.junit.jupiter;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* Test suite for the JUnit Jupiter programming model, extension model, and
Expand All @@ -32,9 +31,9 @@
*
* @since 5.0
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("org.junit.jupiter")
@IncludeClassNamePatterns(".*Tests?")
@IncludeEngines("junit-jupiter")
public class JupiterTestSuite {
class JupiterTestSuite {
}
2 changes: 1 addition & 1 deletion junit-jupiter-migrationsupport/junit-jupiter-migrationsupport.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ dependencies {

testImplementation(projects.junitJupiterEngine)
testImplementation(projects.junitPlatformLauncher)
testImplementation(projects.junitPlatformRunner)
testImplementation(projects.junitPlatformSuiteEngine)
testImplementation(projects.junitPlatformTestkit)
}

Expand Down
7 changes: 3 additions & 4 deletions ...rt/src/test/java/org/junit/jupiter/migrationsupport/JupiterMigrationSupportTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package org.junit.jupiter.migrationsupport;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* Test suite for JUnit Jupiter migration support.
Expand All @@ -31,9 +30,9 @@
*
* @since 5.0
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("org.junit.jupiter.migrationsupport")
@IncludeClassNamePatterns(".*Tests?")
@IncludeEngines("junit-jupiter")
public class JupiterMigrationSupportTestSuite {
class JupiterMigrationSupportTestSuite {
}
2 changes: 1 addition & 1 deletion junit-jupiter-params/junit-jupiter-params.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ dependencies {
testImplementation(projects.junitPlatformTestkit)
testImplementation(projects.junitJupiterEngine)
testImplementation(projects.junitPlatformLauncher)
testImplementation(projects.junitPlatformRunner)
testImplementation(projects.junitPlatformSuiteEngine)

compileOnly(kotlin("stdlib"))
testImplementation(kotlin("stdlib"))
Expand Down
7 changes: 3 additions & 4 deletions junit-jupiter-params/src/test/java/org/junit/jupiter/params/ParameterizedTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package org.junit.jupiter.params;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* Test suite for JUnit Jupiter parameterized test support.
Expand All @@ -31,9 +30,9 @@
*
* @since 5.0
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("org.junit.jupiter.params")
@IncludeClassNamePatterns(".*Tests?")
@IncludeEngines("junit-jupiter")
public class ParameterizedTestSuite {
class ParameterizedTestSuite {
}
8 changes: 6 additions & 2 deletions junit-platform-runner/src/main/java/org/junit/platform/runner/JUnitPlatform.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
package org.junit.platform.runner;

import static java.util.stream.Collectors.toList;
import static org.apiguardian.api.API.Status.STABLE;
import static org.apiguardian.api.API.Status.DEPRECATED;
import static org.junit.platform.commons.support.AnnotationSupport.isAnnotated;
import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;
import static org.junit.platform.suite.commons.SuiteLauncherDiscoveryRequestBuilder.request;
Expand Down Expand Up @@ -45,6 +45,7 @@
import org.junit.platform.suite.api.SelectModules;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.SelectUris;
import org.junit.platform.suite.api.Suite;
import org.junit.platform.suite.api.SuiteDisplayName;
import org.junit.platform.suite.api.UseTechnicalNames;
import org.junit.platform.suite.commons.SuiteLauncherDiscoveryRequestBuilder;
Expand Down Expand Up @@ -105,8 +106,11 @@
* @see SuiteDisplayName
* @see UseTechnicalNames
* @see ConfigurationParameter
* @deprecated since 1.8, in favor of the {@link Suite @Suite} support provided by
* the {@code junit-platform-suite-engine} module; to be removed in JUnit Platform 2.0
*/
@API(status = STABLE, since = "1.0")
@API(status = DEPRECATED, since = "1.8")
@Deprecated
public class JUnitPlatform extends Runner implements Filterable {

// @formatter:off
Expand Down
2 changes: 1 addition & 1 deletion junit-vintage-engine/junit-vintage-engine.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ dependencies {
testFixturesImplementation(projects.junitPlatformRunner)

testImplementation(projects.junitPlatformLauncher)
testImplementation(projects.junitPlatformRunner)
testImplementation(projects.junitPlatformSuiteEngine)
testImplementation(projects.junitPlatformTestkit)
}

Expand Down
7 changes: 3 additions & 4 deletions junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package org.junit.vintage.engine;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* Test suite for the {@link VintageTestEngine}.
Expand All @@ -31,9 +30,9 @@
*
* @since 4.12
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("org.junit.vintage.engine")
@IncludeClassNamePatterns(".*Tests?")
@IncludeEngines("junit-jupiter")
public class VintageTestEngineTestSuite {
class VintageTestEngineTestSuite {
}
1 change: 1 addition & 0 deletions ...ures/java/org/junit/vintage/engine/samples/junit4/TestCaseRunWithJUnitPlatformRunner.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
/**
* @since 4.12
*/
@SuppressWarnings("deprecation")
@RunWith(JUnitPlatform.class)
@SelectClasses(PlainJUnit4TestCaseWithSingleTestWhichFails.class)
public class TestCaseRunWithJUnitPlatformRunner {
Expand Down
7 changes: 3 additions & 4 deletions platform-tests/src/test/java/org/junit/platform/JUnitPlatformTestSuite.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@

package org.junit.platform;

import org.junit.platform.runner.JUnitPlatform;
import org.junit.platform.suite.api.IncludeClassNamePatterns;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.runner.RunWith;
import org.junit.platform.suite.api.Suite;

/**
* Test suite for the JUnit Platform.
Expand All @@ -31,9 +30,9 @@
*
* @since 1.0
*/
@RunWith(JUnitPlatform.class)
@Suite
@SelectPackages("org.junit.platform")
@IncludeClassNamePatterns(".*Tests?")
@IncludeEngines("junit-jupiter")
public class JUnitPlatformTestSuite {
class JUnitPlatformTestSuite {
}
1 change: 1 addition & 0 deletions platform-tests/src/test/java/org/junit/platform/runner/JUnitPlatformRunnerTests.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@
* @since 1.0
*/
@Tag("junit4")
@SuppressWarnings("deprecation")
class JUnitPlatformRunnerTests {

@Nested
Expand Down

2 comments on commit 8ac3dfb

@mpkorstanje
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think UseTechnicalNames should be deprecated too. It is a JUnit4 specific workaround that is not needed with the Suite Engine.

So once the JUnitPlatformRunner is removed so would/could/should UseTechnicalNames .

@sbrannen
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I pondered that as well while working on that issue.

In the end I decided that I'd leave it undeprecated in case we find there is a need for it with @Suite support in certain reporting scenarios.

In any case, feel free to open a new issue to deprecate @UseTechnicalNames, and the team will reassess that (potentially for 5.8.1).

Please sign in to comment.