FastMoq.Provider.Moq 4.1.0

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
• 🌐 Web Helper Guidance - Controller, HttpContext, IHttpContextAccessor, and claims-principal test setup
• 🔌 Provider Selection Guide - How to register, select, and bootstrap providers for a test assembly
• 📋 Provider Capabilities - What moq, nsubstitute, and reflection support today, with recommended usage patterns
• 👨‍🍳 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, shared Azure SDK helpers, database helpers, Azure Functions 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.Azure - Shared Azure SDK testing helpers for credentials, pageable builders, Azure-oriented configuration, and common client registration.
• FastMoq.AzureFunctions - Azure Functions worker and HTTP-trigger helpers for typed FunctionContext.InstanceServices setup, concrete HttpRequestData and HttpResponseData builders, and body readers.
• 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.

Web-helper note:

• if you install the aggregate FastMoq package, the web helpers are included
• if you install FastMoq.Core directly, add FastMoq.Web before using CreateHttpContext(...), CreateControllerContext(...), SetupClaimsPrincipal(...), AddHttpContext(...), or AddHttpContextAccessor(...)
• for migration-specific guidance, start with Migration Guide and then use Testing Guide for the day-to-day helper rules
• for the full package-choice overview, use Getting Started

Azure Functions helper note:

• if you install the aggregate FastMoq package, the Azure Functions helpers are included
• if you install FastMoq.Core directly, add FastMoq.AzureFunctions and import FastMoq.AzureFunctions.Extensions before using CreateFunctionContextInstanceServices(...), AddFunctionContextInstanceServices(...), CreateHttpRequestData(...), or CreateHttpResponseData(...)
• the typed CreateTypedServiceProvider(...) and AddServiceProvider(...) helpers remain in FastMoq.Core, while the request and response body readers stay in FastMoq.AzureFunctions.Extensions

Azure SDK helper note:

• if you install the aggregate FastMoq package, the shared Azure SDK helpers are included
• if you install FastMoq.Core directly, add FastMoq.Azure before using PageableBuilder, AddTokenCredential(...), CreateAzureServiceProvider(...), or the Azure client registration helpers
• the Azure helper namespaces are split by concern under FastMoq.Azure.Pageable, FastMoq.Azure.Credentials, FastMoq.Azure.DependencyInjection, FastMoq.Azure.Storage, and FastMoq.Azure.KeyVault

Typical split-package install:

dotnet add package FastMoq.Core
dotnet add package FastMoq.Azure
dotnet add package FastMoq.AzureFunctions
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.

PageableBuilder, AddTokenCredential(...), AddDefaultAzureCredential(...), CreateAzureConfiguration(...), CreateAzureServiceProvider(...), and the Azure client registration helpers live in the FastMoq.Azure.* namespaces.

CreateFunctionContextInstanceServices(...), AddFunctionContextInstanceServices(...), CreateHttpRequestData(...), CreateHttpResponseData(...), ReadBodyAsStringAsync(...), and ReadBodyAsJsonAsync<T>(...) live in FastMoq.AzureFunctions.Extensions, while the generic CreateTypedServiceProvider(...) and AddServiceProvider(...) helpers stay in FastMoq.Extensions.

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
• Provider Capabilities for supported-vs-unsupported behavior by provider
• 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