CustomAssertions 1.4.0

CustomAssertions

A modern, fluent assertion library for .NET that provides type-safe, chainable assertions with comprehensive validation capabilities. Designed to work seamlessly with xUnit, NUnit, and MSTest.

✨ Features

• 🔗 Fluent API: Chain multiple assertions together for readable, expressive tests
• 🎯 Type-Safe: Strong typing with compile-time validation
• 📦 Comprehensive: Assertions for strings, integers, collections, dates, records, structs, tuples, and more
• 🧪 Test Framework Agnostic: Works with xUnit, NUnit, MSTest
• 🚀 Modern C#: Leverages latest C# features (records, pattern matching, nullable types)
• 📝 Well-Documented: Full XML documentation for IntelliSense support
• ⚡ Performant: Minimal overhead with efficient implementation
• 🔍 Detailed Error Messages: Clear, descriptive failure messages

📦 Installation

Via NuGet Package Manager

Install-Package CustomAssertions

Via .NET CLI

dotnet add package CustomAssertions

Via PackageReference

<PackageReference Include="CustomAssertions" Version="1.2.0" />

🚀 Quick Start

using CustomAssertions.ConcreteModels;
using Xunit;

public class ExampleTests
{
    [Fact]
    public void StringAssertion_Example()
    {
        var result = new StringAssertions("Hello, World!")
            .NotNullOrEmpty()
            .HasMinimumLength(5)
            .Contains("World")
            .MatchesRegex(@"^Hello.*!")
            .Validate();

        Assert.True(result);
    }

    [Fact]
    public void IntAssertion_Example()
    {
        var result = new IntAssertions(42)
            .IsPositive()
            .IsGreaterThan(10)
            .IsLessThan(100)
            .IsInRange(1, 50)
            .Validate();

        Assert.True(result);
    }
}

📚 Available Assertions

Type-Specific Assertions

• StringAssertions: null/empty checks, length validations, regex matching, contains/not contains
• IntAssertions: positive/negative/zero, comparisons, range validation
• LongAssertions: 64-bit integer validation, even/odd checks, range operations
• ByteAssertions: byte-specific comparisons and range validation
• DecimalAssertions: high-precision decimal validation, scale checks, financial operations
• FloatingPointAssertions: approximate equality, range, special values (NaN, Infinity)
• BoolAssertions: true/false validation, equality checks
• CharAssertions: letter, digit, case, punctuation, whitespace checks
• GuidAssertions: empty/not empty, version validation, format matching
• EnumAssertions: defined values, flag operations, name validation
• DateTimeAssertions: before/after, date range, weekend checks, component validation
• DateTimeOffsetAssertions: timezone-aware date/time validation, offset checks
• TimeSpanAssertions: duration validation, component checks, approximation

Collection & Complex Type Assertions

• CollectionAssertions: empty/not empty, contains item
• DictionaryAssertions: key/value existence, containment checks
• TupleAssertions: length, item validation, reference equality
• NullableAssertions: has value, conditional validation, value equality
• RecordAssertions: value equality for records, reference checks
• StructAssertions: default value, equality checks
• GenericAssertions: type checks, custom predicates, equality operations
• ExceptionAssertions: exception message, type, inner exception, stack trace validation

� Aggregate Model Example: Airline Reservation System

CustomAssertions includes a complete Domain-Driven Design (DDD) aggregate model example demonstrating enterprise-level patterns and validation. This airline reservation system showcases:

📐 Architecture Patterns

• Aggregate Root Pattern: Reservation manages consistency boundary
• Entity Pattern: Flight, Passenger, Ticket with identity and lifecycle
• Value Object Pattern: Immutable Ticket with value semantics
• Smart Constructors: Validation at construction time
• Encapsulation: Private setters, controlled mutation

🔧 Model Components

Reservation (Aggregate Root)

var flight = new Flight("AA123", "JFK", "LAX", DateTime.UtcNow.AddDays(7));
var passenger = new Passenger("John Smith", "john.smith@email.com");
var reservation = new Reservation(flight, passenger);

// Automatic ticket issuance upon reservation creation
Assert.NotNull(reservation.Ticket);
Assert.True(reservation.IsActive);

// Cancel reservation (affects ticket state)
reservation.Cancel();
Assert.False(reservation.IsActive);

Flight Entity

var flight = new Flight("AA123", "JFK", "LAX", DateTime.UtcNow.AddDays(7));

// Validation with CustomAssertions
new StringAssertions(flight.FlightNumber)
    .NotNullOrEmpty()
    .HasMinimumLength(1)
    .Validate();

new DateTimeAssertions(flight.DepartureTime)
    .IsAfter(DateTime.UtcNow)
    .Validate();

Passenger Entity

var passenger = new Passenger("John Smith", "john.smith@email.com");

// Built-in validation
Assert.Equal("John", passenger.FirstName);
Assert.Equal("Smith", passenger.LastName);

// Email validation with CustomAssertions
new StringAssertions(passenger.Email)
    .NotNullOrEmpty()
    .Contains("@")
    .Validate();

Ticket Value Object/Entity

var ticket = reservation.Ticket;

// Verify ticket properties
Assert.Equal(reservation.Id, ticket.ReservationId);
Assert.Equal(flight.FlightNumber, ticket.FlightNumber);
Assert.Equal(passenger.Name, ticket.PassengerName);

// Check ticket validity
new BoolAssertions(ticket.IsValid)
    .IsTrue()
    .Validate();

✅ Comprehensive Test Coverage

The aggregate model includes 29 comprehensive unit tests covering:

• ✓ Entity Validation: Flight, Passenger, Ticket creation and validation
• ✓ Aggregate Consistency: Reservation maintains invariants across entities
• ✓ Business Rules: Cancellation workflow, state transitions
• ✓ Edge Cases: Null handling, empty values, boundary conditions
• ✓ Integration: Entity relationships and aggregate boundaries

Test Results: 581 total tests, 29 for aggregate model, 100% pass rate

See CustomAssertions.Tests/ReservationAggregateTests.cs for complete test examples.

💡 Key Learnings

This aggregate demonstrates:

1. Aggregate Boundaries: All changes flow through the aggregate root
2. Consistency Enforcement: Ticket automatically issued upon reservation
3. Encapsulation: Internal entities accessed only through aggregate
4. Validation Patterns: Constructor validation + CustomAssertions for testing
5. Immutability: Private setters prevent external mutation
6. State Management: IsActive computed from ticket state

�🏗️ Architecture

The library follows these design principles:

• SOLID Principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
• Fluent Interface Pattern: Enables method chaining for readable code
• Template Method Pattern: Base classes define structure, concrete classes implement specifics
• Curiously Recurring Template Pattern (CRTP): Type-safe fluent chaining

🔧 Requirements

• .NET 6.0 or higher (.NET 6, .NET 7, .NET 8, .NET 9 supported)
• C# 10 or higher (for modern language features)

📄 License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Made with ❤️ by Darel Johnson

Copyright © 2024 Darel Johnson. All rights reserved.