Order nested classes declared in same enclosing type deterministically (#4839)

* The methods `findNestedClasses` and `streamNestedClasses` in
  `ReflectionSupport` now return nested classes declared in the same
  enclosing class or interface ordered in a deterministic but
  intentionally nonobvious way.
* For consistency with test methods, `@Nested` classes declared in the
  same enclosing class or interface are now ordered in a deterministic
  but intentionally nonobvious way.

Author: marcphilipp

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

@@ -21,7 +21,9 @@ repository on GitHub.
 [[release-notes-6.0.0-RC1-junit-platform-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes
 
-* ❓
+* The methods `findNestedClasses` and `streamNestedClasses` in `ReflectionSupport` now
+  return nested classes declared in the same enclosing class or interface ordered in a
+  deterministic but intentionally nonobvious way.
 
 [[release-notes-6.0.0-RC1-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
@@ -47,7 +49,9 @@ repository on GitHub.
 [[release-notes-6.0.0-RC1-junit-jupiter-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes
 
-* ❓
+* For consistency with test methods, `@Nested` classes declared in the same enclosing
+  class or interface are now ordered in a deterministic but intentionally nonobvious
+  way.
 
 [[release-notes-6.0.0-RC1-junit-jupiter-new-features-and-improvements]]
 ==== New Features and Improvements

junit-platform-commons/src/main/java/org/junit/platform/commons/support/ReflectionSupport.java

@@ -632,6 +632,10 @@ public static Stream<Method> streamMethods(Class<?> clazz, Predicate<Method> pre
 	 * <p>This method does <strong>not</strong> search for nested classes
 	 * recursively.
 	 *
+	 * <p>Nested classes declared in the same enclosing class or interface will
+	 * be ordered using an algorithm that is deterministic but intentionally
+	 * nonobvious.
+	 *
 	 * <p>As of JUnit Platform 1.6, this method detects cycles in <em>inner</em>
 	 * class hierarchies &mdash; from the supplied class up to the outermost
 	 * enclosing class &mdash; and throws a {@link JUnitException} if such a cycle
@@ -658,6 +662,10 @@ public static List<Class<?>> findNestedClasses(Class<?> clazz, Predicate<Class<?
 	 * <p>This method does <strong>not</strong> search for nested classes
 	 * recursively.
 	 *
+	 * <p>Nested classes declared in the same enclosing class or interface will
+	 * be ordered using an algorithm that is deterministic but intentionally
+	 * nonobvious.
+	 *
 	 * <p>As of JUnit Platform 1.6, this method detects cycles in <em>inner</em>
 	 * class hierarchies &mdash; from the supplied class up to the outermost
 	 * enclosing class &mdash; and throws a {@link JUnitException} if such a cycle

junit-platform-commons/src/main/java/org/junit/platform/commons/util/ReflectionUtils.java

@@ -1182,7 +1182,7 @@ private static void visitAllNestedClasses(Class<?> clazz, Predicate<Class<?>> pr
 
 		try {
 			// Candidates in current class
-			for (Class<?> nestedClass : clazz.getDeclaredClasses()) {
+			for (Class<?> nestedClass : toSortedMutableList(clazz.getDeclaredClasses())) {
 				if (predicate.test(nestedClass)) {
 					consumer.accept(nestedClass);
 					if (detectInnerClassCycle(nestedClass, errorHandling)) {
@@ -1698,6 +1698,10 @@ private static List<Method> toSortedMutableList(Method[] methods) {
 		return toSortedMutableList(methods, ReflectionUtils::defaultMethodSorter);
 	}
 
+	private static List<Class<?>> toSortedMutableList(Class<?>[] fields) {
+		return toSortedMutableList(fields, ReflectionUtils::defaultClassSorter);
+	}
+
 	private static <T> List<T> toSortedMutableList(T[] items, Comparator<? super T> comparator) {
 		List<T> result = new ArrayList<>(items.length);
 		Collections.addAll(result, items);
@@ -1730,6 +1734,19 @@ private static int defaultMethodSorter(Method method1, Method method2) {
 		return comparison;
 	}
 
+	/**
+	 * Class comparator to achieve deterministic but nonobvious order.
+	 */
+	private static int defaultClassSorter(Class<?> class1, Class<?> class2) {
+		String name1 = class1.getName();
+		String name2 = class2.getName();
+		int comparison = Integer.compare(name1.hashCode(), name2.hashCode());
+		if (comparison == 0) {
+			comparison = name1.compareTo(name2);
+		}
+		return comparison;
+	}
+
 	private static List<Method> getInterfaceMethods(Class<?> clazz, HierarchyTraversalMode traversalMode) {
 		List<Method> allInterfaceMethods = new ArrayList<>();
 		for (Class<?> ifc : clazz.getInterfaces()) {

platform-tests/src/test/java/org/junit/platform/commons/util/ReflectionUtilsTests.java

@@ -1152,6 +1152,15 @@ void findNestedClassesWithRecursiveHierarchies() {
 				runnable4, runnable4, runnable4, runnable5, runnable5, runnable5).parallel().forEach(Runnable::run);
 		}
 
+		@Test
+		void findNestedClassesWithMultipleNestedClasses() {
+			var nestedClasses = findNestedClasses(OuterClassWithMultipleNestedClasses.class);
+
+			assertThat(nestedClasses) //
+					.map(Class::getSimpleName) //
+					.containsExactly("Beta", "Zeta", "Eta", "Alpha", "Delta", "Gamma", "Theta", "Epsilon");
+		}
+
 		private static List<Class<?>> findNestedClasses(Class<?> clazz) {
 			return ReflectionUtils.findNestedClasses(clazz, c -> true);
 		}
@@ -2326,4 +2335,23 @@ class InnerClassImplementingInterface implements InterfaceWithNestedClass {
 		}
 	}
 
+	static class OuterClassWithMultipleNestedClasses {
+		class Alpha {
+		}
+		class Beta {
+		}
+		class Gamma {
+		}
+		class Delta {
+		}
+		class Epsilon {
+		}
+		class Zeta {
+		}
+		class Eta {
+		}
+		class Theta {
+		}
+	}
+
 }