Add object equivalency with member selection and ordering control

Author: yevhen

src/SharpAssert.Runtime/Features/Collections/CollectionExtensions.cs

@@ -0,0 +1,43 @@
+// ABOUTME: Configuration builder for equivalency assertions.
+// ABOUTME: Provides a fluent API for customizing object comparison behavior.
+
+using System.Linq.Expressions;
+using KellermanSoftware.CompareNetObjects;
+
+namespace SharpAssert;
+
+public sealed class EquivalencyConfig<T>
+{
+    internal ComparisonConfig ComparisonConfig { get; } = new();
+
+    public EquivalencyConfig<T> Excluding(Expression<Func<T, object>> memberSelector)
+    {
+        var memberName = GetMemberName(memberSelector);
+        ComparisonConfig.MembersToIgnore.Add(memberName);
+        return this;
+    }
+
+    public EquivalencyConfig<T> Including(Expression<Func<T, object>> memberSelector)
+    {
+        var memberName = GetMemberName(memberSelector);
+        ComparisonConfig.MembersToInclude.Add(memberName);
+        return this;
+    }
+
+    public EquivalencyConfig<T> WithoutStrictOrdering()
+    {
+        ComparisonConfig.IgnoreCollectionOrder = true;
+        return this;
+    }
+
+    static string GetMemberName(Expression<Func<T, object>> expression)
+    {
+        if (expression.Body is MemberExpression memberExpr)
+            return memberExpr.Member.Name;
+
+        if (expression.Body is UnaryExpression { Operand: MemberExpression unaryMember })
+            return unaryMember.Member.Name;
+
+        throw new ArgumentException($"Expression '{expression}' does not refer to a property or field.");
+    }
+}

src/SharpAssert.Runtime/Features/Collections/CollectionOrderingExpectation.cs

@@ -0,0 +1,21 @@
+// ABOUTME: Extension methods for object equivalency assertions.
+// ABOUTME: Provides IsEquivalentTo() for deep object comparison with configuration.
+
+namespace SharpAssert;
+
+public static class EquivalencyExtensions
+{
+    public static IsEquivalentToExpectation<T> IsEquivalentTo<T>(this T actual, T expected)
+    {
+        return new IsEquivalentToExpectation<T>(actual, expected, new EquivalencyConfig<T>());
+    }
+
+    public static IsEquivalentToExpectation<T> IsEquivalentTo<T>(
+        this T actual,
+        T expected,
+        Func<EquivalencyConfig<T>, EquivalencyConfig<T>> configure)
+    {
+        var config = configure(new EquivalencyConfig<T>());
+        return new IsEquivalentToExpectation<T>(actual, expected, config);
+    }
+}

src/SharpAssert.Runtime/Features/Collections/CollectionUniquenessExpectation.cs

@@ -0,0 +1,54 @@
+// ABOUTME: Expectation for deep object equivalency with configurable comparison rules.
+// ABOUTME: Wraps Compare-Net-Objects to provide rich diagnostics on failure.
+
+using KellermanSoftware.CompareNetObjects;
+using SharpAssert.Features.Shared;
+
+namespace SharpAssert;
+
+public sealed class IsEquivalentToExpectation<T> : Expectation
+{
+    readonly T actual;
+    readonly T expected;
+    readonly EquivalencyConfig<T> config;
+
+    internal IsEquivalentToExpectation(T actual, T expected, EquivalencyConfig<T> config)
+    {
+        this.actual = actual;
+        this.expected = expected;
+        this.config = config;
+    }
+
+    public override EvaluationResult Evaluate(ExpectationContext context)
+    {
+        var compareLogic = new CompareLogic(config.ComparisonConfig);
+        var result = compareLogic.Compare(actual, expected);
+
+        if (result.AreEqual)
+            return ExpectationResults.Pass(context.Expression);
+
+        var differences = FormatDifferences(result.Differences);
+        return ExpectationResults.Fail(context.Expression, differences.ToArray());
+    }
+
+    static List<string> FormatDifferences(IList<Difference> differences)
+    {
+        var lines = new List<string>();
+
+        if (differences.Count > 0)
+        {
+            lines.Add("Object differences:");
+            foreach (var diff in differences.Take(20))
+            {
+                lines.Add($"  {diff.PropertyName}: expected {FormatValue(diff.Object2Value)}, got {FormatValue(diff.Object1Value)}");
+            }
+
+            if (differences.Count > 20)
+                lines.Add($"  ... ({differences.Count - 20} more differences)");
+        }
+
+        return lines;
+    }
+
+    static string FormatValue(object? value) => ValueFormatter.Format(value);
+}