Enrich assertInstanceOf failure with cause

This results in the stack trace of the test subject `Throwable` being
reported along with the failure.

Author: vy

documentation/src/docs/asciidoc/release-notes/release-notes-6.1.0-M1.adoc

@@ -52,7 +52,9 @@ repository on GitHub.
 * Introduce new `dynamicContainer(Consumer<? super Configuration>)` factory method for
   dynamic containers. It allows configuring the `ExecutionMode` of the dynamic container
   and/or its children in addition to its display name, test source URI, and children.
-
+* Enrich `assertInstanceOf` failure using the test subject `Throwable` as cause. It
+  results in the stack trace of the test subject `Throwable` to get reported along with
+  the failure.
 
 [[release-notes-6.1.0-M1-junit-vintage]]
 === JUnit Vintage

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

@@ -55,6 +55,7 @@ private static <T> T assertInstanceOf(Class<T> expectedType, @Nullable Object ac
 					.reason(actualValue == null ? "Unexpected null value" : "Unexpected type") //
 					.expected(expectedType) //
 					.actual(actualValue == null ? null : actualValue.getClass()) //
+					.cause(actualValue instanceof Throwable t ? t : null) //
 					.buildAndThrow();
 		}
 		return expectedType.cast(actualValue);

jupiter-tests/src/test/java/org/junit/jupiter/api/AssertInstanceOfAssertionsTests.java

@@ -96,15 +96,19 @@ private void assertInstanceOfFails(Class<?> expectedType, @Nullable Object actua
 		String valueType = actualValue == null ? "null" : actualValue.getClass().getCanonicalName();
 		String expectedMessage = "Unexpected %s, expected: <%s> but was: <%s>".formatted(unexpectedSort,
 			expectedType.getCanonicalName(), valueType);
+		Throwable expectedCause = actualValue instanceof Throwable throwable ? throwable : null;
 
-		assertThrowsWithMessage(expectedMessage, () -> assertInstanceOf(expectedType, actualValue));
-		assertThrowsWithMessage("extra ==> " + expectedMessage,
+		assertThrowsWithMessage(expectedMessage, expectedCause, () -> assertInstanceOf(expectedType, actualValue));
+		assertThrowsWithMessage("extra ==> " + expectedMessage, expectedCause,
 			() -> assertInstanceOf(expectedType, actualValue, "extra"));
-		assertThrowsWithMessage("extra ==> " + expectedMessage,
+		assertThrowsWithMessage("extra ==> " + expectedMessage, expectedCause,
 			() -> assertInstanceOf(expectedType, actualValue, () -> "extra"));
 	}
 
-	private void assertThrowsWithMessage(String expectedMessage, Executable executable) {
-		assertEquals(expectedMessage, assertThrows(AssertionFailedError.class, executable).getMessage());
+	private void assertThrowsWithMessage(String expectedMessage, @Nullable Throwable expectedCause,
+			Executable executable) {
+		Throwable throwable = assertThrows(AssertionFailedError.class, executable);
+		assertEquals(expectedMessage, throwable.getMessage());
+		assertSame(expectedCause, throwable.getCause());
 	}
 }