Deprecate junit-vintage-engine to clarify its purpose

marcphilipp · marcphilipp · commit f8f62812328a · 2025-06-02T17:08:30.000+02:00
diff --git a/documentation/documentation.gradle.kts b/documentation/documentation.gradle.kts
@@ -165,7 +165,7 @@ tasks {
 		args.addAll("--config=junit.platform.reporting.open.xml.enabled=true")
 		args.addAll("--config=junit.platform.output.capture.stdout=true")
 		args.addAll("--config=junit.platform.output.capture.stderr=true")
-		args.addAll("--config=junit.platform.discovery.issue.severity.critical=info")
+		args.addAll("--config=junit.platform.discovery.issue.severity.critical=warn")
 		outputs.dir(consoleLauncherTestReportsDir)
 		argumentProviders.add(CommandLineArgumentProvider {
 			listOf(
@@ -202,6 +202,7 @@ tasks {
 		(options as JUnitPlatformOptions).apply {
 			includeEngines("junit-vintage")
 			includeTags("timeout")
+			systemProperty("junit.platform.discovery.issue.severity.critical", "warn")
 		}
 	}
 
diff --git a/documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-M1.adoc b/documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-M1.adoc
@@ -132,7 +132,11 @@ repository on GitHub.
 [[release-notes-6.0.0-M1-junit-vintage-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes
 
-* ❓
+* The JUnit Vintage engine is now deprecated and will report an INFO level discovery issue
+  when it finds at least one JUnit 4 test class. For now, the intent of the deprecation is
+  not to signal removal in the next major version but to clarify the intended purpose of
+  the engine. It should only be used temporarily while migrating tests to JUnit Jupiter or
+  another testing framework with native JUnit Platform support.
 
 [[release-notes-6.0.0-M1-junit-vintage-new-features-and-improvements]]
 ==== New Features and Improvements
diff --git a/junit-vintage-engine/src/main/java/module-info.java b/junit-vintage-engine/src/main/java/module-info.java
@@ -16,6 +16,7 @@
  * @provides org.junit.platform.engine.TestEngine The {@code VintageTestEngine}
  * runs JUnit 3 and 4 based tests on the platform.
  */
+@SuppressWarnings("deprecation")
 module org.junit.vintage.engine {
 
 	requires static org.apiguardian.api;
diff --git a/junit-vintage-engine/src/main/java/org/junit/vintage/engine/Constants.java b/junit-vintage-engine/src/main/java/org/junit/vintage/engine/Constants.java
@@ -10,17 +10,19 @@
 
 package org.junit.vintage.engine;
 
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
-import static org.apiguardian.api.API.Status.STABLE;
 
 import org.apiguardian.api.API;
 
 /**
  * Collection of constants related to the {@link VintageTestEngine}.
  *
- * @since 5.12
+ * @deprecated Should only be used temporarily while migrating tests to JUnit
+ * Jupiter or another testing framework with native JUnit Platform support
  */
-@API(status = STABLE, since = "5.12")
+@Deprecated(since = "6.0")
+@API(status = DEPRECATED, since = "6.0")
 public final class Constants {
 
 	/**
diff --git a/junit-vintage-engine/src/main/java/org/junit/vintage/engine/VintageTestEngine.java b/junit-vintage-engine/src/main/java/org/junit/vintage/engine/VintageTestEngine.java
@@ -10,7 +10,7 @@
 
 package org.junit.vintage.engine;
 
-import static org.apiguardian.api.API.Status.INTERNAL;
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.junit.platform.engine.TestExecutionResult.successful;
 import static org.junit.vintage.engine.descriptor.VintageTestDescriptor.ENGINE_ID;
 
@@ -31,8 +31,11 @@
  * The JUnit Vintage {@link TestEngine}.
  *
  * @since 4.12
+ * @deprecated Should only be used temporarily while migrating tests to JUnit
+ * Jupiter or another testing framework with native JUnit Platform support
  */
-@API(status = INTERNAL, since = "4.12")
+@Deprecated(since = "6.0")
+@API(status = DEPRECATED, since = "6.0")
 public final class VintageTestEngine implements TestEngine {
 
 	@Override
diff --git a/junit-vintage-engine/src/main/java/org/junit/vintage/engine/discovery/VintageDiscoverer.java b/junit-vintage-engine/src/main/java/org/junit/vintage/engine/discovery/VintageDiscoverer.java
@@ -14,6 +14,7 @@
 
 import org.apiguardian.api.API;
 import org.junit.platform.commons.support.scanning.ClassFilter;
+import org.junit.platform.engine.DiscoveryIssue;
 import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.UniqueId;
@@ -45,6 +46,13 @@ public VintageEngineDescriptor discover(EngineDiscoveryRequest discoveryRequest,
 			RunnerTestDescriptor runnerTestDescriptor = (RunnerTestDescriptor) testDescriptor;
 			postProcessor.applyFiltersAndCreateDescendants(runnerTestDescriptor);
 		}
+		if (!engineDescriptor.getChildren().isEmpty()) {
+			var issue = DiscoveryIssue.create(DiscoveryIssue.Severity.INFO, //
+				"The JUnit Vintage engine is deprecated and should only be " //
+						+ "used temporarily while migrating tests to JUnit Jupiter or another testing " //
+						+ "framework with native JUnit Platform support.");
+			discoveryRequest.getDiscoveryListener().issueEncountered(uniqueId, issue);
+		}
 		return engineDescriptor;
 	}
 
diff --git a/junit-vintage-engine/src/main/java/org/junit/vintage/engine/execution/VintageExecutor.java b/junit-vintage-engine/src/main/java/org/junit/vintage/engine/execution/VintageExecutor.java
@@ -12,10 +12,6 @@
 
 import static java.util.Objects.requireNonNullElse;
 import static org.apiguardian.api.API.Status.INTERNAL;
-import static org.junit.vintage.engine.Constants.PARALLEL_CLASS_EXECUTION;
-import static org.junit.vintage.engine.Constants.PARALLEL_EXECUTION_ENABLED;
-import static org.junit.vintage.engine.Constants.PARALLEL_METHOD_EXECUTION;
-import static org.junit.vintage.engine.Constants.PARALLEL_POOL_SIZE;
 
 import java.util.ArrayList;
 import java.util.Iterator;
@@ -34,12 +30,14 @@
 import org.junit.platform.engine.EngineExecutionListener;
 import org.junit.platform.engine.ExecutionRequest;
 import org.junit.platform.engine.TestDescriptor;
+import org.junit.vintage.engine.Constants;
 import org.junit.vintage.engine.descriptor.RunnerTestDescriptor;
 import org.junit.vintage.engine.descriptor.VintageEngineDescriptor;
 
 /**
  * @since 5.12
  */
+@SuppressWarnings({ "deprecation", "RedundantSuppression" })
 @API(status = INTERNAL, since = "5.12")
 public class VintageExecutor {
 
@@ -62,9 +60,11 @@ public VintageExecutor(VintageEngineDescriptor engineDescriptor, EngineExecution
 		this.engineExecutionListener = engineExecutionListener;
 		this.request = request;
 		this.parallelExecutionEnabled = request.getConfigurationParameters().getBoolean(
-			PARALLEL_EXECUTION_ENABLED).orElse(false);
-		this.classes = request.getConfigurationParameters().getBoolean(PARALLEL_CLASS_EXECUTION).orElse(false);
-		this.methods = request.getConfigurationParameters().getBoolean(PARALLEL_METHOD_EXECUTION).orElse(false);
+			Constants.PARALLEL_EXECUTION_ENABLED).orElse(false);
+		this.classes = request.getConfigurationParameters().getBoolean(Constants.PARALLEL_CLASS_EXECUTION).orElse(
+			false);
+		this.methods = request.getConfigurationParameters().getBoolean(Constants.PARALLEL_METHOD_EXECUTION).orElse(
+			false);
 	}
 
 	public void executeAllChildren() {
@@ -110,7 +110,7 @@ private boolean executeInParallel() {
 	}
 
 	private int getThreadPoolSize() {
-		Optional<String> optionalPoolSize = request.getConfigurationParameters().get(PARALLEL_POOL_SIZE);
+		Optional<String> optionalPoolSize = request.getConfigurationParameters().get(Constants.PARALLEL_POOL_SIZE);
 		if (optionalPoolSize.isPresent()) {
 			try {
 				int poolSize = Integer.parseInt(optionalPoolSize.get());
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/JUnit4ParameterizedTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/JUnit4ParameterizedTests.java
@@ -63,6 +63,7 @@ private void executeTests(DiscoverySelector selector) {
 			request()
 				.selectors(selector)
 				.filters(includeEngines("junit-vintage"))
+				.enableImplicitConfigurationParameters(false)
 				.build()
 		);
 		// @formatter:on
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageLauncherIntegrationTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageLauncherIntegrationTests.java
@@ -280,7 +280,9 @@ public void executionFinished(TestIdentifier testIdentifier, TestExecutionResult
 	}
 
 	private LauncherDiscoveryRequest toRequest(LauncherDiscoveryRequestBuilder requestBuilder) {
-		return requestBuilder.filters(includeEngines(ENGINE_ID)).build();
+		return requestBuilder.filters(includeEngines(ENGINE_ID)) //
+				.enableImplicitConfigurationParameters(false) //
+				.build();
 	}
 
 }
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineBasicTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineBasicTests.java
@@ -20,6 +20,7 @@
  *
  * @since 4.12
  */
+@SuppressWarnings("deprecation")
 class VintageTestEngineBasicTests {
 
 	private final VintageTestEngine vintage = new VintageTestEngine();
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineDiscoveryTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineDiscoveryTests.java
@@ -40,12 +40,15 @@
 
 import org.junit.jupiter.api.Test;
 import org.junit.platform.commons.util.ClassUtils;
+import org.junit.platform.engine.DiscoveryIssue.Severity;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.TestTag;
 import org.junit.platform.engine.UniqueId;
 import org.junit.platform.engine.support.descriptor.ClassSource;
 import org.junit.platform.engine.support.descriptor.MethodSource;
 import org.junit.platform.launcher.LauncherDiscoveryRequest;
+import org.junit.platform.testkit.engine.EngineDiscoveryResults;
+import org.junit.platform.testkit.engine.EngineTestKit;
 import org.junit.runner.manipulation.Filter;
 import org.junit.vintage.engine.samples.PlainOldJavaClassWithoutAnyTestsTestCase;
 import org.junit.vintage.engine.samples.junit3.JUnit3SuiteWithSingleTestCaseWithSingleTestWhichFails;
@@ -76,8 +79,6 @@
  */
 class VintageTestEngineDiscoveryTests {
 
-	VintageTestEngine engine = new VintageTestEngine();
-
 	@Test
 	void resolvesSimpleJUnit4TestClass() throws Exception {
 		Class<?> testClass = PlainJUnit4TestCaseWithSingleTestWhichFails.class;
@@ -702,6 +703,28 @@ void resolvesTestSourceForParameterizedTests() throws Exception {
 		assertMethodSource(testClass.getMethod("test"), testMethodDescriptor);
 	}
 
+	@Test
+	void reportsNoDiscoveryIssuesWhenNoTestsAreFound() {
+		var request = discoveryRequestForClass(PlainOldJavaClassWithoutAnyTestsTestCase.class);
+
+		var results = discover(request);
+
+		assertThat(results.getDiscoveryIssues()).isEmpty();
+	}
+
+	@Test
+	void reportDiscoveryIssueWhenTestsAreFound() {
+		var request = discoveryRequestForClass(PlainJUnit4TestCaseWithSingleTestWhichFails.class);
+
+		var results = discover(request);
+
+		assertThat(results.getDiscoveryIssues()).hasSize(1);
+
+		var issue = results.getDiscoveryIssues().getFirst();
+		assertThat(issue.severity()).isEqualTo(Severity.INFO);
+		assertThat(issue.message()).contains("JUnit Vintage engine is deprecated");
+	}
+
 	private TestDescriptor findChildByDisplayName(TestDescriptor runnerDescriptor, String displayName) {
 		// @formatter:off
 		var children = runnerDescriptor.getChildren();
@@ -715,7 +738,12 @@ private TestDescriptor findChildByDisplayName(TestDescriptor runnerDescriptor, S
 	}
 
 	private TestDescriptor discoverTests(LauncherDiscoveryRequest discoveryRequest) {
-		return engine.discover(discoveryRequest, UniqueId.forEngine(engine.getId()));
+		return discover(discoveryRequest).getEngineDescriptor();
+	}
+
+	@SuppressWarnings("deprecation")
+	private static EngineDiscoveryResults discover(LauncherDiscoveryRequest discoveryRequest) {
+		return EngineTestKit.discover(new VintageTestEngine(), discoveryRequest);
 	}
 
 	private Path getClasspathRoot(Class<?> testClass) throws Exception {
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineExecutionTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/VintageTestEngineExecutionTests.java
@@ -787,8 +787,10 @@ void executesJUnit4SuiteWithJUnit4TestCaseWithFailingDescriptionThatIsNotReporte
 	@Test
 	void executesCompletelyDynamicTestCaseDiscoveredByUniqueId() {
 		Class<?> testClass = CompletelyDynamicTestCase.class;
-		var request = LauncherDiscoveryRequestBuilder.request().selectors(
-			selectUniqueId(VintageUniqueIdBuilder.uniqueIdForClass(testClass))).build();
+		var request = LauncherDiscoveryRequestBuilder.request() //
+				.selectors(selectUniqueId(VintageUniqueIdBuilder.uniqueIdForClass(testClass))) //
+				.enableImplicitConfigurationParameters(false) //
+				.build();
 
 		execute(request).allEvents().assertEventsMatchExactly( //
 			event(engine(), started()), //
@@ -868,8 +870,10 @@ void executesUnrolledSpockFeatureMethod() {
 		// Load Groovy class via reflection to avoid compilation errors in Eclipse IDE.
 		String testClassName = "org.junit.vintage.engine.samples.spock.SpockTestCaseWithUnrolledAndRegularFeatureMethods";
 		Class<?> testClass = ReflectionUtils.loadRequiredClass(testClassName, getClass().getClassLoader());
-		var request = LauncherDiscoveryRequestBuilder.request().selectors(
-			selectMethod(testClass, "unrolled feature for #input")).build();
+		var request = LauncherDiscoveryRequestBuilder.request() //
+				.selectors(selectMethod(testClass, "unrolled feature for #input"))//
+				.enableImplicitConfigurationParameters(false) //
+				.build();
 		execute(request).allEvents().assertEventsMatchExactly( //
 			event(engine(), started()), //
 			event(uniqueIdSubstring(testClassName), started()), //
@@ -889,7 +893,10 @@ void executesRegularSpockFeatureMethod() {
 		// Load Groovy class via reflection to avoid compilation errors in Eclipse IDE.
 		String testClassName = "org.junit.vintage.engine.samples.spock.SpockTestCaseWithUnrolledAndRegularFeatureMethods";
 		Class<?> testClass = ReflectionUtils.loadRequiredClass(testClassName, getClass().getClassLoader());
-		var request = LauncherDiscoveryRequestBuilder.request().selectors(selectMethod(testClass, "regular")).build();
+		var request = LauncherDiscoveryRequestBuilder.request() //
+				.selectors(selectMethod(testClass, "regular")) //
+				.enableImplicitConfigurationParameters(false) //
+				.build();
 		execute(request).allEvents().assertEventsMatchExactly( //
 			event(engine(), started()), //
 			event(container(testClass), started()), //
@@ -924,10 +931,12 @@ private static EngineExecutionResults execute(Class<?> testClass) {
 		return execute(request(testClass));
 	}
 
+	@SuppressWarnings("deprecation")
 	private static EngineExecutionResults execute(LauncherDiscoveryRequest request) {
 		return EngineTestKit.execute(new VintageTestEngine(), request);
 	}
 
+	@SuppressWarnings("deprecation")
 	private static void execute(Class<?> testClass, EngineExecutionListener listener) {
 		TestEngine testEngine = new VintageTestEngine();
 		var discoveryRequest = request(testClass);
@@ -938,7 +947,10 @@ private static void execute(Class<?> testClass, EngineExecutionListener listener
 	}
 
 	private static LauncherDiscoveryRequest request(Class<?> testClass) {
-		return LauncherDiscoveryRequestBuilder.request().selectors(selectClass(testClass)).build();
+		return LauncherDiscoveryRequestBuilder.request() //
+				.selectors(selectClass(testClass)) //
+				.enableImplicitConfigurationParameters(false) //
+				.build();
 	}
 
 	private static boolean atLeastJUnit4_13() {
diff --git a/junit-vintage-engine/src/test/java/org/junit/vintage/engine/execution/ParallelExecutionIntegrationTests.java b/junit-vintage-engine/src/test/java/org/junit/vintage/engine/execution/ParallelExecutionIntegrationTests.java
@@ -17,10 +17,6 @@
 import static org.junit.platform.testkit.engine.EventConditions.finishedSuccessfully;
 import static org.junit.platform.testkit.engine.EventConditions.started;
 import static org.junit.platform.testkit.engine.EventConditions.test;
-import static org.junit.vintage.engine.Constants.PARALLEL_CLASS_EXECUTION;
-import static org.junit.vintage.engine.Constants.PARALLEL_EXECUTION_ENABLED;
-import static org.junit.vintage.engine.Constants.PARALLEL_METHOD_EXECUTION;
-import static org.junit.vintage.engine.Constants.PARALLEL_POOL_SIZE;
 import static org.junit.vintage.engine.descriptor.VintageTestDescriptor.SEGMENT_TYPE_RUNNER;
 import static org.junit.vintage.engine.descriptor.VintageTestDescriptor.SEGMENT_TYPE_TEST;
 import static org.junit.vintage.engine.samples.junit4.JUnit4ParallelClassesTestCase.FirstClassTestCase;
@@ -51,6 +47,7 @@
 import org.junit.platform.testkit.engine.EngineTestKit;
 import org.junit.platform.testkit.engine.Event;
 import org.junit.platform.testkit.engine.Events;
+import org.junit.vintage.engine.Constants;
 import org.junit.vintage.engine.VintageTestEngine;
 import org.junit.vintage.engine.samples.junit4.JUnit4ParallelClassesTestCase;
 import org.junit.vintage.engine.samples.junit4.JUnit4ParallelMethodsTestCase;
@@ -180,12 +177,14 @@ private Events executeInParallelSuccessfully(int poolSize, boolean parallelClass
 		}
 	}
 
+	@SuppressWarnings("deprecation")
 	private static EngineExecutionResults execute(int poolSize, boolean parallelClasses, boolean parallelMethods,
 			Class<?>... testClass) {
 		return EngineTestKit.execute(new VintageTestEngine(),
 			request(poolSize, parallelClasses, parallelMethods, testClass));
 	}
 
+	@SuppressWarnings("deprecation")
 	private static LauncherDiscoveryRequest request(int poolSize, boolean parallelClasses, boolean parallelMethods,
 			Class<?>... testClasses) {
 		var classSelectors = Arrays.stream(testClasses) //
@@ -194,10 +193,11 @@ private static LauncherDiscoveryRequest request(int poolSize, boolean parallelCl
 
 		return LauncherDiscoveryRequestBuilder.request() //
 				.selectors(classSelectors) //
-				.configurationParameter(PARALLEL_EXECUTION_ENABLED, String.valueOf(true)) //
-				.configurationParameter(PARALLEL_POOL_SIZE, String.valueOf(poolSize)) //
-				.configurationParameter(PARALLEL_CLASS_EXECUTION, String.valueOf(parallelClasses)) //
-				.configurationParameter(PARALLEL_METHOD_EXECUTION, String.valueOf(parallelMethods)) //
+				.configurationParameter(Constants.PARALLEL_EXECUTION_ENABLED, String.valueOf(true)) //
+				.configurationParameter(Constants.PARALLEL_POOL_SIZE, String.valueOf(poolSize)) //
+				.configurationParameter(Constants.PARALLEL_CLASS_EXECUTION, String.valueOf(parallelClasses)) //
+				.configurationParameter(Constants.PARALLEL_METHOD_EXECUTION, String.valueOf(parallelMethods)) //
+				.enableImplicitConfigurationParameters(false) //
 				.build();
 	}
 
diff --git a/platform-tests/src/test/java/org/junit/platform/launcher/core/LauncherFactoryTests.java b/platform-tests/src/test/java/org/junit/platform/launcher/core/LauncherFactoryTests.java
@@ -441,6 +441,7 @@ private LauncherDiscoveryRequest createLauncherDiscoveryRequestForBothStandardEn
 		return request()
 				.selectors(selectClass(JUnit4Example.class))
 				.selectors(selectClass(JUnit5Example.class))
+				.enableImplicitConfigurationParameters(false)
 				.build();
 		// @formatter:on
 	}
diff --git a/platform-tooling-support-tests/projects/graalvm-starter/build.gradle.kts b/platform-tooling-support-tests/projects/graalvm-starter/build.gradle.kts
@@ -52,6 +52,7 @@ val initializeAtBuildTime = mapOf(
 	// These need to be added to native-build-tools
 	"6.0" to listOf(
 		"org.junit.platform.commons.util.KotlinReflectionUtils",
+		"org.junit.platform.launcher.core.DiscoveryIssueNotifier\$1",
 	)
 )
 
diff --git a/platform-tooling-support-tests/projects/standalone/expected-err.txt b/platform-tooling-support-tests/projects/standalone/expected-err.txt
@@ -18,3 +18,7 @@
 - junit-platform-suite .+
 - junit-jupiter .+
 - junit-vintage .+
+>> LOGGER >>
+INFO: TestEngine with ID 'junit-vintage' encountered a non-critical issue during test discovery:
+
+(1) [INFO] The JUnit Vintage engine is deprecated and should only be used temporarily while migrating tests to JUnit Jupiter or another testing framework with native JUnit Platform support.

Original file line number	Diff line number	Diff line change
`@@ -280,7 +280,9 @@ public void executionFinished(TestIdentifier testIdentifier, TestExecutionResult`
`280`	`280`	`}`
`281`	`281`
`282`	`282`	`private LauncherDiscoveryRequest toRequest(LauncherDiscoveryRequestBuilder requestBuilder) {`
`283`		`- return requestBuilder.filters(includeEngines(ENGINE_ID)).build();`
	`283`	`+ return requestBuilder.filters(includeEngines(ENGINE_ID)) //`
	`284`	`+ .enableImplicitConfigurationParameters(false) //`
	`285`	`+ .build();`
`284`	`286`	`}`
`285`	`287`
`286`	`288`	`}`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@`
`20`	`20`	`*`
`21`	`21`	`* @since 4.12`
`22`	`22`	`*/`
	`23`	`+@SuppressWarnings("deprecation")`
`23`	`24`	`class VintageTestEngineBasicTests {`
`24`	`25`
`25`	`26`	`private final VintageTestEngine vintage = new VintageTestEngine();`