Add Ordering, Orderable and @OrderWith

src/main/java/junit/framework/JUnit4TestAdapter.java

@@ -9,8 +9,10 @@
 import org.junit.runner.Runner;
 import org.junit.runner.manipulation.Filter;
 import org.junit.runner.manipulation.Filterable;
+import org.junit.runner.manipulation.GeneralOrdering;
+import org.junit.runner.manipulation.InvalidOrderingException;
 import org.junit.runner.manipulation.NoTestsRemainException;
-import org.junit.runner.manipulation.Sortable;
+import org.junit.runner.manipulation.Orderable;
 import org.junit.runner.manipulation.Sorter;
 
 /**
@@ -23,7 +25,7 @@ public static Test suite() {
       }
 </pre>
  */
-public class JUnit4TestAdapter implements Test, Filterable, Sortable, Describable {
+public class JUnit4TestAdapter implements Test, Filterable, Orderable, Describable {
     private final Class<?> fNewTestClass;
 
     private final Runner fRunner;
@@ -93,4 +95,13 @@ public void filter(Filter filter) throws NoTestsRemainException {
     public void sort(Sorter sorter) {
         sorter.apply(fRunner);
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since 4.13
+     */
+    public void order(GeneralOrdering ordering) throws InvalidOrderingException {
+        ordering.apply(fRunner);
+    }
 }

src/main/java/org/junit/internal/runners/JUnit38ClassRunner.java

@@ -1,5 +1,8 @@
 package org.junit.internal.runners;
 
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+
 import junit.extensions.TestDecorator;
 import junit.framework.AssertionFailedError;
 import junit.framework.Test;
@@ -12,15 +15,16 @@
 import org.junit.runner.Runner;
 import org.junit.runner.manipulation.Filter;
 import org.junit.runner.manipulation.Filterable;
+import org.junit.runner.manipulation.GeneralOrdering;
+import org.junit.runner.manipulation.InvalidOrderingException;
 import org.junit.runner.manipulation.NoTestsRemainException;
+import org.junit.runner.manipulation.Orderable;
 import org.junit.runner.manipulation.Sortable;
 import org.junit.runner.manipulation.Sorter;
 import org.junit.runner.notification.Failure;
 import org.junit.runner.notification.RunNotifier;
-import java.lang.annotation.Annotation;
-import java.lang.reflect.Method;
 
-public class JUnit38ClassRunner extends Runner implements Filterable, Sortable {
+public class JUnit38ClassRunner extends Runner implements Filterable, Orderable {
     private static final class OldTestClassAdaptingListener implements
             TestListener {
         private final RunNotifier notifier;
@@ -170,6 +174,18 @@ public void sort(Sorter sorter) {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @since 4.13
+     */
+    public void order(GeneralOrdering ordering) throws InvalidOrderingException {
+        if (getTest() instanceof Orderable) {
+            Orderable adapter = (Orderable) getTest();
+            adapter.order(ordering);
+        }
+    }
+
     private void setTest(Test test) {
         this.test = test;
     }

src/main/java/org/junit/runner/OrderWith.java

@@ -0,0 +1,26 @@
+package org.junit.runner;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.runner.manipulation.Ordering;
+
+/**
+ * When a test class is annotated with <code>&#064;OrderWith</code> or extends a class annotated
+ * with <code>&#064;OrderWith</code>, JUnit will order the tests in the test class (and child
+ * test classes, if any) using the ordering defined by the {@link Ordering} class.
+ *
+ * @since 4.13
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@Inherited
+public @interface OrderWith {
+    /**
+     * Gets a class that extends {@link Ordering}. The class must have a public no-arg constructor.
+     */
+    Class<? extends Ordering.Factory> value();
+}

src/main/java/org/junit/runner/Request.java

@@ -1,5 +1,6 @@
 package org.junit.runner;
 
+import java.util.Collection;
 import java.util.Comparator;
 
 import org.junit.internal.builders.AllDefaultPossibilitiesBuilder;
@@ -8,6 +9,8 @@
 import org.junit.internal.requests.SortingRequest;
 import org.junit.internal.runners.ErrorReportingRunner;
 import org.junit.runner.manipulation.Filter;
+import org.junit.runner.manipulation.InvalidOrderingException;
+import org.junit.runner.manipulation.Ordering;
 import org.junit.runners.model.InitializationError;
 
 /**
@@ -151,15 +154,15 @@ public Request filterWith(Description desiredDescription) {
      * For example, here is code to run a test suite in alphabetical order:
      * <pre>
      * private static Comparator&lt;Description&gt; forward() {
-     * return new Comparator&lt;Description&gt;() {
-     * public int compare(Description o1, Description o2) {
-     * return o1.getDisplayName().compareTo(o2.getDisplayName());
-     * }
-     * };
+     *   return new Comparator&lt;Description&gt;() {
+     *     public int compare(Description o1, Description o2) {
+     *       return o1.getDisplayName().compareTo(o2.getDisplayName());
+     *     }
+     *   };
      * }
      *
      * public static main() {
-     * new JUnitCore().run(Request.aClass(AllTests.class).sortWith(forward()));
+     *   new JUnitCore().run(Request.aClass(AllTests.class).sortWith(forward()));
      * }
      * </pre>
      *
@@ -169,4 +172,44 @@ public Request filterWith(Description desiredDescription) {
     public Request sortWith(Comparator<Description> comparator) {
         return new SortingRequest(this, comparator);
     }
+
+    /**
+     * Returns a Request whose Tests can be run in a certain order, defined by
+     * <code>ordering</code>
+     * <p>
+     * For example, here is code to run a test suite in reverse order:
+     * <pre>
+     * private static Ordering reverse() {
+     *   return new Ordering() {
+     *     public List&lt;Description&gt; orderItems(Collection&lt;Description&gt; descriptions) {
+     *       List&lt;Description&gt; ordered = new ArrayList&lt;&gt;(descriptions);
+     *       Collections.reverse(ordered);
+     *       return ordered;
+     *     }
+     *   }
+     * }
+     *     
+     * public static main() {
+     *   new JUnitCore().run(Request.aClass(AllTests.class).orderWith(reverse()));
+     * }
+     * </pre>
+     *
+     * @return a Request with ordered Tests
+     * @since 4.13
+     */
+    public Request orderWith(final Ordering ordering) {
+        final Request delegate = this;
+        return new Request() {
+            @Override
+            public Runner getRunner() {
+                try {
+                    Runner runner = delegate.getRunner();
+                    ordering.apply(runner);
+                    return runner;
+                } catch (InvalidOrderingException e) {
+                    return new ErrorReportingRunner(ordering.getClass(), e);
+                }
+            }
+        };
+    }
 }

src/main/java/org/junit/runner/manipulation/Alphanumeric.java

@@ -0,0 +1,27 @@
+package org.junit.runner.manipulation;
+
+import java.util.Comparator;
+
+import org.junit.runner.Description;
+
+/**
+ * A sorter that orders tests alphanumerically by test name.
+ *
+ * @since 4.13
+ */
+public final class Alphanumeric extends Sorter implements Ordering.Factory {
+
+    public Alphanumeric() {
+        super(COMPARATOR);
+    }
+
+    public Ordering create(Context context) {
+        return this;
+    }
+
+    private static final Comparator<Description> COMPARATOR = new Comparator<Description>() {
+        public int compare(Description o1, Description o2) {
+            return o1.getDisplayName().compareTo(o2.getDisplayName());
+        }
+    };
+}

src/main/java/org/junit/runner/manipulation/GeneralOrdering.java

@@ -0,0 +1,41 @@
+package org.junit.runner.manipulation;
+
+import java.util.Collection;
+import java.util.List;
+
+import org.junit.runner.Description;
+
+/**
+ * An {@link Ordering} that is not a {@link Sorter}.
+ *
+ * @since 4.13
+ */
+public final class GeneralOrdering extends Ordering {
+    private final Ordering delegate;
+
+    GeneralOrdering(Ordering delegate) {
+        this.delegate = delegate;
+    }
+
+    @Override
+    protected List<Description> orderItems(Collection<Description> descriptions) {
+        return delegate.orderItems(descriptions);
+    }
+
+    @Override
+    public void apply(Object target) throws InvalidOrderingException {
+        /*
+         * We overwrite apply() to avoid having a GeneralOrdering wrap another
+         * GeneralOrdering.
+         */
+        if (target instanceof Orderable) {
+            Orderable orderable = (Orderable) target;
+            orderable.order(this);
+        }
+    }
+
+    @Override
+    boolean validateOrderingIsCorrect() {
+        return delegate.validateOrderingIsCorrect();
+    }
+}

src/main/java/org/junit/runner/manipulation/InvalidOrderingException.java

@@ -0,0 +1,21 @@
+package org.junit.runner.manipulation;
+
+/**
+ * Thrown when an ordering does something invalid (like remove or add children)
+ *
+ * @since 4.13
+ */
+public class InvalidOrderingException extends Exception {
+    private static final long serialVersionUID = 1L;
+
+    public InvalidOrderingException() {
+    }
+
+    public InvalidOrderingException(String message) {
+        super(message);
+    }
+
+    public InvalidOrderingException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

src/main/java/org/junit/runner/manipulation/Orderable.java

@@ -0,0 +1,21 @@
+package org.junit.runner.manipulation;
+
+/**
+ * Interface for runners that allow ordering of tests.
+ *
+ * <p>Beware of using this interface to cope with order dependencies between tests.
+ * Tests that are isolated from each other are less expensive to maintain and
+ * can be run individually.
+ *
+ * @since 4.13
+ */
+public interface Orderable extends Sortable {
+
+    /**
+     * Orders the tests using <code>ordering</code>
+     *
+     * @throws InvalidOrderingException if ordering does something invalid (like remove or add
+     * children)
+     */
+    void order(GeneralOrdering ordering) throws InvalidOrderingException;
+}