Add ArgumentMatchers#assertArg method (#2949)

Fixes #2285

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

@@ -14,6 +14,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.function.Consumer;
 import java.util.regex.Pattern;
 
 import org.mockito.internal.matchers.Any;
@@ -912,6 +913,22 @@ public static <T> T argThat(ArgumentMatcher<T> matcher) {
         return null;
     }
 
+    /**
+     * Allows creating custom argument matchers where matching is considered successful when the consumer given by parameter does not throw an exception.
+     * <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(Consumer<T> consumer) {
+        return argThat(
+                argument -> {
+                    consumer.accept(argument);
+                    return true;
+                });
+    }
+
     /**
      * Allows creating custom <code>char</code> argument matchers.
      * <p>

src/main/java/org/mockito/Mockito.java

@@ -39,6 +39,7 @@
 import org.mockito.verification.VerificationMode;
 import org.mockito.verification.VerificationWithTimeout;
 
+import java.util.function.Consumer;
 import java.util.function.Function;
 
 /**
@@ -1661,6 +1662,19 @@
  * With an implicit type, the Java compiler is unable to automatically determine the type of a mock and you need
  * to pass in the {@code Class} explicitly.
  * </p>
+ *
+ * <h3 id="55">55. <a class="meaningful_link" href="#verification_with_assertions" name="verification_with_assertions">
+ *  Verification with assertions</a> (Since 5.3.0)</h3>
+ *
+ * To validate arguments during verification, instead of capturing them with {@link ArgumentCaptor}, you can now
+ * use {@link ArgumentMatchers#assertArg(Consumer)}}:
+ *
+ * <pre class="code"><code class="java">
+ *   verify(serviceMock).doStuff(assertArg(param -&gt; {
+ *     assertThat(param.getField1()).isEqualTo("foo");
+ *     assertThat(param.getField2()).isEqualTo("bar");
+ *   }));
+ * </code></pre>
  */
 @CheckReturnValue
 @SuppressWarnings("unchecked")

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

@@ -20,6 +20,7 @@
 import static org.mockito.AdditionalMatchers.lt;
 import static org.mockito.AdditionalMatchers.not;
 import static org.mockito.AdditionalMatchers.or;
+import static org.mockito.ArgumentMatchers.assertArg;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.ArgumentMatchers.nullable;
 import static org.mockito.Mockito.any;
@@ -52,6 +53,7 @@
 import java.util.RandomAccess;
 import java.util.regex.Pattern;
 
+import org.junit.ComparisonFailure;
 import org.junit.Test;
 import org.mockito.ArgumentMatchers;
 import org.mockito.Mockito;
@@ -624,4 +626,51 @@ public void nullable_matcher() throws Exception {
 
         verify(mock, times(2)).oneArg(nullable(Character.class));
     }
+
+    @Test
+    public void assertArg_matcher() throws Exception {
+        mock.oneArg("hello");
+
+        verify(mock).oneArg(assertArg((String it) -> assertEquals("hello", it)));
+    }
+
+    @Test
+    public void assertArg_matcher_fails_when_assertion_fails() throws Exception {
+        mock.oneArg("hello");
+
+        try {
+            verify(mock).oneArg(assertArg((String it) -> assertEquals("not-hello", it)));
+            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");
+
+        try {
+            verify(mock).oneArg(assertArg((String it) -> assertEquals("not-hello", it)));
+            fail("Should throw an exception");
+        } catch (ComparisonFailure e) {
+            // do nothing
+        }
+
+        mock.oneArg("hello");
+    }
+
+    @Test
+    public void can_verify_on_mock_after_assert_arg() throws Exception {
+        mock.oneArg("hello");
+
+        try {
+            verify(mock).oneArg(assertArg((String it) -> assertEquals("not-hello", it)));
+            fail("Should throw an exception");
+        } catch (ComparisonFailure e) {
+            // do nothing
+        }
+
+        verify(mock).oneArg("hello");
+    }
 }