Deprecate junit-vintage-engine to clarify its purpose

Author: marcphilipp

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

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 {
 
 	/**

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

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;
 	}
 

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,11 @@ private TestDescriptor findChildByDisplayName(TestDescriptor runnerDescriptor, S
 	}
 
 	private TestDescriptor discoverTests(LauncherDiscoveryRequest discoveryRequest) {
-		return engine.discover(discoveryRequest, UniqueId.forEngine(engine.getId()));
+		return discover(discoveryRequest).getEngineDescriptor();
+	}
+
+	private static EngineDiscoveryResults discover(LauncherDiscoveryRequest discoveryRequest) {
+		return EngineTestKit.discover(new VintageTestEngine(), discoveryRequest);
 	}
 
 	private Path getClasspathRoot(Class<?> testClass) throws Exception {