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;
+ }
+}