Improve output for expected argument matchers

src/NSubstitute/Core/Arguments/ArgumentMatcher.cs

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

src/NSubstitute/Core/Arguments/ArgumentSpecification.cs

@@ -56,7 +56,10 @@ public string FormatArgument(object? argument)
             : ArgumentFormatter.Default.Format(argument, highlight: !isSatisfiedByArg);
     }
 
-    public override string ToString() => _matcher.ToString() ?? string.Empty;
+    public override string ToString() =>
+        _matcher is IDescribeSpecification describe
+            ? describe.DescribeSpecification()
+            : _matcher.ToString() ?? string.Empty;
 
     public IArgumentSpecification CreateCopyMatchingAnyArgOfType(Type requiredType)
     {

src/NSubstitute/Core/Arguments/IArgumentMatcher.cs

@@ -1,8 +1,10 @@
 namespace NSubstitute.Core.Arguments;
 
 /// <summary>
-/// Provides a specification for arguments for use with <see ctype="Arg.Matches (IArgumentMatcher)" />.
-/// Can additionally implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Provides a specification for arguments.
+/// Can implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Can implement <see cref="IDescribeSpecification"/> to give descriptions of expected arguments (otherwise
+/// `ToString()` will be used for descriptions).
 /// </summary>
 public interface IArgumentMatcher
 {
@@ -14,8 +16,10 @@ public interface IArgumentMatcher
 }
 
 /// <summary>
-/// Provides a specification for arguments for use with <see ctype="Arg.Matches &lt; T &gt;(IArgumentMatcher)" />.
-/// Can additionally implement <see ctype="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Provides a specification for arguments.
+/// Can implement <see cref="IDescribeNonMatches" /> to give descriptions when arguments do not match.
+/// Can implement <see cref="IDescribeSpecification"/> to give descriptions of expected arguments (otherwise
+/// `ToString()` will be used for descriptions).
 /// </summary>
 /// <typeparam name="T">Matches arguments of type <typeparamref name="T"/> or compatible type.</typeparam>
 public interface IArgumentMatcher<T>

src/NSubstitute/Core/CallSpecification.cs

@@ -123,7 +123,11 @@ public IEnumerable<ArgumentMatchInfo> NonMatchingArguments(ICall call)
 
     public override string ToString()
     {
-        var argSpecsAsStrings = _argumentSpecifications.Select(x => x.ToString() ?? string.Empty).ToArray();
+        var argSpecsAsStrings = Array.ConvertAll(_argumentSpecifications, x =>
+            x is IDescribeSpecification describe
+                ? describe.DescribeSpecification() ?? string.Empty
+                : x.ToString() ?? string.Empty
+        );
         return CallFormatter.Default.Format(GetMethodInfo(), argSpecsAsStrings);
     }
 

src/NSubstitute/Core/IDescribeNonMatches.cs

@@ -1,5 +1,10 @@
 namespace NSubstitute.Core;
 
+/// <summary>
+/// A type that can describe how an argument does not match a required condition.
+/// Use in conjunction with <see cref="NSubstitute.Core.Arguments.IArgumentMatcher"/> to provide information about
+/// non-matches.
+/// </summary>
 public interface IDescribeNonMatches
 {
     /// <summary>
@@ -9,4 +14,4 @@ public interface IDescribeNonMatches
     /// <param name="argument"></param>
     /// <returns>Description of the non-match, or <see cref="string.Empty" /> if no description can be provided.</returns>
     string DescribeFor(object? argument);
-}
+}

src/NSubstitute/Core/IDescribeSpecification.cs

@@ -0,0 +1,16 @@
+namespace NSubstitute.Core;
+
+/// <summary>
+/// A type that can describe the required conditions to meet a specification.
+/// Use in conjunction with <see cref="NSubstitute.Core.Arguments.IArgumentMatcher"/> to provide information about
+/// what it requires to match an argument.
+/// </summary>
+public interface IDescribeSpecification
+{
+    /// <summary>
+    /// A concise description of the conditions required to match this specification, or <see cref="string.Empty"/>
+    /// if a detailed description can not be provided.
+    /// </summary>
+    /// <returns>Description of the specification, or <see cref="string.Empty" /> if no description can be provided.</returns>
+    string DescribeSpecification();
+}

tests/NSubstitute.Acceptance.Specs/ArgumentMatching.cs

@@ -745,4 +745,47 @@ public void SetUp()
     {
         _something = Substitute.For<ISomething>();
     }
-}
+
+    [Test]
+    public void Should_use_ToString_to_describe_custom_arg_matcher_without_DescribesSpec()
+    {
+        var ex = Assert.Throws<ReceivedCallsException>(() =>
+        {
+            _something.Received().Add(23, ArgumentMatcher.Enqueue(new CustomMatcher()));
+        });
+        Assert.That(ex.Message, Contains.Substring("Add(23, Custom match)"));
+    }
+
+    [Test]
+    public void Should_describe_spec_for_custom_arg_matcher_when_implemented()
+    {
+        var ex = Assert.Throws<ReceivedCallsException>(() =>
+        {
+            _something.Received().Add(23, ArgumentMatcher.Enqueue(new CustomDescribeSpecMatcher("DescribeSpec")));
+        });
+        Assert.That(ex.Message, Contains.Substring("Add(23, DescribeSpec)"));
+    }
+
+    [Test]
+    public void Should_use_empty_string_for_null_describe_spec_for_custom_arg_matcher_when_implemented()
+    {
+        var ex = Assert.Throws<ReceivedCallsException>(() =>
+        {
+            _something.Received().Add(23, ArgumentMatcher.Enqueue(new CustomDescribeSpecMatcher(null)));
+        });
+        Assert.That(ex.Message, Contains.Substring("Add(23, )"));
+    }
+
+    class CustomMatcher : IArgumentMatcher, IDescribeNonMatches, IArgumentMatcher<int>
+    {
+        public string DescribeFor(object argument) => "failed";
+        public bool IsSatisfiedBy(object argument) => false;
+        public bool IsSatisfiedBy(int argument) => false;
+        public override string ToString() => "Custom match";
+    }
+
+    class CustomDescribeSpecMatcher(string description) : CustomMatcher, IDescribeSpecification
+    {
+        public string DescribeSpecification() => description;
+    }
+}