Advice about the best NFluent equivalent of FluentAssertions BeEquivalentTo assertion

[maximedezette]

Hi NFluent Team,

I've developed a simple tool to help automate the migration from FluentAssertions to NFluent assertions.

While the tool doesn’t yet support every assertion, it significantly eases the migration process by handling most common assertion replacements. It offers a more efficient approach compared to manual search-and-replace techniques.
My goal is to enable migrations of large projects to be completed in just a few hours, leaving only minor adjustments for more complex assertions.

That said, I'm new to NFluent and would greatly appreciate your advice on some of the transformations the tool performs. In particular, I’m uncertain about the replacement for .Should().BeEquivalentTo(object).

Currently, the tool replaces it with:

Check.That(var).HasFieldsWithSameValues(object);

While this works in most cases, it doesn’t fully match the behavior of BeEquivalentTo, which checks the entire object graph and can also be applied to collections. Initially, I considered .IsEquivalentTo(object) as a replacement but encountered more build errors with that approach.

Do you have any suggestions for a better equivalent in NFluent for this specific assertion? I'd be grateful for your insights on improving the tool! 🙏

[dupdob]

well
FluentAssertion IsEquivalenTto is a powerful beast, especially in terms of fine configuration control.

In general, you should be wary of HasFieldsWithSameValues(...) which is actually a prototype feature that accidentally leaked into a release.

NFluent IsEquivalentTo is supposed to be very similar, except for the fine grained control. I am interested by the kind of compilation error you encounter.

If you need into how to perform fine grained control properties/field based comparison, you can look into Considering.

I tend to think this kind of feature diverges a bit too much from TDD perspective, that's why existing NFluent checks are more limited than Fluentassertions'.

That being said, I am ok to consider extending existing NFluent checks to ease the porting from FluentAssertions.

[maximedezette]

I wasn't aware that HasFieldsWithSameValues was a prototype feature so I'll make the change, thank you for pointing that out 👍

Here are some example that don't seem to work well when I make the tool replace FluentAssertions BeEquivalentTo with IsEquivalentTo :

With this VO:

public record Amount
{
    public Amount(int Value)
    {
        if (Value < 0)
            throw new ArgumentOutOfRangeException("An amount must have a positive value");
        this.Value = Value;
    }

    public int Value { get;  }
    
    public static Amount operator +(Amount a, Amount b) => new(a.Value + b.Value);
    public static Amount operator -(Amount a, Amount b) => new(a.Value - b.Value);
    
    public static implicit operator int(Amount a) => a.Value;
    public static implicit operator Amount(int a) => new(a);
}

And this test:

    [Test]
    public void Should_sum_amounts()
    {
        Amount amount = new (50);
        Amount otherAmount = new (10);
        
        var totalAmount = amount + otherAmount;
        
        Check.That(totalAmount).IsEquivalentTo(new Amount(60));
        Check.That(totalAmount.Value).IsEqualTo(60);
    }

    Check.That(totalAmount).IsEquivalentTo(new Amount(60)); has the error => Cannot convert instance argument type 'NFluent.ICheck<Domain.ValueObject.Amount>' to 'NFluent.ICheck<System.Collections.IEnumerable>'

There is this other scenario too:

  [Then(@"the battle report is")]
    public void  ThenTheBattleReportIs(Table table)
    {
       var battleReport = _scenarioContext.Get<BattleReport>("battleReport");

       if (table.ContainsColumn("Result"))
       {
           var expectedResult = table.Rows[0]["Result"];
           Check.That(battleReport.BattleResult.ToString()).IsEquivalentTo(expectedResult);
       }
    }

Is false with the Following message:

The checked string is not equivalent to the expected enumerable.
The checked string:
	["AttackingRealmWin"]
The expected enumerable:
	{'A','t','t','a','c','k','i','n','g','R','e','a','l','m','W','i','n'} (17 items)
   at NFluent.Kernel.ExceptionReporter.ReportError(String message)
   at NFluent.Kernel.CheckLogic`1.EndCheck()
   at NFluent.Helpers.EqualityHelper.ImplementEquivalentTo[T](ICheckLogic`1 checker, IEnumerable`1 content)
   at NFluent.EnumerableCheckExtensions.IsEquivalentTo[T](ICheck`1 context, T[] expectedValues)
   at NFluent.EnumerableCheckExtensions.IsEquivalentTo[T](ICheck`1 context, IEnumerable`1 content)
   at AcceptanceTests.StepDefinitions.BattleStepDefinitions.ThenTheBattleReportIs(Table table) 

In both case, the expected is considered as an Enumerable which seems normal to me from what I understand of IsEquivalentTo assertion which seems made for comparing Enumerable and Dictionaries instead of objects🤔 I use NFluent 3.1 and my imports are

using Domain.ValueObject;
using NFluent;

In the first case.

using System.Text.Json;
using AcceptanceTests.Utils;
using Domain.Battle;
using NFluent;
using Reqnroll;
using StrategyBrowserGameAPI.Infrastructure.Secondary;

In the second one.

That being said, when I replace ShouldBeEquivalentTo with .Considering().All.Fields.And.Properties.IsEqualTo(..) it works on all my cases.
My test project is too small to draw conclusion but I think that it make sense that in most cases, when BeEquivalentTo is being used, what is truly wanted is to make a field by field comparison. What do you think ?

[dupdob]

Thanks, there is a lot there:

I wasn't aware that HasFieldsWithSameValues was a prototype feature so I'll make the change, thank you for pointing that out 👍

Don't worry, you are not the first, you won't be the last. This check had such a success that I kept as is and never documented this, but it still view it as half baked 😄 .

Amount test case

It may be a problem with records. I never did any explicit test with them, and no one reported any issues, but it looks like it is.
Will look into this.

String & enumeration

What behavior are you expecting here? should the string be considered as an IEnumerable<char> as well? I think I could do that.

[maximedezette]

It may be a problem with records. I never did any explicit test with them, and no one reported any issues, but it looks like it is.
Will look into this.

I've made some tests with regular classes to make sure of that but I've encountered the same error, here is an example:

[Fact]
   public void Should_compare_two_classes_with_isEquivalentTo()
   {
       var actual = new MyCustomObject("property1", "property2", new NestedObject("nestedProperty1", "nestedProperty2"));
       var expected = new MyCustomObject("property1", "property2", new NestedObject("nestedProperty1", "nestedProperty2"));

       Check.That(actual).IsEquivalentTo(expected);
   }


internal class MyCustomObject(string Property1, string Property2, NestedObject NestedObject)
{
   public string Property1 { get; init; } = Property1;
   public string Property2 { get; init; } = Property2;
   public NestedObject NestedObject { get; init; } = NestedObject;
}

internal class NestedObject(string Property1, string Property2)
{
   public string Property1 { get; init; } = Property1;
   public string Property2 { get; init; } = Property2;
} 

Cannot convert instance argument type 'NFluent.ICheck<UnitTests.CsFileContentReplacer.ContainTest.MyCustomObject>' to 'NFluent.ICheck<System.Collections.IEnumerable>'

When I go to the IsEquivalentTo implementation, I see:

public static ICheckLink<ICheck<IEnumerable>> IsEquivalentTo(this ICheck<IEnumerable> context,
    params object[] expectedValues)
{
    var checker = ExtensibilityHelper.BeginCheck(context);
    var dictionary = ExtractDictionaryFromValueArray(expectedValues);
    if (dictionary != null)
    {
        EqualityHelper.ImplementEquivalentTo(checker, dictionary);
    }
    else
    {
        EqualityHelper.ImplementEquivalentTo(checker, ExtractEnumerableValueFromPossibleOneValueArray(expectedValues));
    }
    return ExtensibilityHelper.BuildCheckLink(context);
}

I might have a configuration issue and use the wrong IsEquivalentTo assertion but When I see the
code, I think it makes sense that it doesn't work with other things than IEnumerable.

What behavior are you expecting here? should the string be considered as an IEnumerable as well?

When I use IsEquivalentTo assertion, I expect it to behave like "is equal to <other> using recursive field by field comparaison", in nearly the same way as the fluent assertion BeEquivalentTo.

Here are some explanation from the BeEquivalentTo documentation:

You may want to make sure that all exposed members of all the objects in the OrderDto object graph match the equally named members of the Order object graph.

...
The default behavior is to treat every type that overrides Object.Equals as an object that was designed to have value semantics. Anonymous types, records, record structs and tuples also override this method, but because the community proved us that they use them quite often in equivalency comparisons, we decided to always compare them by their members.
...
The comparison is recursive by default. To avoid infinite recursion, Fluent Assertions will recurse up to 10 levels deep by default,
..

[dupdob]

What I need to see here, is why the compilation ends up using this signature:
public static ICheckLink<ICheck<IEnumerable>> IsEquivalentTo(this ICheck<IEnumerable> context, params object[] expectedValues)
when used on some class. It does not make sense, unless 'everything is enumerable' now....

[dupdob]

OK, I had a look and now I understand.
I remembered wrong: IsEquivalentTo is for Enumerable only. Sorry about that; I thought that you were talking about runtime exception but those were compilation errors.
It has been a while since I last had a look, but the most powerful comparison is for Anonymous type, where there is a recursive comparison.
I must review the design and see how to surface it into an easy API

[shareitcode]

I tried this code :

  [Fact]
  public void Should_compare_two_classes_with_isEquivalentTo()
  {
      var actual = new List<MyCustomObject> {new MyCustomObject("property1", "property2", new NestedObject("nestedProperty1", "nestedProperty2"))};
      var expected = new List<MyCustomObject> {new MyCustomObject("property1", "property2", new NestedObject("nestedProperty1", "nestedProperty2"))};

      Check.That(actual).IsEquivalentTo(expected);
  }

And I have this exception:

NFluent.Kernel.FluentCheckException

The checked enumerable is not equivalent to the expected one.
MyTest+MyCustomObject should not exist (found in actual[0]); MyTest+MyCustomObject should be found instead.
The checked enumerable:
	{MyTest+MyCustomObject} (1 item)
The expected enumerable:
	{MyTest+MyCustomObject} (1 item)
   at NFluent.Kernel.ExceptionReporter.ReportError(String message)
   at NFluent.Kernel.CheckLogic`1.EndCheck()
   at NFluent.Helpers.EqualityHelper.ImplementEquivalentTo[T](ICheckLogic`1 checker, IEnumerable`1 content)
   at NFluent.EnumerableCheckExtensions.IsEquivalentTo[T](ICheck`1 context, T[] expectedValues)
   at NFluent.EnumerableCheckExtensions.IsEquivalentTo[T](ICheck`1 context, IEnumerable`1 content)
   at MyTest.Should_compare_two_classes_with_isEquivalentTo() in C:\Developments\MyTests\MyTest.cs:line 41

I think IsEquivalentTo is not for object but only for Enumerable according to the wiki.

[dupdob]

After digging up, there is no clear equivalent that is exposed. As said earlier, the design is almost ready. The only missing part is recursion for the general case (recursion is currently supported, but only for enumeration).
I am looking into how to add it.

[maximedezette]

I remembered wrong: IsEquivalentTo is for Enumerable only. Sorry about that; I thought that you were talking about runtime exception but those were compilation errors.

It's nothing, I'm just glad we've found an explanation 👍

After digging up, there is no clear equivalent that is exposed. As said earlier, the design is almost ready. The only missing part is recursion for the general case (recursion is currently supported, but only for enumeration).
I am looking into how to add it.

Thanks a lot, that would be great !

In the meantime, we will continue to improve the tool without talking too much about it.
Because BeEquivalentTo is wildely use, I prefer to wait until we have the best possible replacement so that the people who have migrated get the best possible grip on NFluent 🙂

If I can ever be of any help, please don't hesitate to contact me.

[dupdob]

@maximedezette : I sent you an invite to the NFluent. This way I will be able to keep you updated on the progress without bloating this entry. And we can discuss further on the best way to address this