Added ability to provide custom message to assertThrows\expectThrows methods

CHANGES.txt

@@ -1,4 +1,5 @@
 Current
+New: Ability to provide custom error message for assertThrows\expectThrows methods (Anatolii Yuzhakov)
 Fixed: GITHUB-2780: Use SpotBugs instead of abandoned FindBugs
 
 7.6.1

testng-asserts/src/main/java/org/testng/Assert.java

@@ -2223,6 +2223,22 @@ public static <T extends Throwable> void assertThrows(
     expectThrows(throwableClass, runnable);
   }
 
+  /**
+   * Asserts that {@code runnable} throws an exception of type {@code throwableClass} 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 message fail message
+   * @param throwableClass the expected type of the exception
+   * @param <T> the expected type of the exception
+   * @param runnable A function that is expected to throw an exception when invoked
+   */
+  public static <T extends Throwable> void assertThrows(
+      String message, Class<T> throwableClass, ThrowingRunnable runnable) {
+    expectThrows(message, throwableClass, runnable);
+  }
+
   /**
    * Asserts that {@code runnable} throws an exception of type {@code throwableClass} when executed
    * and returns the exception. If {@code runnable} does not throw an exception, an {@link
@@ -2238,6 +2254,24 @@ public static <T extends Throwable> void assertThrows(
    */
   public static <T extends Throwable> T expectThrows(
       Class<T> throwableClass, ThrowingRunnable runnable) {
+    return expectThrows(null, throwableClass, runnable);
+  }
+
+  /**
+   * Asserts that {@code runnable} throws an exception of type {@code throwableClass} when executed
+   * and returns the exception. If {@code runnable} 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 message fail message
+   * @param throwableClass the expected type of the exception
+   * @param <T> the expected type of the exception
+   * @param runnable A function that is expected to throw an exception when invoked
+   * @return The exception thrown by {@code runnable}
+   */
+  public static <T extends Throwable> T expectThrows(
+      String message, Class<T> throwableClass, ThrowingRunnable runnable) {
     try {
       runnable.run();
     } catch (Throwable t) {
@@ -2249,12 +2283,12 @@ public static <T extends Throwable> T expectThrows(
                 "Expected %s to be thrown, but %s was thrown",
                 throwableClass.getSimpleName(), t.getClass().getSimpleName());
 
-        throw new AssertionError(mismatchMessage, t);
+        throw new AssertionError(message != null ? message : mismatchMessage, t);
       }
     }
-    String message =
+    String nothingThrownMessage =
         String.format(
             "Expected %s to be thrown, but nothing was thrown", throwableClass.getSimpleName());
-    throw new AssertionError(message);
+    throw new AssertionError(message != null ? message : nothingThrownMessage);
   }
 }

testng-asserts/src/test/java/test/asserttests/AssertTest.java

@@ -240,6 +240,33 @@ public void expectThrowsSuppliesACoherentErrorMessageUponTypeMismatch() {
     fail();
   }
 
+  @Test
+  public void expectThrowsWithErrorMessageProvidedByClientUponTypeMismatch() {
+    NullPointerException npe = new NullPointerException();
+    String messageProvidedByClient = "Client's message";
+
+    try {
+      expectThrows(messageProvidedByClient, IOException.class, throwingRunnable(npe));
+    } catch (AssertionError error) {
+      assertEquals(messageProvidedByClient, error.getMessage());
+      return;
+    }
+    fail();
+  }
+
+  @Test
+  public void expectThrowsWithErrorMessageProvidedByClientWhenNothingWasThrown() {
+    String messageProvidedByClient = "Client's message";
+
+    try {
+      expectThrows(messageProvidedByClient, Throwable.class, nonThrowingRunnable());
+    } catch (AssertionError error) {
+      assertEquals(messageProvidedByClient, error.getMessage());
+      return;
+    }
+    fail();
+  }
+
   private static ThrowingRunnable nonThrowingRunnable() {
     return () -> {};
   }