Add Assert#expectThrows

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,81 @@ 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 when executed. If it does, the exception
+     * object is returned. If it does not, an {@link AssertionError} is thrown.
+     *
+     * @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(ThrowingRunnable runnable) {
+        return (T) expectThrows(null, Throwable.class, runnable);
+    }
+
+    /**
+     * Asserts that {@code runnable} throws an exception when executed. If it does, the exception
+     * object is returned. If it does not, an {@link AssertionError} is thrown with the given {@code
+     * message}.
+     *
+     * @param message  the identifying message for the {@link AssertionError}
+     * @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(String message, ThrowingRunnable runnable) {
+        return (T) expectThrows(message, Throwable.class, runnable);
+    }
+
+    /**
+     * Asserts that {@code runnable} throws an exception of type {@code throwableClass} 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.
+     *
+     * @param throwableClass 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> throwableClass, ThrowingRunnable runnable) {
+        return expectThrows(null, throwableClass, runnable);
+    }
+
+    /**
+     * Asserts that {@code runnable} throws an exception of type {@code throwableClass} when
+     * executed. If it does, the exception object is returned. If it does not throw an exception, an
+     * {@link AssertionError} is thrown with the given {@code message}. If it throws the wrong type
+     * of exception, an {@code AssertionError} is thrown describing the mismatch.
+     *
+     * @param message        the identifying message for the {@link AssertionError}
+     * @param throwableClass 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(String message, Class<T> throwableClass, ThrowingRunnable runnable) {
+        try {
+            runnable.run();
+        } catch (Throwable t) {
+            String mismatchMessage = String.format("Expected %s to be thrown, but got %s instead",
+                    throwableClass.getSimpleName(), t.getClass().getSimpleName());
+            assertTrue(mismatchMessage, throwableClass.isInstance(t));
+            return (T) t;
+        }
+        fail(message);
+        throw new AssertionError(); // This statement is unreachable.
+    }
 }

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

@@ -11,15 +11,18 @@
 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.math.BigDecimal;
-
 import org.junit.Assert;
+import org.junit.Assert.ThrowingRunnable;
 import org.junit.ComparisonFailure;
 import org.junit.Test;
 import org.junit.internal.ArrayComparisonFailure;
 
+import java.io.IOException;
+import java.math.BigDecimal;
+
 /**
  * Tests for {@link org.junit.Assert}
  */
@@ -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,83 @@ public void assertNotEqualsIgnoresDeltaOnNaN() {
     public void assertNotEqualsIgnoresFloatDeltaOnNaN() {
         assertNotEquals(Float.NaN, Float.NaN, 1f);
     }
+
+    @Test(expected = AssertionError.class)
+    public void expectThrowsRequiresAnExceptionToBeThrown() {
+        expectThrows(nonThrowingRunnable());
+    }
+
+    @Test
+    public void expectThrowsIncludesNoMessageByDefault() {
+        try {
+            expectThrows(nonThrowingRunnable());
+        } catch (AssertionError ex) {
+            assertNull(ex.getMessage());
+            return;
+        }
+        fail();
+    }
+
+    @Test
+    public void expectThrowsIncludesTheSuppliedMessage() {
+        try {
+            expectThrows("message", nonThrowingRunnable());
+        } catch (AssertionError ex) {
+            assertEquals("message", ex.getMessage());
+            return;
+        }
+        fail();
+    }
+
+    @Test
+    public void expectThrowsReturnsTheSameObjectThrown() {
+        NullPointerException npe = new NullPointerException();
+
+        Throwable throwable = expectThrows(throwingRunnable(npe));
+
+        assertSame(npe, throwable);
+    }
+
+    @Test(expected = ClassCastException.class)
+    public void expectThrowsDetectsTypeMismatchesViaAssignment() {
+        NullPointerException npe = new NullPointerException();
+
+        IOException ioException = expectThrows(throwingRunnable(npe));
+    }
+
+    @Test(expected = AssertionError.class)
+    public void expectThrowsDetectsTypeMismatchesViaExplicitTypeHint() {
+        NullPointerException npe = new NullPointerException();
+
+        expectThrows(IOException.class, throwingRunnable(npe));
+    }
+
+    @Test
+    public void expectThrowsSuppliesACoherentErrorMessageUponTypeMismatch() {
+        NullPointerException npe = new NullPointerException();
+
+        try {
+            expectThrows(IOException.class, throwingRunnable(npe));
+        } catch (AssertionError error) {
+            assertEquals("Expected IOException to be thrown, but got NullPointerException instead",
+                    error.getMessage());
+            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;
+            }
+        };
+    }
 }