Deprecate expectThrows in favor of assertThrows returning the exception

Prior to this commit, expectThrows() returned the thrown exception;
whereas, assertThrows() simply swallowed the exception. This lead to
confusion for users since it was not readily clear which variant should
be used. In addition, expectThrows() was the only method in the
Assertions class (other than the necessary fail() variants) that was not
named assert*().

This commit addresses this issue by refactoring assertThrows() to return
the thrown exception and deprecating the existing (and now duplicated)
expectThrows() method.

Closes: #531

documentation/src/docs/asciidoc/release-notes-5.0.0-M3.adoc

@@ -102,14 +102,16 @@ on GitHub.
 
 * The `Executable` functional interface has been relocated to a new dedicated
   `org.junit.jupiter.api.function` package.
+* `Assertions.expectThrows()` has been deprecated in favor of `Assertions.assertThrows()`.
 
-====== New Features
+====== New Features and Improvements
 
 * Support for lazy and preemptive _timeouts_ with lambda expressions in `Assertions`. See
   examples in <<writing-tests-assertions,`AssertionsDemo`>> and consult the
   `{Assertions}` Javadoc for further details.
 * New variants of `Assertions.assertAll()` that accept streams of executables (i.e.,
   `Stream<Executable>`).
+* `Assertions.assertThrows()` now returns the thrown exception.
 
 
 [[release-notes-5.0.0-m3-junit-vintage]]

documentation/src/test/java/example/AssertionsDemo.java

@@ -16,10 +16,10 @@
 import static java.time.Duration.ofMinutes;
 import static org.junit.jupiter.api.Assertions.assertAll;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTimeout;
 import static org.junit.jupiter.api.Assertions.assertTimeoutPreemptively;
 import static org.junit.jupiter.api.Assertions.assertTrue;
-import static org.junit.jupiter.api.Assertions.expectThrows;
 
 import org.junit.jupiter.api.Test;
 
@@ -49,7 +49,7 @@ void groupedAssertions() {
 
 	@Test
 	void exceptionTesting() {
-		Throwable exception = expectThrows(IllegalArgumentException.class, () -> {
+		Throwable exception = assertThrows(IllegalArgumentException.class, () -> {
 			throw new IllegalArgumentException("a message");
 		});
 		assertEquals("a message", exception.getMessage());

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

@@ -1007,30 +1007,16 @@ public static void assertAll(String heading, Stream<Executable> executables) thr
 
 	/**
 	 * <em>Asserts</em> that execution of the supplied {@code executable} throws
-	 * an exception of the {@code expectedType}.
+	 * 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>Use {@link #assertThrows} if you do not want to perform additional checks on
-	 * the exception instance. Otherwise use {@link #expectThrows}.
-	 */
-	public static void assertThrows(Class<? extends Throwable> expectedType, Executable executable) {
-		expectThrows(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>Use {@link #expectThrows} if you want to perform additional checks on the exception instance.
-	 * Otherwise use {@link #assertThrows}.</p>
+	 * <p>If you do not want to perform additional checks on the exception instance,
+	 * simply ignore the return value.
 	 */
 	@SuppressWarnings("unchecked")
-	public static <T extends Throwable> T expectThrows(Class<T> expectedType, Executable executable) {
+	public static <T extends Throwable> T assertThrows(Class<? extends Throwable> expectedType, Executable executable) {
 		try {
 			executable.execute();
 		}
@@ -1048,6 +1034,14 @@ public static <T extends Throwable> T expectThrows(Class<T> expectedType, Execut
 			String.format("Expected %s to be thrown, but nothing was thrown.", expectedType.getName()));
 	}
 
+	/**
+	 * @deprecated Use {@link #assertThrows(Class, Executable)} instead.
+	 */
+	@Deprecated
+	public static <T extends Throwable> T expectThrows(Class<T> expectedType, Executable executable) {
+		return assertThrows(expectedType, executable);
+	}
+
 	// --- assertTimeout -------------------------------------------------------
 
 	/**