Introduce ClassOrderer.Default for reverting back to default ordering

Author: marcphilipp

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -112,6 +112,7 @@ endif::[]
 :Assumptions:                                {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/Assumptions.html[org.junit.jupiter.api.Assumptions]
 :AutoClose:                                  {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/AutoClose.html[@AutoClose]
 :ClassOrderer_ClassName:                     {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.ClassName.html[ClassOrderer.ClassName]
+:ClassOrderer_Default:                       {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.Default.html[ClassOrderer.Default]
 :ClassOrderer_DisplayName:                   {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.DisplayName.html[ClassOrderer.DisplayName]
 :ClassOrderer_OrderAnnotation:               {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.OrderAnnotation.html[ClassOrderer.OrderAnnotation]
 :ClassOrderer_Random:                        {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/ClassOrderer.Random.html[ClassOrderer.Random]

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-RC1.adoc

@@ -74,9 +74,10 @@ repository on GitHub.
   <<../user-guide/index.adoc#writing-tests-display-names, User Guide>> for details.
 * For consistency with `@TestClassOrder`, `@TestMethodOrder` annotations specified on a
   test class are now inherited to its `@Nested` inner classes, recursively.
-* Introduce `MethodOrderer.Default` for reverting back to default ordering on a `@Nested`
-  class, recursively, when an enclosing class specifies a different method orderer via
-  `@TestMethodOrder`.
+* Introduce `MethodOrderer.Default` and `ClassOrderer.Default` for reverting back to
+  default ordering on a `@Nested` class and its `@Nested` inner classes when an enclosing
+  class specifies a different orderer via `@TestMethodOrder` or `@TestClassOrder`,
+  respectively.
 
 
 [[release-notes-6.0.0-RC1-junit-vintage]]

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -1130,6 +1130,8 @@ To configure test class execution order _locally_ for `@Nested` test classes, de
 want to order, and supply a class reference to the `ClassOrderer` implementation you would
 like to use directly in the `@TestClassOrder` annotation. The configured `ClassOrderer`
 will be applied recursively to `@Nested` test classes and their `@Nested` test classes.
+If you want to avoid that a `@Nested` test class uses the same `ClassOrderer` as its
+enclosing class, you can specify `{ClassOrderer_Default}` together with `@TestClassOrder`.
 Note that a local `@TestClassOrder` declaration always overrides an inherited
 `@TestClassOrder` declaration or a `ClassOrderer` configured globally via the
 `junit.jupiter.testclass.order.default` configuration parameter.

junit-jupiter-api/src/main/java/org/junit/jupiter/api/ClassOrderer.java

@@ -11,12 +11,14 @@
 package org.junit.jupiter.api;
 
 import static java.util.Comparator.comparingInt;
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.util.Collections;
 import java.util.Comparator;
 
 import org.apiguardian.api.API;
+import org.junit.platform.commons.JUnitException;
 import org.junit.platform.commons.logging.Logger;
 import org.junit.platform.commons.logging.LoggerFactory;
 
@@ -51,6 +53,9 @@
  * <li>{@link ClassOrderer.Random}</li>
  * </ul>
  *
+ * <p>In addition, {@link ClassOrderer.Default} allows reverting back to default ordering for
+ * {@link Nested @Nested} classes.
+ *
  * @since 5.8
  * @see TestClassOrder
  * @see ClassOrdererContext
@@ -97,6 +102,35 @@ public interface ClassOrderer {
 	 */
 	void orderClasses(ClassOrdererContext context);
 
+	/**
+	 * {@code ClassOrderer} that allows to explicitly specify that the default
+	 * ordering should be applied.
+	 *
+	 * <p>If the {@value #DEFAULT_ORDER_PROPERTY_NAME} is set, specifying this
+	 * {@code ClassOrderer} has the same effect as referencing the configured
+	 * class directly. Otherwise, it has the same effect as not specifying any
+	 * {@code ClassOrderer}.
+	 *
+	 * <p>This annotation is useful to reset the {@code ClassOrderer} for a
+	 * {@link Nested @Nested} class and its {@code @Nested} inner classes,
+	 * recursively, when a {@code ClassOrderer} is configured using
+	 * {@link TestClassOrder @TestClassOrder} on an enclosing class.
+	 *
+	 * @since 6.0
+	 */
+	@API(status = EXPERIMENTAL, since = "6.0")
+	final class Default implements ClassOrderer {
+
+		private Default() {
+			throw new JUnitException("This class must not be instantiated");
+		}
+
+		@Override
+		public void orderClasses(ClassOrdererContext context) {
+			// never called
+		}
+	}
+
 	/**
 	 * {@code ClassOrderer} that sorts classes alphanumerically based on their
 	 * fully qualified names using {@link String#compareTo(String)}.

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/DefaultJupiterConfiguration.java

@@ -69,7 +69,8 @@ public class DefaultJupiterConfiguration implements JupiterConfiguration {
 			new InstantiatingConfigurationParameterConverter<>(MethodOrderer.class, "method orderer"));
 
 	private static final ConfigurationParameterConverter<ClassOrderer> classOrdererConverter = //
-		new InstantiatingConfigurationParameterConverter<>(ClassOrderer.class, "class orderer");
+		exclude(isEqual(ClassOrderer.Default.class.getName()),
+			new InstantiatingConfigurationParameterConverter<>(ClassOrderer.class, "class orderer"));
 
 	private static final ConfigurationParameterConverter<CleanupMode> cleanupModeConverter = //
 		new EnumConfigurationParameterConverter<>(CleanupMode.class, "cleanup mode");

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

@@ -113,7 +113,6 @@ private DescriptorWrapperOrderer<TestDescriptor, ClassOrderer, DefaultClassDescr
 			ClassBasedTestDescriptor classBasedTestDescriptor) {
 		return AnnotationSupport.findAnnotation(classBasedTestDescriptor.getTestClass(), TestClassOrder.class)//
 				.map(TestClassOrder::value)//
-				.map(ReflectionSupport::newInstance)//
 				.map(this::createDescriptorWrapperOrderer)//
 				.orElseGet(() -> {
 					Object parent = classBasedTestDescriptor.getParent().orElse(null);
@@ -125,6 +124,14 @@ private DescriptorWrapperOrderer<TestDescriptor, ClassOrderer, DefaultClassDescr
 				});
 	}
 
+	private DescriptorWrapperOrderer<TestDescriptor, ClassOrderer, DefaultClassDescriptor> createDescriptorWrapperOrderer(
+			Class<? extends ClassOrderer> ordererClass) {
+		if (ordererClass == ClassOrderer.Default.class) {
+			return globalOrderer;
+		}
+		return createDescriptorWrapperOrderer(ReflectionSupport.newInstance(ordererClass));
+	}
+
 	private DescriptorWrapperOrderer<TestDescriptor, ClassOrderer, DefaultClassDescriptor> createDescriptorWrapperOrderer(
 			ClassOrderer classOrderer) {
 		OrderingAction<TestDescriptor, DefaultClassDescriptor> orderingAction = (__,

jupiter-tests/src/test/java/org/junit/jupiter/engine/extension/OrderedClassTests.java

@@ -200,6 +200,24 @@ void classTemplateWithGlobalConfig() {
 				.containsSubsequence(classTemplate.getSimpleName(), otherClass.getSimpleName());
 	}
 
+	@Test
+	void nestedClassedCanUseDefaultOrder(@TrackLogRecords LogRecordListener logRecords) {
+		executeTests(null, selectClass(RevertingBackToDefaultOrderTestCase.Inner.class));
+		assertThat(callSequence).containsExactly("ShortName", "AMuchLongerNameForSure");
+		callSequence.clear();
+
+		executeTests(ClassOrderer.ClassName.class, selectClass(RevertingBackToDefaultOrderTestCase.Inner.class));
+		assertThat(callSequence).containsExactly("AMuchLongerNameForSure", "ShortName");
+		callSequence.clear();
+
+		executeTests(ClassOrderer.Default.class, selectClass(RevertingBackToDefaultOrderTestCase.Inner.class));
+		assertThat(callSequence).containsExactly("ShortName", "AMuchLongerNameForSure");
+		assertThat(logRecords.stream()) //
+				.filteredOn(it -> it.getLevel().intValue() >= Level.WARNING.intValue()) //
+				.map(LogRecord::getMessage) //
+				.isEmpty();
+	}
+
 	private static void assertIneffectiveOrderAnnotationIssues(List<DiscoveryIssue> discoveryIssues) {
 		assertThat(discoveryIssues).hasSize(2);
 		assertThat(discoveryIssues).extracting(DiscoveryIssue::severity).containsOnly(Severity.INFO);
@@ -437,4 +455,29 @@ private record Ctx() implements ClassTemplateInvocationContext {
 		}
 	}
 
+	@TestClassOrder(ClassOrderer.DisplayName.class)
+	static class RevertingBackToDefaultOrderTestCase {
+
+		@Nested
+		@TestClassOrder(ClassOrderer.Default.class)
+		class Inner {
+
+			@Nested
+			class ShortName {
+				@Test
+				void test() {
+					callSequence.add(getClass().getSimpleName());
+				}
+			}
+
+			@Nested
+			class AMuchLongerNameForSure {
+				@Test
+				void test() {
+					callSequence.add(getClass().getSimpleName());
+				}
+			}
+		}
+	}
+
 }