Improve output for expected argument matchers

- Add IDescribeSpecification to allow custom arg matchers to provide
  custom output for "expected to receive" entries.
- Fallback to ToString when IDescribeSpecification not implemented.
- Update code comment docs accordingly.
- Improved support for custom matchers

Closes #796.

Author: dtchepak

.gitignore

@@ -308,3 +308,7 @@ docs/_site/*
 
 # Ignore Ionide files (https://ionide.io/)
 .ionide
+
+# Ignore mergetool temp files
+*.orig
+

src/NSubstitute/Arg.cs

@@ -53,6 +53,18 @@ public static ref T Is<T>(Expression<Predicate<object?>> predicate) where T : An
         return ref ArgumentMatcher.Enqueue<T>(new ExpressionArgumentMatcher<object>(predicate));
     }
 
+    /// <summary>
+    /// Match argument that satisfies <paramref name="matcher"/>.
+    /// </summary>
+    public static ref T Is<T>(IArgumentMatcher matcher) =>
+        ref ArgumentMatcher.Enqueue<T>(matcher);
+
+    /// <summary>
+    /// Match argument that satisfies <paramref name="matcher"/>.
+    /// </summary>
+    public static ref T Is<T>(IArgumentMatcher<T> matcher) =>
+        ref ArgumentMatcher.Enqueue(matcher);
+
     /// <summary>
     /// Invoke any <see cref="Action"/> argument whenever a matching call is made to the substitute.
     /// </summary>

src/NSubstitute/ArgMatchers.cs

@@ -0,0 +1,38 @@
+using NSubstitute.Core.Arguments;
+
+// Disable nullability for client API, so it does not affect clients.
+#nullable disable annotations
+
+namespace NSubstitute;
+
+/// <summary>
+/// Argument matchers for use with <see cref="Arg.Is{T}(IArgumentMatcher{T})"/>.
+/// </summary>
+public static class ArgMatchers
+{
+    public static IArgumentMatcher<T> EqualTo<T>(T value) => new TypedEqualsArgumentMatcher<T>(value);
+
+    public static IArgumentMatcher Any<T>() => new AnyArgumentMatcher(typeof(T));
+
+
+#if NET6_0_OR_GREATER
+    /// <summary>
+    /// Match argument that satisfies <paramref name="predicate"/>.
+    /// If the <paramref name="predicate"/> throws an exception for an argument it will be treated as non-matching.
+    /// </summary>
+    public static IArgumentMatcher<T> Matching<T>(
+        Predicate<T> predicate,
+        [System.Runtime.CompilerServices.CallerArgumentExpression("predicate")]
+        string predicateDescription = ""
+    ) =>
+        new PredicateArgumentMatcher<T>(predicate, predicateDescription);
+
+    // See https://github.com/nsubstitute/NSubstitute/issues/822
+    private class PredicateArgumentMatcher<T>(Predicate<T> predicate, string predicateDescription) : IArgumentMatcher<T>
+    {
+        public bool IsSatisfiedBy(T argument) => predicate(argument!);
+
+        public override string ToString() => predicateDescription;
+    }
+#endif
+}

src/NSubstitute/Compatibility/Arg.Compat.cs

@@ -1,4 +1,5 @@
 using System.Linq.Expressions;
+using NSubstitute.Core.Arguments;
 
 // Disable nullability for client API, so it does not affect clients.
 #nullable disable annotations
@@ -48,6 +49,16 @@ public static class Compat
         /// </summary>
         public static AnyType Is<T>(Expression<Predicate<object>> predicate) where T : AnyType => Arg.Is<T>(predicate);
 
+        /// <summary>
+        /// Match argument that satisfies <paramref name="matcher"/>.
+        /// </summary>
+        public static T Is<T>(IArgumentMatcher matcher) => ArgumentMatcher.Enqueue<T>(matcher);
+
+        /// <summary>
+        /// Match argument that satisfies <paramref name="matcher"/>.
+        /// </summary>
+        public static T Is<T>(IArgumentMatcher<T> matcher) => ArgumentMatcher.Enqueue(matcher);
+
         /// <summary>
         /// Invoke any <see cref="Action"/> argument whenever a matching call is made to the substitute.
         /// This is provided for compatibility with older compilers --
@@ -95,7 +106,7 @@ public static class Compat
         /// Capture any argument compatible with type <typeparamref name="T"/> and use it to call the <paramref name="useArgument"/> function
         /// whenever a matching call is made to the substitute.
         /// This is provided for compatibility with older compilers --
-        /// if possible use <see cref="Arg.Do{T}" /> instead.
+        /// if possible use <see cref="Arg.Do{T}(System.Action{T})" /> instead.
         /// </summary>
         public static T Do<T>(Action<T> useArgument) => Arg.Do<T>(useArgument);
 

src/NSubstitute/Compatibility/CompatArg.cs

@@ -1,4 +1,5 @@
 using System.Linq.Expressions;
+using NSubstitute.Core.Arguments;
 
 // Disable nullability for client API, so it does not affect clients.
 #nullable disable annotations
@@ -57,6 +58,16 @@ private CompatArg() { }
     /// </summary>
     public Arg.AnyType Is<T>(Expression<Predicate<object>> predicate) where T : Arg.AnyType => Arg.Is<T>(predicate);
 
+    /// <summary>
+    /// Match argument that satisfies <paramref name="matcher"/>.
+    /// </summary>
+    public static T Is<T>(IArgumentMatcher matcher) => ArgumentMatcher.Enqueue<T>(matcher);
+
+    /// <summary>
+    /// Match argument that satisfies <paramref name="matcher"/>.
+    /// </summary>
+    public static T Is<T>(IArgumentMatcher<T> matcher) => ArgumentMatcher.Enqueue(matcher);
+
     /// <summary>
     /// Invoke any <see cref="Action"/> argument whenever a matching call is made to the substitute.
     /// This is provided for compatibility with older compilers --

src/NSubstitute/Core/Arguments/AnyArgumentMatcher.cs

@@ -1,8 +1,14 @@
 namespace NSubstitute.Core.Arguments;
 
-public class AnyArgumentMatcher(Type typeArgMustBeCompatibleWith) : IArgumentMatcher
+public class AnyArgumentMatcher(Type typeArgMustBeCompatibleWith)
+    : IArgumentMatcher, IDescribeSpecification, IDescribeNonMatches
 {
     public override string ToString() => "any " + typeArgMustBeCompatibleWith.GetNonMangledTypeName();
 
     public bool IsSatisfiedBy(object? argument) => argument.IsCompatibleWith(typeArgMustBeCompatibleWith);
-}
+
+    public string DescribeFor(object? argument) =>
+        argument?.GetType().GetNonMangledTypeName() ?? "<null>" + " is not a " + typeArgMustBeCompatibleWith.GetNonMangledTypeName();
+
+    public string DescribeSpecification() => ToString();
+}

src/NSubstitute/Core/Arguments/ArgumentMatcher.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using NSubstitute.Exceptions;
 
 namespace NSubstitute.Core.Arguments;
@@ -53,6 +54,11 @@ public GenericToNonGenericMatcherProxyWithDescribe(IArgumentMatcher<T> matcher)
         }
 
         public string DescribeFor(object? argument) => ((IDescribeNonMatches)_matcher).DescribeFor(argument);
+
+        public override string ToString() =>
+            _matcher is IDescribeSpecification describe
+                ? describe.DescribeSpecification() ?? string.Empty
+                : _matcher.ToString() ?? string.Empty;
     }
 
     private class DefaultValueContainer<T>

src/NSubstitute/Core/Arguments/EqualsArgumentMatcher.cs

@@ -5,4 +5,11 @@ public class EqualsArgumentMatcher(object? value) : IArgumentMatcher
     public override string ToString() => ArgumentFormatter.Default.Format(value, false);
 
     public bool IsSatisfiedBy(object? argument) => EqualityComparer<object>.Default.Equals(value, argument);
+}
+
+public class TypedEqualsArgumentMatcher<T>(T? value) : IArgumentMatcher<T>
+{
+    public override string ToString() => ArgumentFormatter.Default.Format(value, false);
+
+    public bool IsSatisfiedBy(T? argument) => EqualityComparer<T>.Default.Equals(argument, value);
 }

tests/NSubstitute.Acceptance.Specs/ArgumentMatching.cs

@@ -4,6 +4,8 @@
 using NSubstitute.Exceptions;
 using NSubstitute.Extensions;
 using NUnit.Framework;
+using static NSubstitute.Acceptance.Specs.Extensions;
+using static NSubstitute.ArgMatchers;
 
 namespace NSubstitute.Acceptance.Specs;
 
@@ -12,6 +14,12 @@ public class ArgumentMatching
 {
     private ISomething _something;
 
+    [SetUp]
+    public void SetUp()
+    {
+        _something = Substitute.For<ISomething>();
+    }
+
     [Test]
     public void Return_result_for_any_argument()
     {
@@ -887,12 +895,6 @@ public interface IWithStructWithDefaultConstructor
         void MethodWithStruct(StructWithDefaultConstructor arg);
     }
 
-    [SetUp]
-    public void SetUp()
-    {
-        _something = Substitute.For<ISomething>();
-    }
-
     public interface IMyService
     {
         void MyMethod<T>(IMyArgument<T> argument);
@@ -940,6 +942,21 @@ public void Should_use_empty_string_for_null_describe_spec_for_custom_arg_matche
         Assert.That(ex.Message, Contains.Substring("Add(23, )"));
     }
 
+    [Test]
+    public void Custom_arg_matcher_support()
+    {
+        _something.Add(1, 2);
+
+        _something.Received().Add(1, Arg.Is(GreaterThan(0)));
+
+        var exception = Assert.Throws<ReceivedCallsException>(() =>
+            _something.Received().Add(1, Arg.Is(GreaterThan(3))));
+
+        Assert.That(exception.Message, Contains.Substring("Add(1, >3)"));
+        Assert.That(exception.Message, Contains.Substring("Add(1, *2*)"));
+        Assert.That(exception.Message, Contains.Substring("arg[1]: 2 \u226f 3"));
+    }
+
     class CustomMatcher : IArgumentMatcher, IDescribeNonMatches, IArgumentMatcher<int>
     {
         public string DescribeFor(object argument) => "failed";
@@ -977,4 +994,39 @@ public override int MethodWithOutParameter(int arg1, out int arg2)
             return 2;
         }
     }
+
+#if NET6_0_OR_GREATER
+    /// <summary>
+    /// See https://github.com/nsubstitute/NSubstitute/issues/822.
+    /// </summary>
+    [Test]
+    public void Predicate_match()
+    {
+        _something.Say("hello");
+
+        _something.Received().Say(Arg.Is(Matching<string>(x => x?.Length > 0)));
+
+        var exception = Assert.Throws<ReceivedCallsException>(() =>
+            _something.Received().Say(Arg.Is(Matching<string>(x => x?.Length > 10))));
+        Assert.That(exception.Message, Contains.Substring("Say(x => x?.Length > 10)"));
+        Assert.That(exception.Message, Contains.Substring("Say(*\"hello\"*)"));
+    }
+#endif
 }
+
+static class Extensions
+{
+    public static IArgumentMatcher<T> GreaterThan<T>(T value) where T : IComparable<T> =>
+        new GreaterThanMatcher<T>(value);
+
+    private class GreaterThanMatcher<T>(T value) :
+        IDescribeNonMatches, IDescribeSpecification, IArgumentMatcher<T>
+        where T : IComparable<T>
+    {
+        public string DescribeFor(object argument) => $"{argument} ≯ {value}";
+
+        public string DescribeSpecification() => $">{value}";
+
+        public bool IsSatisfiedBy(T argument) => argument.CompareTo(value) > 0;
+    }
+}