Merge branch 'master' into Timeout-rule-builder

Author: kcooney

doc/ReleaseNotes4.12.md

@@ -95,6 +95,27 @@ This allows for validation to be added to annotations. Validators should extend
 `ExpectedException` didn't handle `AssertionError`s and `AssumptionViolatedException` well. This has been fixed. The new documentation explains the usage of `ExpectedException` for testing these exceptions. The two methods `handleAssertionErrors()` and `handleAssumptionViolatedExceptions()` are not needed anymore. If you have used them, just remove it and read `ExpectedException`'s documentation.
 
 
+### [Pull request #818:](https://github.com/junit-team/junit/pull/818) External version of AssumptionViolatedException
+
+In JUnit 4.11 and earlier, if you wanted to write a custom runner that handled
+`AssumptionViolatedException` or you needed to create an instance of `AssumptionViolatedException`
+directly, you needed to import an internal class (`org.junit.internal.AssumptionViolatedException`).
+Now you can import `org.junit.AssumptionViolatedException` (which extends
+`org.junit.internal.AssumptionViolatedException`).
+
+The classes in `Assume` have been modified to throw `org.junit.AssumptionViolatedException`.
+
+
+### [Pull request #985:](https://github.com/junit-team/junit/pull/985) Change AssumptionViolatedException to not set the cause to null; fixes issue #494
+
+Previously, the `AssumptionViolatedException` constructors would explicitly set the cause to `null`
+(unless you use a constructor where you provide a `Throwable`, in which case it would set that as
+the cause). This prevented code directly creating the exception from setting a cause.
+
+With this change, the cause is only set if you pass in a `Throwable`.
+
+It's recommended that you create `AssumptionViolatedException` via the methods in `Assume`.
+
 
 ### [Pull request #542:](https://github.com/junit-team/junit/pull/542) Customized failure message for `ExpectedException`
 
@@ -565,11 +586,6 @@ Follow this link for _IntelliJ IDEA_: [http://www.jetbrains.com/idea/webhelp/act
 # Miscellaneous
 
 
-### [Pull request #862:] (https://github.com/junit-team/junit/pull/862) Delete classes that are deprecated for six years
-
-`JUnit4ClassRunner` was deprecated in JUnit 4.3 (six years and nine major releases ago) with a comment saying "This may disappear as soon as 1 April 2009". We started having some problems with running the tests in JDK 7, and we decided to delete the class and its support classes. Although we try very hard to maintain backwards compatibility, `JUnit4ClassRunner` didn't support `Rule`s, it wasn't designed to be extensible, and it was in an internal package. Please use `BlockJUnit4ClassRunner` instead.
-
-
 ### [Pull request #776:](https://github.com/junit-team/junit/pull/776) Add support for [Travis CI](http://travis-ci.org)
 
 Travis CI is a free CI server for public Github repositories. Every pull request is run by Travis CI and Github's web interface shows the CI result for each pull request. Every user can use Travis CI for testing her branches, too.

src/main/java/org/junit/experimental/theories/ParameterSupplier.java

@@ -2,6 +2,42 @@
 
 import java.util.List;
 
+/**
+ * Abstract parent class for suppliers of input data points for theories. Extend this class to customize how {@link
+ * org.junit.experimental.theories.Theories Theories} runner
+ * finds accepted data points. Then use your class together with <b>&#064;ParametersSuppliedBy</b> on input
+ * parameters for theories.
+ *
+ * <p>
+ * For example, here is a supplier for values between two integers, and an annotation that references it:
+ *
+ * <pre>
+ *     &#064;Retention(RetentionPolicy.RUNTIME)
+ *     <b>&#064;ParametersSuppliedBy</b>(BetweenSupplier.class)
+ *     public @interface Between {
+ *         int first();
+ *
+ *         int last();
+ *     }
+ *
+ *     public static class BetweenSupplier extends <b>ParameterSupplier</b> {
+ *         &#064;Override
+ *         public List&lt;<b>PotentialAssignment</b>&gt; getValueSources(<b>ParameterSignature</b> sig) {
+ *             List&lt;<b>PotentialAssignment</b>&gt; list = new ArrayList&lt;PotentialAssignment&gt;();
+ *             Between annotation = (Between) sig.getSupplierAnnotation();
+ *
+ *             for (int i = annotation.first(); i &lt;= annotation.last(); i++)
+ *                 list.add(<b>PotentialAssignment</b>.forValue("ints", i));
+ *             return list;
+ *         }
+ *     }
+ * </pre>
+ * </p>
+ *
+ * @see org.junit.experimental.theories.ParametersSuppliedBy
+ * @see org.junit.experimental.theories.Theories
+ * @see org.junit.experimental.theories.FromDataPoints
+ */
 public abstract class ParameterSupplier {
     public abstract List<PotentialAssignment> getValueSources(ParameterSignature sig) throws Throwable;
 }

src/main/java/org/junit/experimental/theories/Theories.java

@@ -18,6 +18,56 @@
 import org.junit.runners.model.Statement;
 import org.junit.runners.model.TestClass;
 
+/**
+ * The Theories runner allows to test a certain functionality against a subset of an infinite set of data points.
+ * <p>
+ * A Theory is a piece of functionality (a method) that is executed against several data inputs called data points.
+ * To make a test method a theory you mark it with <b>&#064;Theory</b>. To create a data point you create a public
+ * field in your test class and mark it with <b>&#064;DataPoint</b>. The Theories runner then executes your test
+ * method as many times as the number of data points declared, providing a different data point as
+ * the input argument on each invocation.
+ * </p>
+ * <p>
+ * A Theory differs from standard test method in that it captures some aspect of the intended behavior in possibly
+ * infinite numbers of scenarios which corresponds to the number of data points declared. Using assumptions and
+ * assertions properly together with covering multiple scenarios with different data points can make your tests more
+ * flexible and bring them closer to scientific theories (hence the name).
+ * </p>
+ * <p>
+ * For example:
+ * <pre>
+ *
+ * &#064;RunWith(<b>Theories.class</b>)
+ * public class UserTest {
+ *      <b>&#064;DataPoint</b>
+ *      public static String GOOD_USERNAME = "optimus";
+ *      <b>&#064;DataPoint</b>
+ *      public static String USERNAME_WITH_SLASH = "optimus/prime";
+ *
+ *      <b>&#064;Theory</b>
+ *      public void filenameIncludesUsername(String username) {
+ *          assumeThat(username, not(containsString("/")));
+ *          assertThat(new User(username).configFileName(), containsString(username));
+ *      }
+ * }
+ * </pre>
+ * This makes it clear that the user's filename should be included in the config file name,
+ * only if it doesn't contain a slash. Another test or theory might define what happens when a username does contain
+ * a slash. <code>UserTest</code> will attempt to run <code>filenameIncludesUsername</code> on every compatible data
+ * point defined in the class. If any of the assumptions fail, the data point is silently ignored. If all of the
+ * assumptions pass, but an assertion fails, the test fails.
+ * <p>
+ * Defining general statements as theories allows data point reuse across a bunch of functionality tests and also
+ * allows automated tools to search for new, unexpected data points that expose bugs.
+ * </p>
+ * <p>
+ * The support for Theories has been absorbed from the Popper project, and more complete documentation can be found
+ * from that projects archived documentation.
+ * </p>
+ *
+ * @see <a href="http://web.archive.org/web/20071012143326/popper.tigris.org/tutorial.html">Archived Popper project documentation</a>
+ * @see <a href="http://web.archive.org/web/20110608210825/http://shareandenjoy.saff.net/tdd-specifications.pdf">Paper on Theories</a>
+ */
 public class Theories extends BlockJUnit4ClassRunner {
     public Theories(Class<?> klass) throws InitializationError {
         super(klass);

src/main/java/org/junit/experimental/theories/Theory.java

@@ -6,6 +6,11 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks test methods that should be read as theories by the {@link org.junit.experimental.theories.Theories Theories} runner.
+ *
+ * @see org.junit.experimental.theories.Theories
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(METHOD)
 public @interface Theory {

src/main/java/org/junit/experimental/theories/suppliers/TestedOnSupplier.java

@@ -7,6 +7,10 @@
 import org.junit.experimental.theories.ParameterSupplier;
 import org.junit.experimental.theories.PotentialAssignment;
 
+/**
+ * @see org.junit.experimental.theories.suppliers.TestedOn
+ * @see org.junit.experimental.theories.ParameterSupplier
+ */
 public class TestedOnSupplier extends ParameterSupplier {
     @Override
     public List<PotentialAssignment> getValueSources(ParameterSignature sig) {

src/main/java/org/junit/internal/AssumptionViolatedException.java

@@ -26,11 +26,14 @@ public class AssumptionViolatedException extends RuntimeException implements Sel
     private final Matcher<?> matcher;
 
     public AssumptionViolatedException(String assumption, boolean valueMatcher, Object value, Matcher<?> matcher) {
-        super(value instanceof Throwable ? (Throwable) value : null);
         this.assumption = assumption;
         this.value = value;
         this.matcher = matcher;
         this.valueMatcher = valueMatcher;
+
+        if (value instanceof Throwable) {
+          initCause((Throwable) value);
+        }
     }
 
     /**
@@ -87,4 +90,4 @@ public void describeTo(Description description) {
             }
         }
     }
-}
+}

src/main/java/org/junit/internal/ComparisonCriteria.java

@@ -1,6 +1,7 @@
 package org.junit.internal;
 
 import java.lang.reflect.Array;
+import java.util.Arrays;
 
 import org.junit.Assert;
 
@@ -24,7 +25,11 @@ public abstract class ComparisonCriteria {
      */
     public void arrayEquals(String message, Object expecteds, Object actuals)
             throws ArrayComparisonFailure {
-        if (expecteds == actuals) {
+        if (expecteds == actuals
+            || Arrays.deepEquals(new Object[] {expecteds}, new Object[] {actuals})) {
+            // The reflection-based loop below is potentially very slow, especially for primitive
+            // arrays. The deepEquals check allows us to circumvent it in the usual case where
+            // the arrays are exactly equal.
             return;
         }
         String header = message == null ? "" : message + ": ";

src/main/java/org/junit/internal/JUnitSystem.java

@@ -3,5 +3,12 @@
 import java.io.PrintStream;
 
 public interface JUnitSystem {
+
+    /**
+     * Will be removed in the next major release
+     */
+    @Deprecated
+    void exit(int code);
+
     PrintStream out();
 }

src/main/java/org/junit/internal/RealSystem.java

@@ -3,6 +3,15 @@
 import java.io.PrintStream;
 
 public class RealSystem implements JUnitSystem {
+
+    /**
+     * Will be removed in the next major release
+     */
+    @Deprecated
+    public void exit(int code) {
+        System.exit(code);
+    }
+
     public PrintStream out() {
         return System.out;
     }

src/main/java/org/junit/internal/matchers/ThrowableCauseMatcher.java

@@ -5,33 +5,46 @@
 import org.hamcrest.Matcher;
 import org.hamcrest.TypeSafeMatcher;
 
+/**
+ * A matcher that applies a delegate matcher to the cause of the current Throwable, returning the result of that
+ * match.
+ *
+ * @param <T> the type of the throwable being matched
+ */
 public class ThrowableCauseMatcher<T extends Throwable> extends
         TypeSafeMatcher<T> {
 
-    private final Matcher<T> matcher;
+    private final Matcher<? extends Throwable> causeMatcher;
 
-    public ThrowableCauseMatcher(Matcher<T> matcher) {
-        this.matcher = matcher;
+    public ThrowableCauseMatcher(Matcher<? extends Throwable> causeMatcher) {
+        this.causeMatcher = causeMatcher;
     }
 
     public void describeTo(Description description) {
         description.appendText("exception with cause ");
-        description.appendDescriptionOf(matcher);
+        description.appendDescriptionOf(causeMatcher);
     }
 
     @Override
     protected boolean matchesSafely(T item) {
-        return matcher.matches(item.getCause());
+        return causeMatcher.matches(item.getCause());
     }
 
     @Override
     protected void describeMismatchSafely(T item, Description description) {
         description.appendText("cause ");
-        matcher.describeMismatch(item.getCause(), description);
+        causeMatcher.describeMismatch(item.getCause(), description);
     }
 
+    /**
+     * Returns a matcher that verifies that the outer exception has a cause for which the supplied matcher
+     * evaluates to true.
+     *
+     * @param matcher to apply to the cause of the outer exception
+     * @param <T> type of the outer exception
+     */
     @Factory
-    public static <T extends Throwable> Matcher<T> hasCause(final Matcher<T> matcher) {
+    public static <T extends Throwable> Matcher<T> hasCause(final Matcher<? extends Throwable> matcher) {
         return new ThrowableCauseMatcher<T>(matcher);
     }
 }

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

@@ -0,0 +1,81 @@
+package org.junit.internal.runners;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.List;
+
+import org.junit.internal.AssumptionViolatedException;
+import org.junit.runner.Description;
+import org.junit.runner.notification.Failure;
+import org.junit.runner.notification.RunNotifier;
+import org.junit.runners.BlockJUnit4ClassRunner;
+
+/**
+ * @deprecated Included for backwards compatibility with JUnit 4.4. Will be
+ *             removed in the next major release. Please use
+ *             {@link BlockJUnit4ClassRunner} in place of {@link JUnit4ClassRunner}.
+ */
+@Deprecated
+public class ClassRoadie {
+    private RunNotifier notifier;
+    private TestClass testClass;
+    private Description description;
+    private final Runnable runnable;
+
+    public ClassRoadie(RunNotifier notifier, TestClass testClass,
+            Description description, Runnable runnable) {
+        this.notifier = notifier;
+        this.testClass = testClass;
+        this.description = description;
+        this.runnable = runnable;
+    }
+
+    protected void runUnprotected() {
+        runnable.run();
+    }
+
+    protected void addFailure(Throwable targetException) {
+        notifier.fireTestFailure(new Failure(description, targetException));
+    }
+
+    public void runProtected() {
+        try {
+            runBefores();
+            runUnprotected();
+        } catch (FailedBefore e) {
+        } finally {
+            runAfters();
+        }
+    }
+
+    private void runBefores() throws FailedBefore {
+        try {
+            try {
+                List<Method> befores = testClass.getBefores();
+                for (Method before : befores) {
+                    before.invoke(null);
+                }
+            } catch (InvocationTargetException e) {
+                throw e.getTargetException();
+            }
+        } catch (AssumptionViolatedException e) {
+            throw new FailedBefore();
+        } catch (Throwable e) {
+            addFailure(e);
+            throw new FailedBefore();
+        }
+    }
+
+    private void runAfters() {
+        List<Method> afters = testClass.getAfters();
+        for (Method after : afters) {
+            try {
+                after.invoke(null);
+            } catch (InvocationTargetException e) {
+                addFailure(e.getTargetException());
+            } catch (Throwable e) {
+                addFailure(e); // Untested, but seems impossible
+            }
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+package org.junit.internal.runners;
+
+import org.junit.runners.BlockJUnit4ClassRunner;
+
+/**
+ * @deprecated Included for backwards compatibility with JUnit 4.4. Will be
+ *             removed in the next major release. Please use
+ *             {@link BlockJUnit4ClassRunner} in place of {@link JUnit4ClassRunner}.
+ */
+@Deprecated
+class FailedBefore extends Exception {
+    private static final long serialVersionUID = 1L;
+}