Using Fluent Assertions or Shouldly

5 February 2025

After the news spread that Fluent Assertions had changed their licence in version 8, a lot of things were unclear. Now, a few weeks later, they have clarified things a bit and have also done a quick release of version 8.0.1 to address a concern that a lot of developers had and was causing a lot of frustration.

Fluent Assertions version 8 is still free for non-commercial use. version 7 is unchanged and still free for commercial use under the Apache licence.

The licence change was frustrating because it was just a version update. If you updated all your packages, you could suddenly use the framework without a licence. After all, who expects a licence change when upgrading a free package. An extra licence check warning when using version 8.0.1 resolve this concern a bit.

If this solves all problems and makes the community happy again, only the future will tell. Here are my thoughts on it.

Should you upgrade to 8?

For my blog, which I do in my spare time, it is not commercial, so I could still use Fluent Assertions 8 for free. I prefer to work with frameworks that I use or can use professionally. A licence that costs $130 per year per developer is too expensive in my opinion. It's the best assertion framework for .NET, just not worth the price.

Update 10 February 2025: Small businesses can now purchase a yearly licence for $50 per developer. This is only for companies with less than $1 million in revenue and a maximum of three developers. I'm unsure if this is an improvement for small businesses. If your team or revenue grows, you must update your licence.

I haven't missed any features in version 7. If you use Fluent Assertions commercially, I would recommend staying on version 7 as long as possible. If a newer version has a feature that you really miss then you could decide if its worth its price.

Lock your NuGet version

Something everybody espacially the first week advised. Lock your NuGet version so that you don't accidental upgrade without a valid license. Also on the Update tab in the NuGet Package Manager it helps so that it doesn't show the unwanted Fluent Assertions update anymore.

The only thing you need to do is to edit you .csproj and add [] around the version. In that case you only allow that specific version.

<PackageReference Include="FluentAssertions" Version="[7.1.0]" />

When you have a older .NET project with still a package.config you can edit it in

<package id="FluentAssertions" version="7.1.0" allowedVersions="[7.1.0]" />

This Microsoft page you gives you all the details and options for how to lock down a version or a range of versions.

Shouldly as alternative

shouldlyorfluentassertions Shouldly is an alternative with many similarities to Fluent Assertions. So should you use it? It depends on how many tests you have and which features of Fluent Assertions you use.

The basics are almost the same, for example on a property level a ShouldBe() instead of a Should().Be(), and all the variants like BeNull, BeGreaterThan, BeLessThan etc.

When testing an exception is thrown its a bit different, but Shouldly is still more then capable of doing this. The biggest difference, and whether Shouldly is the best solution for you, is how Should().BeEquivalentTo() works.

Exception assertion

Testing whether an exception is thrown in Shouldly is done with a Should.Throw<ExceptionType>(function), it returns the exception which you can then use to check if the message has the expected value. For example

// Act
var act = async () => await GetTarget().DoSomething(something);

// Assert Fluent Assertions
await act.Should().ThrowExactlyAsync<ArgumentException>().WithMessage($"Doing something: {something} is not supported");

// Assert Shouldly
var exception = await Should.ThrowAsync<NotSupportedException>(act);
exception.Message.ShouldBe($"Doing something: {something} is not supported");

It has a small advantage if you don't like the async lambda functions, or prefer to combine the call and throw assertion. This can be done like this:

// Act & Assert Shouldly
var exception = await Should.ThrowAsync<NotSupportedException>(GetTarget().DoSomething(something));
exception.Message.ShouldBe($"Doing something: {something} is not supported");

BeEquivalentTo

Finally, the real difference in BeEquivalentTo. Shouldly is stricter and also lacks an EquivalencyAssertionOptions, at some point this are features that are really useful. For some of the examples I've made I used the User class and the Service below:

public interface IUserService
{
    void CreateUser(int code, string firstName, string lastName);
    User GetUser(int code);
}

public class User
{
    public required Guid Id { get; set; }
    public required int Code { get; set; }
    public required string FirstName { get; set; }
    public required string LastName { get; set; }
    public required bool DbContraintField { get; set; }
    public required DateTime CreatedDate { get; set; }
}

For the example above, I might want to do the following, which aren't possible with Shouldly:

Excluding properties. The Id is a Guid. When my UserService creates a user with an Id using Guid.NewGuid(), I just want to ignore it. In Fluent Assertions I used to do it like this:
```
result.Should().BeEquivalentTo(expected, options => options.Excluding(u => u.Id));
```
DateTime tolerance. When my UserService creates a user with a CreatedDate with a DateTime.Now() then I can predict the value, just not to the millisecond. In Fluent Assertions it is also not the easiest part, but there I did check it like:
```
result.Should().BeEquivalentTo(expected, options => options.Using<DateTime>(ctx => ctx.Subject.Should().BeCloseTo(ctx.Expectation, TimeSpan.FromSeconds(1))).WhenTypeIs<DateTime>());
```

Stricter. If I am doing an integration test and my UserService creates the record in the database. I may only want to check the Code, FirstName and LastName. Excluding the fields is one option, sometimes I just want to assert against a anonymous object and only compare the properties that are in the expected object. In Fluent Assertions, I could do this like:
```
result.Should().BeEquivalentTo(new { Code = code, FirstName = firstName, LastName = lastName });
```
Without strict ordering. I don't have an example for this with the User class. If I have async calls that add items to a collection, I don't know the order in which I get the collection. In Fluent Assertions I could do check it like:
```
createdUser.Should().BeEquivalentTo(expected, options => options.WithoutStrictOrdering());
```

Create a Extension method for Shouldly

If you use BeEquivalentTo in many places like the above, then it is probably best to stick with version 7 of Fluent Assertions. Shouldly is aware of the situation due to the licence changes of Fluent Assertions, and is considering adding some missing features. It may be easier to make the move to Shouldly in the future.

Another option is to create your own extension methods to fill the gap for the features you are missing. I've created mine to help me with the 2 things I miss the most.

Excluding properties, like:

result.ShouldBeEquivalentTo(expected, options => options.Exclude(u => u.Id));

DateTime tolerance, i now can do like:

result.ShouldBeEquivalentTo(expected, options => options.UsingDateTimeTolerance(TimeSpan.FromSeconds(1)));

In the future I may extend and improve it, if so I will update the code below.

[ShouldlyMethods]
public static class ShouldlyExtensions
{
    public static void ShouldBeEquivalentTo<T>(this T? actual, T? expected, Action<EquivalencyOptions<T>> options) where T : class
    {
        if (typeof(IEnumerable).IsAssignableFrom(typeof(T)) && typeof(T) != typeof(string))
        {
            throw new InvalidOperationException("This overload is not intended for collection types.");
        }

        var equivalencyOptions = ValidateAndSetupOptions(actual, expected, options);

        CompareObjects(actual, expected, equivalencyOptions, new HashSet<(object, object)>());
    }

    public static void ShouldBeEquivalentTo<T>(this IEnumerable<T?> actual, IEnumerable<T?> expected, Action<EquivalencyOptions<T>> options)
    {
        var equivalencyOptions = ValidateAndSetupOptions(actual, expected, options);
        var actualList = actual.ToList();
        var expectedList = expected.ToList();

        actualList.Count.ShouldBe(expectedList.Count, "Collection counts do not match.");

        for (int i = 0; i < actualList.Count; i++)
        {
            CompareObjects(actualList[i], expectedList[i], equivalencyOptions, new HashSet<(object, object)>());
        }
    }

    private static EquivalencyOptions<T> ValidateAndSetupOptions<T>(object? actual, object? expected, Action<EquivalencyOptions<T>> options)
    {
        if (actual == null && expected != null || actual != null && expected == null)
        {
            throw new ShouldAssertException(@$"Comparing object equivalence:
actual: {actual?.GetType().ToString() ?? "null"}
expected: {expected?.GetType().ToString() ?? "null"}");
        }

        var equivalencyOptions = new EquivalencyOptions<T>();
        options(equivalencyOptions);

        return equivalencyOptions;
    }

    private static void CompareObjects<T>(object? actual, object? expected, EquivalencyOptions<T> options, HashSet<(object, object)> visitedObjects, string parentPath = "")
    {
        if (actual == null && expected == null)
        {
            return;
        }

        if (actual == null || expected == null)
        {
            throw new ShouldAssertException(@$"Comparing object equivalence, at path '{parentPath}':
actual: {actual?.GetType().ToString() ?? "null"}
expected: {expected?.GetType().ToString() ?? "null"}");
        };

        if (visitedObjects.Contains((actual, expected)))
        {
            return;
        }
        visitedObjects.Add((actual, expected));

        var properties = actual.GetType().GetProperties();

        foreach (var property in properties)
        {
            var propertyPath = string.IsNullOrEmpty(parentPath) ? property.Name : $"{parentPath}.{property.Name}";

            if (options.ExcludedProperties.Contains(propertyPath) || property.GetIndexParameters().Length > 0)
            {
                continue;
            }

            ComparePropertyValues(property.GetValue(actual), property.GetValue(expected), property, options, visitedObjects, propertyPath);
        }
    }

    private static void ComparePropertyValues<T>(object? actualValue, object? expectedValue, System.Reflection.PropertyInfo property, EquivalencyOptions<T> options, HashSet<(object, object)> visitedObjects, string propertyPath)
    {
        var hasNull = actualValue == null || expectedValue == null;
        if (!hasNull && property.PropertyType == typeof(DateTime) && options.DateTimeTolerance.HasValue)
        {
            ((DateTime)actualValue!).ShouldBe((DateTime)expectedValue!, options.DateTimeTolerance.Value, $"Property {propertyPath} does not match.");
        }
        else if (!hasNull && property.PropertyType == typeof(DateTimeOffset) && options.DateTimeTolerance.HasValue)
        {
            ((DateTimeOffset)actualValue!).ShouldBe((DateTimeOffset)expectedValue!, options.DateTimeTolerance.Value, $"Property {propertyPath} does not match.");
        }
        else if (!hasNull && IsCollectionType(property.PropertyType))
        {
            CompareCollections(actualValue!, expectedValue!, options, visitedObjects, propertyPath);
        }
        else if (!hasNull && IsComplexType(actualValue!))
        {
            CompareObjects(actualValue, expectedValue, options, visitedObjects, propertyPath);
        }
        else
        {
            actualValue.ShouldBe(expectedValue, $"Property {propertyPath} does not match.");
        }
    }

    private static void CompareCollections<T>(object actual, object expected, EquivalencyOptions<T> options, HashSet<(object, object)> visitedObjects, string parentPath = "")
    {
        var actualList = ((IEnumerable<object>)actual).ToList();
        var expectedList = ((IEnumerable<object>)expected).ToList();

        actualList.Count.ShouldBe(expectedList.Count, "Collection counts do not match.");

        for (int i = 0; i < actualList.Count; i++)
        {
            CompareObjects(actualList[i], expectedList[i], options, visitedObjects, parentPath);
        }
    }

    private static bool IsCollectionType(Type type)
    {
        return typeof(IEnumerable).IsAssignableFrom(type) && type != typeof(string);
    }

    private static bool IsComplexType(object obj)
    {
        var type = obj.GetType();
        return !type.IsPrimitive
            && !type.IsEnum
            && type != typeof(string)
            && type != typeof(decimal)
            && type != typeof(DateTime)
            && type != typeof(DateTimeOffset);
    }
}

public class EquivalencyOptions<T>
{
    public HashSet<string> ExcludedProperties { get; } = new HashSet<string>();
    public TimeSpan? DateTimeTolerance { get; private set; }

    public EquivalencyOptions<T> Exclude(Expression<Func<T, object>> propertyExpression)
    {
        ArgumentNullException.ThrowIfNull(propertyExpression);

        ExcludedProperties.Add(GetPropertyPath(propertyExpression));
        return this;
    }

    public EquivalencyOptions<T> UsingDateTimeTolerance(TimeSpan tolerance)
    {
        DateTimeTolerance = tolerance;
        return this;
    }

    private string GetPropertyPath(Expression expression)
    {
        var propertyNames = new List<string>();
        ExtractPropertyPath(expression, propertyNames);
        propertyNames.Reverse();
        return string.Join(".", propertyNames);
    }

    private void ExtractPropertyPath(Expression expression, List<string> propertyNames)
    {
        switch (expression)
        {
            case MemberExpression memberExpression:
                propertyNames.Add(memberExpression.Member.Name);
                ExtractPropertyPath(memberExpression.Expression!, propertyNames);
                break;
            case MethodCallExpression methodCallExpression:
                foreach (var argument in methodCallExpression.Arguments.Reverse())
                {
                    ExtractPropertyPath(argument, propertyNames);
                }
                break;
            case UnaryExpression unaryExpression:
                ExtractPropertyPath(unaryExpression.Operand, propertyNames);
                break;
            case LambdaExpression lambdaExpression:
                ExtractPropertyPath(lambdaExpression.Body, propertyNames);
                break;
            case ParameterExpression:
                break;
            default:
                throw new ArgumentException("Invalid property expression");
        }
    }
}