Add assertThrows variants which accept exceptions as values

Signed-off-by: Matthew de Detrich <matthew.dedetrich@gls-itservices.com>

Author: Matthew de Detrich

documentation/modules/ROOT/partials/release-notes/release-notes-6.2.0-M1.adoc

@@ -32,6 +32,10 @@ repository on GitHub.
 * When using a third-party engine that uses the `junit-` prefix a discovery issue is
   emitted.
 * `junit-platform-console-standalone` is now part of the `junit-bom`
+* The `org.junit.jupiter.api.assertThrows` Kotlin API and its related functions have
+  added variants that use an exception class as a value rather than a type parameter.
+  This is to primarily to address the current issue/s when trying to use
+  `@ParameterizedTest` that produces exceptions as values.
 
 [[v6.2.0-M1-junit-jupiter]]
 === JUnit Jupiter

junit-jupiter-api/src/main/kotlin/org/junit/jupiter/api/Assertions.kt

@@ -285,6 +285,39 @@ inline fun <reified T : Throwable> assertThrows(executable: () -> Unit): T {
     }
 }
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows(IllegalArgumentException::class.java) {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ * This version of assertThrows is intended to be used in situations where reified Throwable's cannot be used,
+ * i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrows
+ */
+inline fun <T : Throwable> assertThrows(
+    expectedType: Class<T>,
+    executable: () -> Unit
+): T {
+    // no contract for `executable` because it is expected to throw an exception instead
+    // of being executed completely (see https://youtrack.jetbrains.com/issue/KT-27748)
+    val throwable: Throwable? =
+        try {
+            executable()
+        } catch (caught: Throwable) {
+            caught
+        } as? Throwable
+
+    return Assertions.assertThrows(expectedType) {
+        if (throwable != null) {
+            throw throwable
+        }
+    }
+}
+
 /**
  * Example usage:
  * ```kotlin
@@ -300,6 +333,25 @@ inline fun <reified T : Throwable> assertThrows(
     executable: () -> Unit
 ): T = assertThrows({ message }, executable)
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows(IllegalArgumentException::class.java, "Should throw an Exception") {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ * This version of assertThrows is intended to be used in situations where reified Throwable's cannot be used,
+ * i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrows
+ */
+inline fun <T : Throwable> assertThrows(
+    expectedType: Class<T>,
+    message: String,
+    executable: () -> Unit
+): T = assertThrows(expectedType, { message }, executable)
+
 /**
  * Example usage:
  * ```kotlin
@@ -339,6 +391,49 @@ inline fun <reified T : Throwable> assertThrows(
     )
 }
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows(IllegalArgumentException::class.java, { "Should throw an Exception" }) {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ * This version of assertThrows is intended to be used in situations where reified Throwable's cannot be used,
+ * i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrows
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T : Throwable> assertThrows(
+    expectedType: Class<T>,
+    noinline message: () -> String,
+    executable: () -> Unit
+): T {
+    contract {
+        callsInPlace(message, AT_MOST_ONCE)
+        // no contract for `executable` because it is expected to throw an exception instead
+        // of being executed completely (see https://youtrack.jetbrains.com/issue/KT-27748)
+    }
+
+    val throwable: Throwable? =
+        try {
+            executable()
+        } catch (caught: Throwable) {
+            caught
+        } as? Throwable
+
+    return Assertions.assertThrows(
+        expectedType,
+        {
+            if (throwable != null) {
+                throw throwable
+            }
+        },
+        message
+    )
+}
+
 /**
  * Example usage:
  * ```kotlin
@@ -366,6 +461,39 @@ inline fun <reified T : Throwable> assertThrowsExactly(executable: () -> Unit):
     }
 }
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrows(IllegalArgumentException::class.java) {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ *  This version of assertThrowsExactly is intended to be used in situations where reified Throwable's cannot be used,
+ *  i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrowsExactly
+ */
+inline fun <T : Throwable> assertThrowsExactly(
+    expectedType: Class<T>,
+    executable: () -> Unit
+): T {
+    // no contract for `executable` because it is expected to throw an exception instead
+    // of being executed completely (see https://youtrack.jetbrains.com/issue/KT-27748)
+    val throwable: Throwable? =
+        try {
+            executable()
+        } catch (caught: Throwable) {
+            caught
+        } as? Throwable
+
+    return Assertions.assertThrowsExactly(expectedType) {
+        if (throwable != null) {
+            throw throwable
+        }
+    }
+}
+
 /**
  * Example usage:
  * ```kotlin
@@ -381,6 +509,25 @@ inline fun <reified T : Throwable> assertThrowsExactly(
     executable: () -> Unit
 ): T = assertThrowsExactly({ message }, executable)
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrowsExactly(IllegalArgumentException::class.java, "Should throw an Exception") {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ *  This version of assertThrowsExactly is intended to be used in situations where reified Throwable's cannot be used,
+ *  i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrowsExactly
+ */
+inline fun <T : Throwable> assertThrowsExactly(
+    expectedType: Class<T>,
+    message: String,
+    executable: () -> Unit
+): T = assertThrowsExactly(expectedType, { message }, executable)
+
 /**
  * Example usage:
  * ```kotlin
@@ -420,6 +567,49 @@ inline fun <reified T : Throwable> assertThrowsExactly(
     )
 }
 
+/**
+ * Example usage:
+ * ```kotlin
+ * val exception = assertThrowsExactly(IllegalArgumentException::class.java, { "Should throw an Exception" }) {
+ *     throw IllegalArgumentException("Talk to a duck")
+ * }
+ * assertEquals("Talk to a duck", exception.message)
+ * ```
+ *
+ *  This version of assertThrowsExactly is intended to be used in situations where reified Throwable's cannot be used,
+ *  i.e. when using a @ParameterizedTest that provides exception classes as values.
+ * @see Assertions.assertThrowsExactly
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T : Throwable> assertThrowsExactly(
+    expectedType: Class<T>,
+    noinline message: () -> String,
+    executable: () -> Unit
+): T {
+    contract {
+        callsInPlace(message, AT_MOST_ONCE)
+        // no contract for `executable` because it is expected to throw an exception instead
+        // of being executed completely (see https://youtrack.jetbrains.com/issue/KT-27748)
+    }
+
+    val throwable: Throwable? =
+        try {
+            executable()
+        } catch (caught: Throwable) {
+            caught
+        } as? Throwable
+
+    return Assertions.assertThrowsExactly(
+        expectedType,
+        {
+            if (throwable != null) {
+                throw throwable
+            }
+        },
+        message
+    )
+}
+
 /**
  * Example usage:
  * ```kotlin