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;
+ }
+ };
+ }
 }