Add missing reason in some equivalency assertions

Src/AwesomeAssertions/Equivalency/MultiDimensionalArrayEquivalencyStep.cs

@@ -65,10 +65,10 @@ private static bool IsArray(object type, AssertionChain assertionChain)
     {
         assertionChain
             .ForCondition(type is not null)
-            .FailWith("Cannot compare a multi-dimensional array to <null>.")
+            .FailWith("Cannot compare a multi-dimensional array to <null>{reason}.")
             .Then
             .ForCondition(type is Array)
-            .FailWith("Cannot compare a multi-dimensional array to something else.");
+            .FailWith("Cannot compare a multi-dimensional array to something else{reason}.");
 
         return assertionChain.Succeeded;
     }
@@ -84,7 +84,7 @@ private static bool HaveSameDimensions(object subject, Array expectation, Assert
 
             assertionChain
                 .ForCondition(expectedLength == actualLength)
-                .FailWith("Expected dimension {0} to contain {1} item(s), but found {2}.", dimension, expectedLength,
+                .FailWith("Expected dimension {0} to contain {1} item(s){reason}, but found {2}.", dimension, expectedLength,
                     actualLength);
 
             sameDimensions &= assertionChain.Succeeded;
@@ -99,7 +99,7 @@ private static bool HaveSameRank(object subject, Array expectation, AssertionCha
 
         assertionChain
             .ForCondition(subjectAsArray.Rank == expectation.Rank)
-            .FailWith("Expected {context:array} to have {0} dimension(s), but it has {1}.", expectation.Rank,
+            .FailWith("Expected {context:array} to have {0} dimension(s){reason}, but it has {1}.", expectation.Rank,
                 subjectAsArray.Rank);
 
         return assertionChain.Succeeded;

Src/AwesomeAssertions/Equivalency/Steps/DictionaryEquivalencyStep.cs

@@ -64,7 +64,7 @@ private static bool AssertIsDictionary(IDictionary subject, AssertionChain asser
     {
         assertionChain
             .ForCondition(subject is not null)
-            .FailWith("Expected {context:subject} to be a dictionary, but it is not.");
+            .FailWith("Expected {context:subject} to be a dictionary{reason}, but it is not.");
 
         return assertionChain.Succeeded;
     }

Src/AwesomeAssertions/Equivalency/Steps/EnumerableEquivalencyValidator.cs

@@ -61,7 +61,7 @@ private bool AssertIsNotNull(object expectation, object[] subject)
     {
         assertionChain
             .ForCondition(expectation is not null)
-            .FailWith("Expected {context:subject} to be <null>, but found {0}.", [subject]);
+            .FailWith("Expected {context:subject} to be <null>{reason}, but found {0}.", [subject]);
 
         return assertionChain.Succeeded;
     }

Src/AwesomeAssertions/Equivalency/Steps/EqualityComparerEquivalencyStep.cs

@@ -34,11 +34,11 @@ public EquivalencyResult Handle(Comparands comparands, IEquivalencyValidationCon
             .For(context)
             .BecauseOf(context.Reason.FormattedMessage, context.Reason.Arguments)
             .ForCondition(comparands.Subject is T)
-            .FailWith("Expected {context:object} to be of type {0}{because}, but found {1}", typeof(T), comparands.Subject)
+            .FailWith("Expected {context:object} to be of type {0}{reason}, but found {1}", typeof(T), comparands.Subject)
             .Then
             .Given(() => comparer.Equals((T)comparands.Subject, (T)comparands.Expectation))
             .ForCondition(isEqual => isEqual)
-            .FailWith("Expected {context:object} to be equal to {1} according to {0}{because}, but {2} was not.",
+            .FailWith("Expected {context:object} to be equal to {1} according to {0}{reason}, but {2} was not.",
                 comparer.ToString(), comparands.Expectation, comparands.Subject);
 
         return EquivalencyResult.EquivalencyProven;

Src/AwesomeAssertions/Equivalency/Steps/GenericDictionaryEquivalencyStep.cs

@@ -86,7 +86,7 @@ private static DictionaryInterfaceInfo EnsureSubjectIsOfTheExpectedDictionaryTyp
         {
             assertionChain.FailWith(
                 "Expected {context:subject} to be a dictionary or collection of key-value pairs that is keyed to " +
-                "type {0}.", expectedDictionary.Key);
+                "type {0}{reason}.", expectedDictionary.Key);
         }
 
         return actualDictionary;

Src/AwesomeAssertions/Equivalency/Steps/GenericEnumerableEquivalencyStep.cs

@@ -68,7 +68,7 @@ private static bool AssertSubjectIsCollection(AssertionChain assertionChain, obj
     {
         assertionChain
             .ForCondition(subject is not null)
-            .FailWith("Expected {context:subject} not to be {0}.", new object[] { null });
+            .FailWith("Expected {context:subject} not to be {0}{reason}.", new object[] { null });
 
         if (assertionChain.Succeeded)
         {

Tests/AwesomeAssertions.Equivalency.Specs/AssertionRuleSpecs.cs

@@ -147,12 +147,12 @@ public void When_a_nested_property_is_unequal_based_on_equality_comparer_it_shou
 
         // Act
         Action act = () => subject.Should().BeEquivalentTo(expectation,
-            opt => opt.Using(new DateTimeByYearComparer()));
+            opt => opt.Using(new DateTimeByYearComparer()), "we want to test the {0} message", "failure");
 
         // Assert
         act.Should()
             .Throw<XunitException>()
-            .WithMessage("Expected*equal*2021*DateTimeByYearComparer*2020*");
+            .WithMessage("Expected*equal*2021*DateTimeByYearComparer*failure message*2020*");
     }
 
     [Fact]
@@ -165,12 +165,12 @@ public void When_the_subjects_property_type_is_different_from_the_equality_compa
 
         // Act
         Action act = () => subject.Should().BeEquivalentTo(expectation,
-            opt => opt.Using(new DateTimeByYearComparer()));
+            opt => opt.Using(new DateTimeByYearComparer()), "we want to test the {0} message", "failure");
 
         // Assert
         act.Should()
             .Throw<XunitException>()
-            .WithMessage("Expected*Timestamp*1L*");
+            .WithMessage("Expected*Timestamp*to be of type *DateTime*failure message*1L*");
     }
 
     private class DateTimeByYearComparer : IEqualityComparer<DateTime>

Tests/AwesomeAssertions.Equivalency.Specs/CollectionSpecs.cs

@@ -1933,11 +1933,11 @@ public void When_a_multi_dimensional_array_is_compared_to_null_it_should_throw()
         };
 
         // Act
-        Action act = () => actual.Should().BeEquivalentTo(expectation);
+        Action act = () => actual.Should().BeEquivalentTo(expectation, "we want to test the {0} message", "failure");
 
         // Assert
         act.Should().Throw<XunitException>()
-            .WithMessage("Cannot compare a multi-dimensional array to <null>*");
+            .WithMessage("Cannot compare a multi-dimensional array to <null>*failure message*");
     }
 
     [Fact]
@@ -1953,11 +1953,30 @@ public void When_a_multi_dimensional_array_is_compared_to_a_non_array_it_should_
         };
 
         // Act
-        Action act = () => actual.Should().BeEquivalentTo(expectation);
+        Action act = () => actual.Should().BeEquivalentTo(expectation, "we want to test the {0} message", "failure");
+
+        // Assert
+        act.Should().Throw<XunitException>()
+            .WithMessage("Cannot compare a multi-dimensional array to something else*failure message*");
+    }
+
+    [Fact]
+    public void When_a_multi_dimensional_array_is_compared_to_another_array_of_different_rank_it_should_throw()
+    {
+        // Arrange
+        int[,] expected =
+        {
+            { 1, 2 },
+            { 3, 4 },
+        };
+        Array actual = new[] { 1, 2 };
+
+        // Act
+        Action act = () => actual.Should().BeEquivalentTo(expected, "we want to test the {0} message", "failure");
 
         // Assert
         act.Should().Throw<XunitException>()
-            .WithMessage("Cannot compare a multi-dimensional array to something else*");
+            .WithMessage("*to have 2 dimension(s)*failure message*but it has 1*");
     }
 
     [Fact]
@@ -1973,11 +1992,11 @@ public void When_the_length_of_the_2nd_dimension_differs_between_the_arrays_it_s
         int[,] expectation = { { 1, 2, 3 } };
 
         // Act
-        Action act = () => actual.Should().BeEquivalentTo(expectation);
+        Action act = () => actual.Should().BeEquivalentTo(expectation, "we want to test the {0} message", "failure");
 
         // Assert
         act.Should().Throw<XunitException>()
-            .WithMessage("Expected dimension 0 to contain 1 item(s), but found 2*");
+            .WithMessage("Expected dimension 0 to contain 1 item(s)*failure message*, but found 2*");
     }
 
     [Fact]

Tests/AwesomeAssertions.Equivalency.Specs/DictionarySpecs.cs

@@ -366,6 +366,21 @@ public void When_a_dictionary_is_compared_to_null_it_should_not_throw_a_NullRefe
             .WithMessage("Expected*not to be*null*valid dictionary*");
     }
 
+    [Fact]
+    public void When_a_non_dictionary_is_compared_to_a_generic_dictionary_it_should_fail()
+    {
+        // Arrange
+        object subject = new();
+        Dictionary<int, int> expectation = [];
+
+        // Act
+        Action act = () => subject.Should().BeEquivalentTo(expectation, "we want to test the {0} message", "failure");
+
+        // Assert
+        act.Should().Throw<XunitException>()
+            .WithMessage("Expected*to be a dictionary or collection of key-value pairs*failure message*");
+    }
+
     [Fact]
     public void When_a_null_dictionary_is_compared_to_null_it_should_not_throw()
     {
@@ -656,12 +671,13 @@ public void When_the_subjects_key_type_is_not_compatible_with_the_expected_key_t
         var expectation = new Dictionary<string, string> { ["greeting"] = "hello" };
 
         // Act
-        Action act = () => actual.Should().BeEquivalentTo(expectation);
+        Action act = () => actual.Should().BeEquivalentTo(expectation, "we want to test the {0} message", "failure");
 
         // Assert
         act.Should().Throw<XunitException>()
             .WithMessage(
-                "Expected actual to be a dictionary or collection of key-value pairs that is keyed to type string*");
+                "Expected actual to be a dictionary or collection of key-value pairs" +
+                " that is keyed to type string*failure message*");
     }
 
     [Fact]

Tests/AwesomeAssertions.Specs/Collections/CollectionAssertionSpecs.BeEquivalentTo.cs

@@ -110,28 +110,26 @@ public void When_testing_for_equivalence_against_null_collection_it_should_throw
             int[] collection2 = null;
 
             // Act
-            Action act = () => collection1.Should().BeEquivalentTo(collection2);
+            Action act = () => collection1.Should().BeEquivalentTo(collection2, "we want to test the {0} message", "failure");
 
             // Assert
             act.Should().Throw<XunitException>().WithMessage(
-                "Expected*<null>*but found {1, 2, 3}*");
+                "Expected*<null>*failure message*but found {1, 2, 3}*");
         }
 
         [Fact]
         public void When_asserting_collections_to_be_equivalent_but_subject_collection_is_null_it_should_throw()
         {
-            // Arrange
             int[] collection = null;
             int[] collection1 = [1, 2, 3];
 
             // Act
             Action act =
                 () => collection.Should()
-                    .BeEquivalentTo(collection1, "because we want to test the behaviour with a null subject");
+                    .BeEquivalentTo(collection1, "we want to test the {0} message", "failure");
 
             // Assert
-            act.Should().Throw<XunitException>().WithMessage(
-                "Expected collection not to be <null>*");
+            act.Should().Throw<XunitException>().WithMessage("Expected collection not to be <null> because*failure message*");
         }
 
         [Fact]

docs/_pages/releases.md

@@ -9,6 +9,7 @@ sidebar:
 ## Unreleased
 
 ### Fixes
+* Add missing reason to some equivalency assertions - [#405](https://github.com/AwesomeAssertions/AwesomeAssertions/pull/405)
 * Add missing `StringSyntaxAttribute` to the because parameter of several assertions - [#404](https://github.com/AwesomeAssertions/AwesomeAssertions/pull/404)
 * Fix assembly loading for NUnit4 and `LifeCycle.InstancePerTestCase` with Microsoft.Testing.Platform - [#362](https://github.com/AwesomeAssertions/AwesomeAssertions/pull/362)
 * Fix configuring displayed length of string assertions at `AssertionScope` - [#393](https://github.com/AwesomeAssertions/AwesomeAssertions/pull/393)