Ploch.Data.EFCore.IntegrationTesting.FluentAssertions 4.0.1

Ploch.Data.EFCore.IntegrationTesting.FluentAssertions

FluentAssertions helpers for integration tests that store and retrieve EF Core entities from a database.

Overview

When comparing entities retrieved from a database against in-memory objects using FluentAssertions, three recurring problems arise:

This library provides a single extension method — WithEntityEquivalencyOptions() — that resolves all three issues consistently.

Installation

Reference the package in your test project:

<PackageReference Include="Ploch.Data.EFCore.IntegrationTesting.FluentAssertions" />

Or, when working locally in the ploch-data workspace, use a project reference:

<ProjectReference Include="..\..\..\src\Data.EFCore.IntegrationTesting.FluentAssertions\Ploch.Data.EFCore.IntegrationTesting.FluentAssertions.csproj" />

API Reference

WithEntityEquivalencyOptions()

public static TSelf WithEntityEquivalencyOptions<TSelf>(
    this SelfReferenceEquivalencyOptions<TSelf> options)
    where TSelf : SelfReferenceEquivalencyOptions<TSelf>

Applies the following configuration to a FluentAssertions equivalency assertion:

• WithoutStrictOrdering() — compares collections by value, ignoring insertion order.
• IgnoringCyclicReferences() — stops traversal when a cycle is detected (e.g. BlogPost → Tags → BlogPosts → BlogPost).
• BeCloseTo with 1 ms tolerance for DateTimeOffset — accommodates the ~100 µs precision loss that occurs when SQLite stores and retrieves DateTimeOffset values.

Usage

using Ploch.Data.EFCore.IntegrationTesting.FluentAssertions;

// Basic — compare an entity retrieved from the DB with the in-memory original.
actual.Should().BeEquivalentTo(expected, options => options.WithEntityEquivalencyOptions());

// With additional exclusions for back-navigation properties.
// EF Core populates Tag.BlogPosts on a loaded BlogPost, but the in-memory BlogPost
// created in test setup does not have that back-reference populated.
actual.Should().BeEquivalentTo(expected,
    options => options.Excluding(p => p.Tags)
                      .Excluding(p => p.Categories)
                      .WithEntityEquivalencyOptions());

// In a collection assertion.
blogPosts.Should().ContainEquivalentOf(expected,
    options => options.Excluding(p => p.Categories).WithEntityEquivalencyOptions());

Handling Back-Navigation Properties

EF Core automatically populates inverse navigation properties when loading an entity with eager loading. For example, loading a BlogPost with .Include(p => p.Tags) also causes each Tag.BlogPosts to be set. The in-memory objects created during test setup do not have this back-reference, causing BeEquivalentTo to fail.

The recommended pattern is to exclude back-navigation properties from the structural comparison and verify them separately by count or content:

// Compare core scalar properties.
actual.Should().BeEquivalentTo(expected,
    options => options.Excluding(p => p.Tags)
                      .Excluding(p => p.Categories)
                      .WithEntityEquivalencyOptions());

// Verify the navigation properties were loaded correctly.
actual.Tags.Should().HaveCount(expected.Tags.Count);
actual.Categories.Should().HaveCount(expected.Categories.Count);

DateTimeOffset Precision in SQLite

SQLite stores DateTimeOffset as TEXT. EF Core's SQLite provider truncates the fractional seconds to approximately 4 decimal places (~100 µs resolution), discarding sub-microsecond ticks. For example:

WithEntityEquivalencyOptions() applies a 1 ms tolerance — 10× the maximum observed rounding error — to every DateTimeOffset comparison, ensuring tests are stable without masking real bugs.

Integration with DataIntegrationTest<TDbContext>

This library is designed to be used alongside Ploch.Data.EFCore.IntegrationTesting, which provides the DataIntegrationTest<TDbContext> base class for EF Core integration tests using an in-memory SQLite database.

public class MyRepositoryTests : GenericRepositoryDataIntegrationTest<MyDbContext>
{
    [Fact]
    public async Task GetByIdAsync_should_return_entity_with_includes()
    {
        using var unitOfWork = CreateUnitOfWork();
        var (blog, blogPost1, _) = await RepositoryHelper.AddTestBlogEntities(
            unitOfWork.Repository<Blog, int>());
        await unitOfWork.CommitAsync();

        var repository = CreateReadRepository<Blog, int>();
        var result = repository.GetById(blog.Id,
            q => q.Include(q => q.BlogPosts).ThenInclude(bp => bp.Tags));

        // Verify against a fresh DbContext — not the same repository used to write.
        var dbContext = CreateRootDbContext();
        var fromDb = await dbContext.Blogs
            .Include(q => q.BlogPosts).ThenInclude(bp => bp.Tags)
            .FirstAsync(b => b.Id == blog.Id);

        fromDb.Should().BeEquivalentTo(result, options => options.WithEntityEquivalencyOptions());
        result!.BlogPosts.Should().HaveCount(blog.BlogPosts.Count);
    }
}