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.

Closes #796.

src/NSubstitute/Core/Arguments/ArgumentMatcher.cs

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

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,9 @@ public IEnumerable<ArgumentMatchInfo> NonMatchingArguments(ICall call)
 
  public override string ToString()
  {
- var argSpecsAsStrings = _argumentSpecifications.Select(x => x.ToString() ?? string.Empty).ToArray();
+ var argSpecsAsStrings = _argumentSpecifications.Select(x =>
+ (x as IDescribeSpecification)?.DescribeSpecification() ?? x.ToString() ?? string.Empty
+ ).ToArray();
  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,15 @@
+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.
+ /// </summary>
+ /// <returns></returns>
+ string DescribeSpecification();
+}

tests/NSubstitute.Acceptance.Specs/ArgumentMatching.cs

@@ -745,4 +745,37 @@ 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()));
+ });
+ Assert.That(ex.Message, Contains.Substring("Add(23, DescribeSpec)"));
+ }
+
+ 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 : CustomMatcher, IDescribeSpecification
+ {
+ public string DescribeSpecification() => "DescribeSpec";
+ }
+}