Run non-inner @Nested classes to restore backward compatibility (#4700)

Since the introduction of discovery issues in 5.13, top-level and static
member classes annotated with `@Nested` were no longer executed because
the validation logic excluded them. This commit restores the old
behavior and improves the generated discovery issues for such cases.

Fixes #4686.

Author: marcphilipp

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/discovery/ClassSelectorResolver.java

@@ -15,6 +15,7 @@
 import static java.util.stream.Collectors.toCollection;
 import static java.util.stream.Collectors.toSet;
 import static org.junit.jupiter.engine.descriptor.NestedClassTestDescriptor.getEnclosingTestClasses;
+import static org.junit.jupiter.engine.discovery.predicates.TestClassPredicates.NestedClassInvalidityReason.NOT_INNER;
 import static org.junit.platform.commons.support.HierarchyTraversalMode.TOP_DOWN;
 import static org.junit.platform.commons.support.ReflectionSupport.findMethods;
 import static org.junit.platform.commons.util.FunctionUtils.where;
@@ -86,13 +87,22 @@ public Resolution resolve(ClassSelector selector, Context context) {
 
 		if (this.predicates.isAnnotatedWithNested.test(testClass)) {
 			// Class name filter is not applied to nested test classes
-			if (this.predicates.isValidNestedTestClass(testClass)) {
+			var invalidityReason = this.predicates.validateNestedTestClass(testClass);
+			if (invalidityReason == null) {
 				return toResolution(
 					context.addToParent(() -> DiscoverySelectors.selectClass(testClass.getEnclosingClass()),
 						parent -> Optional.of(newMemberClassTestDescriptor(parent, testClass))));
 			}
+			if (invalidityReason == NOT_INNER) {
+				return resolveStandaloneTestClass(context, testClass);
+			}
+			return unresolved();
 		}
-		else if (isAcceptedStandaloneTestClass(testClass)) {
+		return resolveStandaloneTestClass(context, testClass);
+	}
+
+	private Resolution resolveStandaloneTestClass(Context context, Class<?> testClass) {
+		if (isAcceptedStandaloneTestClass(testClass)) {
 			return toResolution(
 				context.addToParent(parent -> Optional.of(newStandaloneClassTestDescriptor(parent, testClass))));
 		}

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/discovery/predicates/TestClassPredicates.java

@@ -27,6 +27,7 @@
 import java.util.function.Predicate;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.ClassTemplate;
 import org.junit.jupiter.api.Nested;
 import org.junit.platform.commons.util.ReflectionUtils;
@@ -55,15 +56,16 @@ public class TestClassPredicates {
 		candidate) || looksLikeIntendedTestClass(candidate);
 	public final Predicate<Method> isTestOrTestFactoryOrTestTemplateMethod;
 
-	private final Condition<Class<?>> isValidNestedTestClass;
+	private final Condition<Class<?>> isNotPrivateUnlessAbstractNestedClass;
+	private final Condition<Class<?>> isInnerNestedClass;
 	private final Condition<Class<?>> isValidStandaloneTestClass;
 
 	public TestClassPredicates(DiscoveryIssueReporter issueReporter) {
 		this.isTestOrTestFactoryOrTestTemplateMethod = new IsTestMethod(issueReporter) //
 				.or(new IsTestFactoryMethod(issueReporter)) //
 				.or(new IsTestTemplateMethod(issueReporter));
-		this.isValidNestedTestClass = isNotPrivateUnlessAbstract("@Nested", issueReporter) //
-				.and(isInner(issueReporter));
+		this.isNotPrivateUnlessAbstractNestedClass = isNotPrivateUnlessAbstract("@Nested", issueReporter);
+		this.isInnerNestedClass = isInner(issueReporter);
 		this.isValidStandaloneTestClass = isNotPrivateUnlessAbstract("Test", issueReporter) //
 				.and(isNotLocal(issueReporter)) //
 				.and(isNotInnerUnlessAbstract(issueReporter)) //
@@ -84,8 +86,16 @@ private boolean looksLikeIntendedTestClass(Class<?> candidate, Set<Class<?>> see
 	}
 
 	public boolean isValidNestedTestClass(Class<?> candidate) {
-		return this.isValidNestedTestClass.check(candidate) //
-				&& isNotAbstract(candidate);
+		return validateNestedTestClass(candidate) == null;
+	}
+
+	public @Nullable NestedClassInvalidityReason validateNestedTestClass(Class<?> candidate) {
+		boolean isInner = this.isInnerNestedClass.check(candidate);
+		boolean isNotPrivateUnlessAbstract = this.isNotPrivateUnlessAbstractNestedClass.check(candidate);
+		if (isNotPrivateUnlessAbstract && isNotAbstract(candidate)) {
+			return isInner ? null : NestedClassInvalidityReason.NOT_INNER;
+		}
+		return NestedClassInvalidityReason.OTHER;
 	}
 
 	public boolean isValidStandaloneTestClass(Class<?> candidate) {
@@ -124,9 +134,13 @@ private static Condition<Class<?>> isNotLocal(DiscoveryIssueReporter issueReport
 	private static Condition<Class<?>> isInner(DiscoveryIssueReporter issueReporter) {
 		return issueReporter.createReportingCondition(ReflectionUtils::isInnerClass, testClass -> {
 			if (testClass.getEnclosingClass() == null) {
-				return createIssue("@Nested", testClass, "must not be a top-level class");
+				return createIssue("Top-level", testClass, "must not be annotated with @Nested",
+					"It will be executed anyway for backward compatibility. "
+							+ "You should remove the @Nested annotation to resolve this warning.");
 			}
-			return createIssue("@Nested", testClass, "must not be static");
+			return createIssue("@Nested", testClass, "must not be static",
+				"It will only be executed if discovered as a standalone test class. "
+						+ "You should remove the annotation or make it non-static to resolve this warning.");
 		});
 	}
 
@@ -141,8 +155,11 @@ private static Condition<Class<?>> isNotAnonymous(DiscoveryIssueReporter issueRe
 	}
 
 	private static DiscoveryIssue createIssue(String prefix, Class<?> testClass, String detailMessage) {
-		String message = "%s class '%s' %s. It will not be executed.".formatted(prefix, testClass.getName(),
-			detailMessage);
+		return createIssue(prefix, testClass, detailMessage, "It will not be executed.");
+	}
+
+	private static DiscoveryIssue createIssue(String prefix, Class<?> testClass, String detailMessage, String effect) {
+		String message = "%s class '%s' %s. %s".formatted(prefix, testClass.getName(), detailMessage, effect);
 		return DiscoveryIssue.builder(DiscoveryIssue.Severity.WARNING, message) //
 				.source(ClassSource.from(testClass)) //
 				.build();
@@ -151,4 +168,9 @@ private static DiscoveryIssue createIssue(String prefix, Class<?> testClass, Str
 	private static boolean isAnnotatedButNotComposed(Class<?> candidate, Class<? extends Annotation> annotationType) {
 		return !candidate.isAnnotation() && isAnnotated(candidate, annotationType);
 	}
+
+	@API(status = INTERNAL, since = "5.13.3")
+	public enum NestedClassInvalidityReason {
+		NOT_INNER, OTHER
+	}
 }

jupiter-tests/src/test/java/org/junit/jupiter/engine/NestedTestClassesTests.java

@@ -274,6 +274,40 @@ private void assertNestedCycle(Class<?> start, Class<?> from, Class<?> to) {
 				.haveExactly(1, finishedWithFailure(message(it -> it.contains(expectedMessage))));
 	}
 
+	@Test
+	void discoversButWarnsAboutTopLevelNestedTestClasses() {
+		var results = discoverTestsForClass(TopLevelNestedTestCase.class);
+
+		var engineDescriptor = results.getEngineDescriptor();
+		assertEquals(2, engineDescriptor.getDescendants().size(), "# resolved test descriptors");
+
+		var discoveryIssues = results.getDiscoveryIssues();
+		assertThat(discoveryIssues).hasSize(1);
+		assertThat(discoveryIssues.getFirst().message()) //
+				.isEqualTo(
+					"Top-level class '%s' must not be annotated with @Nested. "
+							+ "It will be executed anyway for backward compatibility. "
+							+ "You should remove the @Nested annotation to resolve this warning.",
+					TopLevelNestedTestCase.class.getName());
+	}
+
+	@Test
+	void discoversButWarnsAboutStaticNestedTestClasses() {
+		var results = discoverTestsForClass(StaticNestedTestCase.TestCase.class);
+
+		var engineDescriptor = results.getEngineDescriptor();
+		assertEquals(2, engineDescriptor.getDescendants().size(), "# resolved test descriptors");
+
+		var discoveryIssues = results.getDiscoveryIssues();
+		assertThat(discoveryIssues).hasSize(1);
+		assertThat(discoveryIssues.getFirst().message()) //
+				.isEqualTo(
+					"@Nested class '%s' must not be static. "
+							+ "It will only be executed if discovered as a standalone test class. "
+							+ "You should remove the annotation or make it non-static to resolve this warning.",
+					StaticNestedTestCase.TestCase.class.getName());
+	}
+
 	// -------------------------------------------------------------------
 
 	@SuppressWarnings("JUnitMalformedDeclaration")

jupiter-tests/src/test/java/org/junit/jupiter/engine/StaticNestedTestCase.java

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.engine;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+class StaticNestedTestCase {
+
+	@SuppressWarnings("JUnitMalformedDeclaration")
+	@Nested
+	static class TestCase {
+		@Test
+		void test() {
+		}
+	}
+
+}

jupiter-tests/src/test/java/org/junit/jupiter/engine/TopLevelNestedTestCase.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.jupiter.engine;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+@Nested
+public class TopLevelNestedTestCase {
+
+	@Test
+	void test() {
+	}
+}

jupiter-tests/src/test/java/org/junit/jupiter/engine/discovery/DiscoveryTests.java

@@ -305,8 +305,8 @@ void reportsWarningForInvalidNestedTestClass(LauncherDiscoveryRequest request) {
 				.isEqualTo("@Nested class '%s' must not be private. It will not be executed.",
 					InvalidTestCases.InvalidTestClassTestCase.Inner.class.getName());
 		assertThat(discoveryIssues.getLast().message()) //
-				.isEqualTo("@Nested class '%s' must not be static. It will not be executed.",
-					InvalidTestCases.InvalidTestClassTestCase.Inner.class.getName());
+				.startsWith("@Nested class '%s' must not be static.".formatted(
+					InvalidTestCases.InvalidTestClassTestCase.Inner.class.getName()));
 	}
 
 	static List<Named<LauncherDiscoveryRequest>> requestsForTestClassWithInvalidNestedTestClass() {

jupiter-tests/src/test/java/org/junit/jupiter/engine/discovery/predicates/TestClassPredicatesTests.java

@@ -254,7 +254,9 @@ void staticNestedClassEvaluatesToFalse() {
 			assertThat(predicates.isAnnotatedWithNestedAndValid).rejects(candidate);
 
 			var issue = DiscoveryIssue.builder(Severity.WARNING,
-				"@Nested class '%s' must not be static. It will not be executed.".formatted(candidate.getName())) //
+				"@Nested class '%s' must not be static. ".formatted(candidate.getName())
+						+ "It will only be executed if discovered as a standalone test class. "
+						+ "You should remove the annotation or make it non-static to resolve this warning.") //
 					.source(ClassSource.from(candidate)) //
 					.build();
 			assertThat(discoveryIssues.stream().distinct()).containsExactly(issue);
@@ -268,8 +270,9 @@ void topLevelClassEvaluatesToFalse() {
 			assertThat(predicates.isAnnotatedWithNestedAndValid).rejects(candidate);
 
 			var issue = DiscoveryIssue.builder(Severity.WARNING,
-				"@Nested class '%s' must not be a top-level class. It will not be executed.".formatted(
-					candidate.getName())) //
+				("Top-level class '%s' must not be annotated with @Nested. ".formatted(candidate.getName())
+						+ "It will be executed anyway for backward compatibility. "
+						+ "You should remove the @Nested annotation to resolve this warning.")) //
 					.source(ClassSource.from(candidate)) //
 					.build();
 			assertThat(discoveryIssues.stream().distinct()).containsExactly(issue);
@@ -312,7 +315,9 @@ class LocalClass {
 			assertThat(predicates.isAnnotatedWithNestedAndValid).rejects(candidate);
 
 			var issue = DiscoveryIssue.builder(Severity.WARNING,
-				"@Nested class '%s' must not be static. It will not be executed.".formatted(candidate.getName())) //
+				"@Nested class '%s' must not be static. ".formatted(candidate.getName())
+						+ "It will only be executed if discovered as a standalone test class. "
+						+ "You should remove the annotation or make it non-static to resolve this warning.") //
 					.source(ClassSource.from(candidate)) //
 					.build();
 			assertThat(discoveryIssues.stream().distinct()).containsExactly(issue);