Add assertArg overload for consumers throwing checked exceptions (#…

…2991)

src/main/java/org/mockito/ArgumentMatchers.java

@@ -929,6 +929,23 @@ public static <T> T assertArg(Consumer<T> consumer) {
                 });
     }
 
+    /**
+     * Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.
+     * Consumer is allowed to throw exception other than RuntimeException
+     * <p>
+     * Typically used with {@link Mockito#verify(Object)} to execute assertions on parameters passed to the verified method invocation.
+     *
+     * @param consumer executes assertions on the verified argument
+     * @return <code>null</code>.
+     */
+    public static <T> T assertArg(ThrowingConsumer<T> consumer) {
+        return argThat(
+                argument -> {
+                    consumer.accept(argument);
+                    return true;
+                });
+    }
+
     /**
      * Allows creating custom <code>char</code> argument matchers.
      * <p>

src/main/java/org/mockito/ThrowingConsumer.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2023 Mockito contributors
+ * This program is made available under the terms of the MIT License.
+ */
+package org.mockito;
+
+import java.util.function.Consumer;
+
+@SuppressWarnings("FunctionalInterfaceMethodChanged")
+@FunctionalInterface
+public interface ThrowingConsumer<T> extends Consumer<T> {
+    @Override
+    default void accept(final T input) {
+        try {
+            acceptThrows(input);
+        } catch (final RuntimeException | AssertionError e) {
+            throw e;
+        } catch (Throwable e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    void acceptThrows(T input) throws Throwable;
+}

src/test/java/org/mockitousage/matchers/MatchersTest.java

@@ -34,6 +34,7 @@
 import static org.mockito.Mockito.anyShort;
 import static org.mockito.Mockito.anyString;
 import static org.mockito.Mockito.contains;
+import static org.mockito.Mockito.doThrow;
 import static org.mockito.Mockito.endsWith;
 import static org.mockito.Mockito.isA;
 import static org.mockito.Mockito.isNotNull;
@@ -47,6 +48,7 @@
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
+import java.io.IOException;
 import java.math.BigDecimal;
 import java.util.ArrayList;
 import java.util.List;
@@ -646,6 +648,24 @@ public void assertArg_matcher_fails_when_assertion_fails() throws Exception {
         }
     }
 
+    @Test
+    public void assertArg_matcher_can_accept_throwing_consumer() throws Exception {
+        mock.oneArg("hello");
+
+        try {
+            verify(mock)
+                    .oneArg(
+                            assertArg(
+                                    (String it) -> {
+                                        assertEquals("not-hello", it);
+                                        doThrow(new IOException()).when(mock).throwsIOException(0);
+                                    }));
+            fail("Should throw an exception");
+        } catch (ComparisonFailure e) {
+            // do nothing
+        }
+    }
+
     @Test
     public void can_invoke_method_on_mock_after_assert_arg() throws Exception {
         mock.oneArg("hello");