Add Assert#expectThrows and Assert#assertThrows

Closes #1154.

Author: rschmitt

src/main/java/org/junit/Assert.java

@@ -298,7 +298,7 @@ public static void assertArrayEquals(String message, Object[] expecteds,
     public static void assertArrayEquals(Object[] expecteds, Object[] actuals) {
         assertArrayEquals(null, expecteds, actuals);
     }
-    
+
     /**
      * Asserts that two boolean arrays are equal. If they are not, an
      * {@link AssertionError} is thrown with the given message. If
@@ -313,8 +313,8 @@ public static void assertArrayEquals(Object[] expecteds, Object[] actuals) {
     public static void assertArrayEquals(String message, boolean[] expecteds,
             boolean[] actuals) throws ArrayComparisonFailure {
         internalArrayEquals(message, expecteds, actuals);
-    }    
-    
+    }
+
     /**
      * Asserts that two boolean arrays are equal. If they are not, an
      * {@link AssertionError} is thrown. If <code>expected</code> and
@@ -955,4 +955,64 @@ public static <T> void assertThat(String reason, T actual,
             Matcher<? super T> matcher) {
         MatcherAssert.assertThat(reason, actual, matcher);
     }
+
+    /**
+     * This interface facilitates the use of expectThrows from Java 8. It allows method references
+     * to void methods (that declare checked exceptions) to be passed directly into expectThrows
+     * without wrapping. It is not meant to be implemented directly.
+     *
+     * @since 4.13
+     */
+    public interface ThrowingRunnable {
+        void run() throws Throwable;
+    }
+
+    /**
+     * Asserts that {@code runnable} throws an exception of type {@code expectedThrowable} when
+     * executed. If it does not throw an exception, an {@link AssertionError} is thrown. If it
+     * throws the wrong type of exception, an {@code AssertionError} is thrown describing the
+     * mismatch; the exception that was actually thrown can be obtained by calling {@link
+     * AssertionError#getCause}.
+     *
+     * @param expectedThrowable the expected type of the exception
+     * @param runnable       a function that is expected to throw an exception when executed
+     * @since 4.13
+     */
+    public static void assertThrows(Class<? extends Throwable> expectedThrowable, ThrowingRunnable runnable) {
+        expectThrows(expectedThrowable, runnable);
+    }
+
+    /**
+     * Asserts that {@code runnable} throws an exception of type {@code expectedThrowable} when
+     * executed. If it does, the exception object is returned. If it does not throw an exception, an
+     * {@link AssertionError} is thrown. If it throws the wrong type of exception, an {@code
+     * AssertionError} is thrown describing the mismatch; the exception that was actually thrown can
+     * be obtained by calling {@link AssertionError#getCause}.
+     *
+     * @param expectedThrowable the expected type of the exception
+     * @param runnable       a function that is expected to throw an exception when executed
+     * @return the exception thrown by {@code runnable}
+     * @since 4.13
+     */
+    public static <T extends Throwable> T expectThrows(Class<T> expectedThrowable, ThrowingRunnable runnable) {
+        try {
+            runnable.run();
+        } catch (Throwable actualThrown) {
+            if (expectedThrowable.isInstance(actualThrown)) {
+                @SuppressWarnings("unchecked") T retVal = (T) actualThrown;
+                return retVal;
+            } else {
+                String mismatchMessage = format("unexpected exception type thrown;",
+                        expectedThrowable.getSimpleName(), actualThrown.getClass().getSimpleName());
+
+                // The AssertionError(String, Throwable) ctor is only available on JDK7.
+                AssertionError assertionError = new AssertionError(mismatchMessage);
+                assertionError.initCause(actualThrown);
+                throw assertionError;
+            }
+        }
+        String message = String.format("expected %s to be thrown, but nothing was thrown",
+                expectedThrowable.getSimpleName());
+        throw new AssertionError(message);
+    }
 }

src/test/java/org/junit/tests/assertion/AssertionTest.java

@@ -11,11 +11,14 @@
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.expectThrows;
 import static org.junit.Assert.fail;
 
+import java.io.IOException;
 import java.math.BigDecimal;
 
 import org.junit.Assert;
+import org.junit.Assert.ThrowingRunnable;
 import org.junit.ComparisonFailure;
 import org.junit.Test;
 import org.junit.internal.ArrayComparisonFailure;
@@ -170,7 +173,7 @@ public void oneDimensionalDoubleArraysAreNotEqual() {
     public void oneDimensionalFloatArraysAreNotEqual() {
         assertArrayEquals(new float[]{1.0f}, new float[]{2.5f}, 1.0f);
     }
-    
+
     @Test(expected = AssertionError.class)
     public void oneDimensionalBooleanArraysAreNotEqual() {
         assertArrayEquals(new boolean[]{true}, new boolean[]{false});
@@ -674,4 +677,80 @@ public void assertNotEqualsIgnoresDeltaOnNaN() {
     public void assertNotEqualsIgnoresFloatDeltaOnNaN() {
         assertNotEquals(Float.NaN, Float.NaN, 1f);
     }
+
+    @Test(expected = AssertionError.class)
+    public void expectThrowsRequiresAnExceptionToBeThrown() {
+        expectThrows(Throwable.class, nonThrowingRunnable());
+    }
+
+    @Test
+    public void expectThrowsIncludesAnInformativeDefaultMessage() {
+        try {
+            expectThrows(Throwable.class, nonThrowingRunnable());
+        } catch (AssertionError ex) {
+            assertEquals("expected Throwable to be thrown, but nothing was thrown", ex.getMessage());
+            return;
+        }
+        fail();
+    }
+
+    @Test
+    public void expectThrowsReturnsTheSameObjectThrown() {
+        NullPointerException npe = new NullPointerException();
+
+        Throwable throwable = expectThrows(Throwable.class, throwingRunnable(npe));
+
+        assertSame(npe, throwable);
+    }
+
+    @Test(expected = AssertionError.class)
+    public void expectThrowsDetectsTypeMismatchesViaExplicitTypeHint() {
+        NullPointerException npe = new NullPointerException();
+
+        expectThrows(IOException.class, throwingRunnable(npe));
+    }
+
+    @Test
+    public void expectThrowsWrapsAndPropagatesUnexpectedExceptions() {
+        NullPointerException npe = new NullPointerException("inner-message");
+
+        try {
+            expectThrows(IOException.class, throwingRunnable(npe));
+        } catch (AssertionError ex) {
+            assertSame(npe, ex.getCause());
+            assertEquals("inner-message", ex.getCause().getMessage());
+            return;
+        }
+        fail();
+    }
+
+    @Test
+    public void expectThrowsSuppliesACoherentErrorMessageUponTypeMismatch() {
+        NullPointerException npe = new NullPointerException();
+
+        try {
+            expectThrows(IOException.class, throwingRunnable(npe));
+        } catch (AssertionError error) {
+            assertEquals("unexpected exception type thrown; expected:<IOException> but was:<NullPointerException>",
+                    error.getMessage());
+            assertSame(npe, error.getCause());
+            return;
+        }
+        fail();
+    }
+
+    private static ThrowingRunnable nonThrowingRunnable() {
+        return new ThrowingRunnable() {
+            public void run() throws Throwable {
+            }
+        };
+    }
+
+    private static ThrowingRunnable throwingRunnable(final Throwable t) {
+        return new ThrowingRunnable() {
+            public void run() throws Throwable {
+                throw t;
+            }
+        };
+    }
 }