Add assertThrows overloads that take a ThrowingSupplier

If the given ThrowingSupplier fails to throw the expected exception and
instead returns a value, the string representation of the value is
included in the failure message to aide debugging.

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertThrows.java

@@ -18,6 +18,7 @@
 import java.util.function.Supplier;
 
 import org.junit.jupiter.api.function.Executable;
+import org.junit.jupiter.api.function.ThrowingSupplier;
 import org.opentest4j.AssertionFailedError;
 
 /**
@@ -34,25 +35,45 @@ private AssertThrows() {
 	}
 	///CLOVER:ON
 
+	static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier) {
+		return assertThrows(expectedType, supplier::get, (Object) null);
+	}
+
 	static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable) {
-		return assertThrows(expectedType, executable, (Object) null);
+		return assertThrows(expectedType, asSupplier(executable), (Object) null);
+	}
+
+	static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier, String message) {
+		return assertThrows(expectedType, supplier::get, (Object) message);
 	}
 
 	static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable, String message) {
-		return assertThrows(expectedType, executable, (Object) message);
+		return assertThrows(expectedType, asSupplier(executable), (Object) message);
+	}
+
+	static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier,
+			Supplier<String> messageSupplier) {
+		return assertThrows(expectedType, supplier::get, (Object) messageSupplier);
 	}
 
 	static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable,
 			Supplier<String> messageSupplier) {
-		return assertThrows(expectedType, executable, (Object) messageSupplier);
+		return assertThrows(expectedType, asSupplier(executable), (Object) messageSupplier);
 	}
 
 	@SuppressWarnings("unchecked")
 	private static <T extends Throwable> T assertThrows(Class<T> expectedType, Executable executable,
 			Object messageOrSupplier) {
+		return assertThrows(expectedType, asSupplier(executable), messageOrSupplier);
+	}
 
+	@SuppressWarnings("unchecked")
+	private static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingResultSupplier<?> supplier,
+			Object messageOrSupplier) {
+
+		Object result;
 		try {
-			executable.execute();
+			result = supplier.get();
 		}
 		catch (Throwable actualException) {
 			if (expectedType.isInstance(actualException)) {
@@ -66,8 +87,34 @@ private static <T extends Throwable> T assertThrows(Class<T> expectedType, Execu
 		}
 
 		String message = buildPrefix(nullSafeGet(messageOrSupplier))
-				+ String.format("Expected %s to be thrown, but nothing was thrown.", getCanonicalName(expectedType));
+				+ String.format("Expected %s to be thrown, but nothing was thrown", getCanonicalName(expectedType))
+				+ (supplier.formatResult() ? String.format(" (returned %s).", result) : ".");
 		throw new AssertionFailedError(message);
 	}
 
+	private interface ThrowingResultSupplier<T> extends ThrowingSupplier<T> {
+		/**
+		 * Returns true if the result should be included in the failure message in the case where the supplier
+		 * returns a result instead of throwing the expected exception.
+		 */
+		default boolean formatResult() {
+			return true;
+		}
+	}
+
+	private static ThrowingResultSupplier<Void> asSupplier(Executable executable) {
+		return new ThrowingResultSupplier<Void>() {
+			@Override
+			public Void get() throws Throwable {
+				executable.execute();
+				return null;
+			}
+
+			@Override
+			public boolean formatResult() {
+				return false;
+			}
+		};
+	}
+
 }

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java

@@ -1169,6 +1169,20 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 		return AssertThrows.assertThrows(expectedType, executable);
 	}
 
+	/**
+	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
+	 * an exception of the {@code expectedType} and returns the exception.
+	 *
+	 * <p>If no exception is thrown, or if an exception of a different type is
+	 * thrown, this method will fail.
+	 *
+	 * <p>If you do not want to perform additional checks on the exception instance,
+	 * simply ignore the return value.
+	 */
+	public static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier) {
+		return AssertThrows.assertThrows(expectedType, supplier);
+	}
+
 	/**
 	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
 	 * an exception of the {@code expectedType} and returns the exception.
@@ -1183,6 +1197,21 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 		return AssertThrows.assertThrows(expectedType, executable, message);
 	}
 
+	/**
+	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
+	 * an exception of the {@code expectedType} and returns the exception.
+	 *
+	 * <p>If no exception is thrown, or if an exception of a different type is
+	 * thrown, this method will fail.
+	 *
+	 * <p>If you do not want to perform additional checks on the exception instance,
+	 * simply ignore the return value.
+	 */
+	public static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier,
+			String message) {
+		return AssertThrows.assertThrows(expectedType, supplier, message);
+	}
+
 	/**
 	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
 	 * an exception of the {@code expectedType} and returns the exception.
@@ -1201,6 +1230,24 @@ public static <T extends Throwable> T assertThrows(Class<T> expectedType, Execut
 		return AssertThrows.assertThrows(expectedType, executable, messageSupplier);
 	}
 
+	/**
+	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
+	 * an exception of the {@code expectedType} and returns the exception.
+	 *
+	 * <p>If no exception is thrown, or if an exception of a different type is
+	 * thrown, this method will fail.
+	 *
+	 * <p>If necessary, the failure message will be retrieved lazily from the
+	 * supplied {@code messageSupplier}.
+	 *
+	 * <p>If you do not want to perform additional checks on the exception instance,
+	 * simply ignore the return value.
+	 */
+	public static <T extends Throwable> T assertThrows(Class<T> expectedType, ThrowingSupplier<?> supplier,
+			Supplier<String> messageSupplier) {
+		return AssertThrows.assertThrows(expectedType, supplier, messageSupplier);
+	}
+
 	// --- executable ---
 
 	/**

junit-jupiter-engine/src/test/java/org/junit/jupiter/api/AssertThrowsAssertionsTests.java

@@ -10,10 +10,7 @@
 
 package org.junit.jupiter.api;
 
-import static org.junit.jupiter.api.AssertionTestUtils.assertMessageContains;
-import static org.junit.jupiter.api.AssertionTestUtils.assertMessageEquals;
-import static org.junit.jupiter.api.AssertionTestUtils.assertMessageStartsWith;
-import static org.junit.jupiter.api.AssertionTestUtils.expectAssertionFailedError;
+import static org.junit.jupiter.api.AssertionTestUtils.*;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assumptions.assumeTrue;
@@ -235,6 +232,64 @@ void assertThrowsWithExecutableThatThrowsSameExceptionTypeFromDifferentClassLoad
 		}
 	}
 
+	@Test
+	void assertThrowsReturns() {
+		try {
+			assertThrows(EnigmaThrowable.class, () -> 42);
+			expectAssertionFailedError();
+		}
+		catch (AssertionFailedError ex) {
+			assertMessageContains(ex, "(returned 42)");
+		}
+	}
+
+	@Test
+	void assertThrowsReturnsNull() {
+		try {
+			assertThrows(EnigmaThrowable.class, () -> null);
+			expectAssertionFailedError();
+		}
+		catch (AssertionFailedError ex) {
+			assertMessageContains(ex, "(returned null)");
+		}
+	}
+
+	@Test
+	void assertThrowsReturnsVoid() {
+		try {
+			assertThrows(EnigmaThrowable.class, () -> {
+			});
+			expectAssertionFailedError();
+		}
+		catch (AssertionFailedError ex) {
+			assertMessageDoesNotContain(ex, "(returned null)");
+		}
+	}
+
+	@Test
+	void assertThrowsReturnsCustomMessage() {
+		try {
+			assertThrows(EnigmaThrowable.class, () -> 42, "custom message");
+			expectAssertionFailedError();
+		}
+		catch (AssertionFailedError ex) {
+			assertMessageContains(ex, "(returned 42)");
+			assertMessageContains(ex, "custom message");
+		}
+	}
+
+	@Test
+	void assertThrowsReturnsCustomMessageSupplier() {
+		try {
+			assertThrows(EnigmaThrowable.class, () -> 42, () -> "custom message");
+			expectAssertionFailedError();
+		}
+		catch (AssertionFailedError ex) {
+			assertMessageContains(ex, "(returned 42)");
+			assertMessageContains(ex, "custom message");
+		}
+	}
+
 	@SuppressWarnings("serial")
 	private static class LocalException extends RuntimeException {
 	}

junit-jupiter-engine/src/test/java/org/junit/jupiter/api/AssertionTestUtils.java

@@ -61,6 +61,13 @@ static void assertMessageContains(Throwable ex, String msg) throws AssertionErro
 		}
 	}
 
+	static void assertMessageDoesNotContain(Throwable ex, String msg) throws AssertionError {
+		if (ex.getMessage().contains(msg)) {
+			throw new AssertionError(
+				"Exception message should contain [" + msg + "], but was [" + ex.getMessage() + "].");
+		}
+	}
+
 	static void assertExpectedAndActualValues(AssertionFailedError ex, Object expected, Object actual)
 			throws AssertionError {
 		if (!wrapsEqualValue(ex.getExpected(), expected)) {