FastMoq.Abstractions 4.0.2

FastMoq

FastMoq is a .NET testing framework for auto-mocking, dependency injection, and test-focused object creation. In v4, it supports a provider-first architecture with a bundled reflection default and optional Moq compatibility when you need it.

Start Here

• If you are evaluating the project for the first time, start with Why FastMoq, Packages, and the documentation links below.
• If you want the shortest path to writing a test, go straight to Getting Started Guide.
• If you are upgrading from the 3.0.0 line, go straight to Migration Guide.

Release Highlights Since 3.0.0

• provider-first architecture built around IMockingProvider, IFastMock<T>, and MockingProviderRegistry
• new package split with FastMoq.Abstractions, FastMoq.Database, FastMoq.Provider.Moq, and FastMoq.Provider.NSubstitute
• provider-neutral verification with Verify(...), VerifyLogged(...), and TimesSpec
• fluent scenario building through Scenario.With(...).When(...).Then(...).Verify(...)
• explicit construction, invocation, and known-type policies instead of older coupled option bags
• expanded migration docs, executable examples, and generated API coverage

Why FastMoq

FastMoq is still intended to remove boilerplate compared with using a mock provider directly.

The value is not only shorter setup calls. The bigger value is that FastMoq keeps the repetitive test harness work out of the test body:

• no separate mock field for every constructor dependency
• no manual new Mock<T>() declarations just to build the subject under test
• no long constructor call that must be updated every time the component gains a new dependency
• built-in support for common framework-heavy test types such as ILogger, IFileSystem, HttpClient, and DbContext
• tracked mocks plus provider-neutral verification and logging helpers

FastMoq vs Direct Mock Provider Usage

Using a mock provider directly:

public class OrderProcessingServiceTests
{
    [Fact]
    public async Task PlaceOrderAsync_ShouldPersistAndLog_WhenReservationAndPaymentSucceed()
    {
        var inventoryGateway = new Mock<IInventoryGateway>();
        var paymentGateway = new Mock<IPaymentGateway>();
        var orderRepository = new Mock<IOrderRepository>();
        var logger = new Mock<ILogger<OrderProcessingService>>();

        var component = new OrderProcessingService(
            inventoryGateway.Object,
            paymentGateway.Object,
            orderRepository.Object,
            logger.Object);

        inventoryGateway
            .Setup(x => x.ReserveAsync("SKU-RED-CHAIR", 2, CancellationToken.None))
            .ReturnsAsync(true);

        paymentGateway
            .Setup(x => x.ChargeAsync("cust-42", 149.90m, CancellationToken.None))
            .ReturnsAsync("pay_12345");

        var result = await component.PlaceOrderAsync(new OrderRequest
        {
            CustomerId = "cust-42",
            Sku = "SKU-RED-CHAIR",
            Quantity = 2,
            TotalAmount = 149.90m,
        }, CancellationToken.None);

        result.Success.Should().BeTrue();
        orderRepository.Verify(x => x.SaveAsync(It.IsAny<OrderRecord>(), CancellationToken.None), Times.Once);
    }
}

Using FastMoq:

public class OrderProcessingServiceTests : MockerTestBase<OrderProcessingService>
{
    [Fact]
    public async Task PlaceOrderAsync_ShouldPersistAndLog_WhenReservationAndPaymentSucceed()
    {
        Mocks.GetOrCreateMock<IInventoryGateway>()
            .Setup(x => x.ReserveAsync("SKU-RED-CHAIR", 2, CancellationToken.None))
            .ReturnsAsync(true);

        Mocks.GetOrCreateMock<IPaymentGateway>()
            .Setup(x => x.ChargeAsync("cust-42", 149.90m, CancellationToken.None))
            .ReturnsAsync("pay_12345");

        var result = await Component.PlaceOrderAsync(new OrderRequest
        {
            CustomerId = "cust-42",
            Sku = "SKU-RED-CHAIR",
            Quantity = 2,
            TotalAmount = 149.90m,
        }, CancellationToken.None);

        result.Success.Should().BeTrue();
        Mocks.Verify<IOrderRepository>(x => x.SaveAsync(It.IsAny<OrderRecord>(), CancellationToken.None), TimesSpec.Once);
        Mocks.VerifyLogged(LogLevel.Information, "Placed order");
    }
}

The FastMoq version removes explicit mock declarations, subject construction, and logger-plumbing code while still allowing provider-specific setup when you need it.

📚 Documentation

Quick Links

• 🚀 Getting Started Guide - Your first FastMoq test in 5 minutes
• 🧪 Testing Guide - Repo-native guidance for GetOrCreateMock<T>(), AddType(...), DbContext, IFileSystem, and known types
• 🔌 Provider Selection Guide - How to register, select, and bootstrap providers for a test assembly
• 👨‍🍳 Cookbook - Real-world patterns and recipes
• 🏗️ Sample Applications - Complete examples with Azure integration
• 🧪 Executable Testing Examples - Repo-backed service examples using the current FastMoq API direction
• 📊 Feature Comparison - FastMoq vs Moq/NSubstitute
• 📈 Performance Benchmarks - Productivity and performance metrics

Additional Resources

• 📖 Complete Documentation - All guides and references in one place
• 🗺️ Roadmap Notes - Current provider-first direction and deferred backlog items
• 🆕 What's New Since 3.0.0 - Summary of the major post-3.0.0 architecture, packaging, and API changes
• ⚠️ Breaking Changes - Intentional v4 behavior changes relative to the 3.0.0 public release
• 🔄 Migration Guide - Practical old-to-new guidance from 3.0.0 to the current repo direction
• ❓ FAQs - Frequently asked questions and troubleshooting
• 🔗 API Documentation - Generated HTML API reference

Features

• NOW BLAZOR SUPPORT in FastMoq and FastMoq.Web.
• Test without declaring Mocks (unless needed).
• Creates objects with chain of automatic injections in objects and their dependencies.
• Creates Mocks and Objects with properties populated.
• Automatically injects and creates components or services.
• Injection: Automatically determines what interfaces need to be injected into the constructor and creates mocks if they do not exist.
  • Generate Mock using specific data.
  • Best guess picks the multiple parameter constructor over the default constructor.
  • Specific mapping allows the tester to create an instance using a specific constructor and specific data.
  • Supports Inject Attributes and multiple constructors.
• Use Mocks without managing fields and properties. Mocks are managed by the Mocker framework. No need to keep track of Mocks. Just use them!
• Create instances of Mocks with non public constructors.
• HttpClient and IFileSystem test helpers
• DbContext support through the optional FastMoq.Database package, with the primary calls staying in the FastMoq namespace.
• Supports Null method parameter testing.
• Comprehensive Documentation - Complete guides, samples, and real-world patterns.
• Lower Test Boilerplate - Less fixture code than manual mock declaration plus manual subject construction.

Packages

• FastMoq - Aggregate package that combines the primary FastMoq runtime, database helpers, and web support.
• FastMoq.Abstractions - Shared provider contracts used by core and provider packages.
• FastMoq.Core - Core testing Mocker and provider-first resolution pipeline.
• FastMoq.Database - Entity Framework and DbContext-focused helpers.
• FastMoq.Provider.Moq - Moq compatibility provider and Moq-specific convenience extensions for v4 migration.
• FastMoq.Provider.NSubstitute - Optional NSubstitute provider package.
• FastMoq.Web - Blazor and web support.

In the current v4 layout, FastMoq.Core bundles the internal reflection provider and the bundled moq compatibility provider. The default provider is reflection. Additional providers such as nsubstitute can be added explicitly.

Typical split-package install:

dotnet add package FastMoq.Core
dotnet add package FastMoq.Database
dotnet add package FastMoq.Web

GetMockDbContext<TContext>() keeps the same main call shape in the FastMoq namespace. If you install FastMoq, the EF helpers are included. If you install FastMoq.Core directly, add FastMoq.Database for DbContext support.

GetMockDbContext<TContext>() remains the default mocked-sets entry point. For explicit mode selection between mocked DbSets and a real EF in-memory context, use GetDbContextHandle<TContext>(new DbContextHandleOptions<TContext> { ... }).

The mocked-sets path is still backed by the existing Moq-based DbContextMock<TContext> implementation, while the real-context path is exposed through DbContextTestMode.RealInMemory.

If you are upgrading an older suite that still uses GetMock<T>(), direct Mock<T> access, VerifyLogger(...), or older HTTP setup helpers such as SetupHttpMessage(...), select Moq explicitly for that test assembly. If you are writing new or actively refactoring tests, prefer provider-neutral APIs such as GetOrCreateMock(...), Verify(...), VerifyLogged(...), WhenHttpRequest(...), and WhenHttpRequestJson(...). When you still need provider-specific setup in v4, use the provider-package extensions on IFastMock<T> such as AsMoq(), Setup(...), or AsNSubstitute().

For the moved HTTP compatibility helpers, the migration point is package selection rather than namespace churn: the Moq compatibility methods remain in the FastMoq.Extensions namespace for low-churn source migration, but their implementation now comes from the FastMoq.Provider.Moq package instead of FastMoq.Core.

Provider selection example:

MockingProviderRegistry.Register("moq", MoqMockingProvider.Instance, setAsDefault: true);
var mocker = new Mocker();

For a temporary override in a specific async scope, use MockingProviderRegistry.Push("providerName"). For detailed setup guidance, see Provider Selection Guide.

Targets

• .NET 9
• .NET 8
• .NET 10

Quick Example

public class OrderProcessingServiceTests : MockerTestBase<OrderProcessingService>
{
    [Fact]
    public async Task PlaceOrderAsync_ShouldPersistAndLog_WhenReservationAndPaymentSucceed()
    {
        Mocks.GetOrCreateMock<IInventoryGateway>()
            .Setup(x => x.ReserveAsync("SKU-RED-CHAIR", 2, CancellationToken.None))
            .ReturnsAsync(true);

        Mocks.GetOrCreateMock<IPaymentGateway>()
            .Setup(x => x.ChargeAsync("cust-42", 149.90m, CancellationToken.None))
            .ReturnsAsync("pay_12345");

        var result = await Component.PlaceOrderAsync(new OrderRequest
        {
            CustomerId = "cust-42",
            Sku = "SKU-RED-CHAIR",
            Quantity = 2,
            TotalAmount = 149.90m,
        }, CancellationToken.None);

        result.Success.Should().BeTrue();
        Mocks.Verify<IOrderRepository>(x => x.SaveAsync(It.IsAny<OrderRecord>(), CancellationToken.None), TimesSpec.Once);
        Mocks.VerifyLogged(LogLevel.Information, "Placed order");
    }
}

Common Entry Points

• MockerTestBase<TComponent>: shortest path for service and component tests with automatic construction and dependency injection
• Mocker: standalone entry point when you do not want a test base class
• GetMock<T>(): lowest-churn compatibility path for older Moq-shaped tests in v4
• GetOrCreateMock<T>(): tracked provider-first mock access for the forward v4 and v5 path
• Verify(...), VerifyNoOtherCalls(...), VerifyLogged(...), and TimesSpec: provider-neutral verification surface

Learn More

• Getting Started Guide for step-by-step first tests
• Testing Guide for common patterns such as IFileSystem, DbContext, CallMethod(...), and constructor-guard testing
• Executable Testing Examples for realistic sample flows backed by repository tests
• Provider Selection Guide for provider bootstrap and selection
• Migration Guide for the v3 to v4 to v5 path
• Breaking Changes for behavior changes relative to 3.0.0
• API Documentation for generated reference docs

License

License - MIT