FluentAssertions — Readable Assertions and Error Messages

// xUnit Assert
Assert.Equal("MRN-001", patient.MRN);
// Failure: Assert.Equal() Failure
// Expected: MRN-001
// Actual:   MRN-002

// FluentAssertions
patient.MRN.Should().Be("MRN-001");
// Failure: Expected patient.MRN to be "MRN-001", but found "MRN-002".

// Equality
result.Value.Should().Be(expectedId);
patient.Name.Should().Be("John Smith");
patient.Name.Should().NotBe("Jane Doe");

// Null
patient.Should().NotBeNull();
prescription.AllergyWarning.Should().BeNull();

// Boolean
result.IsSuccess.Should().BeTrue();
patient.IsActive.Should().BeTrue("because we just created the patient");

// Numeric
dosage.Amount.Should().Be(5m);
dosage.Amount.Should().BeGreaterThan(0m);
dosage.Amount.Should().BeInRange(0.1m, 1000m);

// String
patient.MRN.Should().StartWith("MRN-");
patient.Email.Should().Contain("@");
patient.Name.Should().NotBeNullOrWhiteSpace();
patient.Name.Should().HaveLength(10);
patient.Name.Should().MatchRegex(@"^[A-Za-z\s]+$");

// DateTime
patient.CreatedAt.Should().BeCloseTo(DateTime.UtcNow, TimeSpan.FromSeconds(5));
prescription.ExpiresAt.Should().BeAfter(DateTime.UtcNow);

var prescriptions = patient.Prescriptions;

// Count
prescriptions.Should().HaveCount(3);
prescriptions.Should().HaveCountGreaterThan(0);
prescriptions.Should().NotBeEmpty();
prescriptions.Should().BeEmpty();

// Content
prescriptions.Should().Contain(rx => rx.DrugName == "Warfarin");
prescriptions.Should().NotContain(rx => rx.IsExpired);
prescriptions.Should().AllSatisfy(rx => rx.IsActive.Should().BeTrue());
prescriptions.Should().ContainSingle(rx => rx.DrugName == "Aspirin");

// Equivalence
prescriptions.Should().BeEquivalentTo(expected);  // deep comparison, order-independent
prescriptions.Should().Equal(expected);            // order-sensitive, reference equality

// Specific elements
prescriptions.Should().HaveElementAt(0, firstExpected);
prescriptions.First().DrugName.Should().Be("Warfarin");

// Ordering
prescriptions.Should().BeInAscendingOrder(rx => rx.IssuedAt);
prescriptions.Should().BeInDescendingOrder(rx => rx.Priority);

// BeEquivalentTo compares all public properties by value
var expected = new PatientDto(
    Id:         patientId,
    Name:       "John Smith",
    MRN:        "MRN-001",
    Department: "Cardiology");

actual.Should().BeEquivalentTo(expected);

// Exclude properties from comparison
actual.Should().BeEquivalentTo(expected, options =>
    options.Excluding(p => p.CreatedAt)   // timestamps differ — exclude
           .Excluding(p => p.Id));         // generated ID — exclude

// Compare only specific properties
actual.Should().BeEquivalentTo(expected, options =>
    options.Including(p => p.Name)
           .Including(p => p.MRN));

// Custom comparison for nested objects
actual.Should().BeEquivalentTo(expected, options =>
    options.Using<DateTime>(ctx =>
        ctx.Subject.Should().BeCloseTo(ctx.Expectation, TimeSpan.FromSeconds(1)))
    .WhenTypeIs<DateTime>());

// Assert an exception is thrown
Action act = () => Patient.Create(null!, new DateOnly(1985, 3, 15), "MRN-001");
act.Should().Throw<ArgumentNullException>()
    .WithMessage("*name*");

// Async exceptions
Func<Task> act = async () =>
    await _handler.Handle(invalidCommand, CancellationToken.None);
await act.Should().ThrowAsync<InvalidOperationException>()
    .WithMessage("*MRN*");

// Assert NO exception (explicit)
Action act = () => Dosage.Create(5m, "mg");
act.Should().NotThrow();

// Assert specific exception properties
act.Should().Throw<DomainException>()
    .Which.ErrorCode.Should().Be("Patient.NotFound");

// Custom helper extension for the Result pattern
public static class ResultAssertions
{
    public static void ShouldSucceed<T>(this Result<T> result)
    {
        result.IsSuccess.Should().BeTrue(
            $"expected success but got failure: {result.Error?.Description}");
    }

    public static void ShouldFailWith(this Result result, string errorCode)
    {
        result.IsFailure.Should().BeTrue("expected failure but got success");
        result.Error.Code.Should().Be(errorCode,
            $"expected error code '{errorCode}' but got '{result.Error.Code}'");
    }
}

// Usage
result.ShouldSucceed();
result.ShouldFailWith("Patient.MRNAlreadyExists");

// Add context to failure messages with "because" parameter
patient.IsActive.Should().BeTrue("because we just created an active patient");
result.IsSuccess.Should().BeTrue(
    $"because command was valid but handler returned: {result.Error?.Description}");

// Multiple assertions — use AssertionScope for batch assertions
// Without scope: first failure stops the test
// With scope: ALL failures reported at once
using (new AssertionScope())
{
    patient.Name.Should().Be("John Smith");
    patient.MRN.Should().Be("MRN-001");
    patient.IsActive.Should().BeTrue();
    patient.Department.Should().Be("Cardiology");
}
// If 3 of these fail, all 3 failures are reported in one test run

[Fact]
public void Patient_created_with_correct_defaults()
{
    var result = Patient.Create("John Smith", new DateOnly(1985, 3, 15), "MRN-001");

    result.IsSuccess.Should().BeTrue();
    var patient = result.Value;

    // All 5 assertions evaluated — all failures reported together
    using (new AssertionScope())
    {
        patient.Name.Should().Be("John Smith");
        patient.MRN.Should().Be("MRN-001");
        patient.IsActive.Should().BeTrue();
        patient.CreatedAt.Should().BeCloseTo(DateTime.UtcNow, TimeSpan.FromSeconds(5));
        patient.Prescriptions.Should().BeEmpty();
    }
}

// Type checking
result.Value.Should().BeOfType<PatientDto>();
result.Value.Should().BeAssignableTo<IEntity>();
result.Error.Should().BeOfType<ValidationError>();

// Cast and continue
var dto = result.Value.Should().BeOfType<PatientDto>().Which;
dto.Name.Should().Be("John Smith");