FastMoq Documentation

Welcome to the FastMoq documentation home page. Use this site when you already know you want FastMoq and need the right guide, package, or capability area for a specific test surface.

If you are evaluating the project itself and want the high-level value proposition first, start with the GitHub repository home page.

Package Overview

FastMoq ships as an aggregate package plus focused helper packages so a test suite can stay broad or stay lightweight depending on what it needs.

  • FastMoq bundles the provider-first runtime, web helpers, database helpers, Azure SDK helpers, Azure Functions helpers, provider integrations, and analyzer assets in one package.
  • FastMoq.Core and FastMoq.Abstractions provide the provider-neutral runtime and provider contracts for lighter installs, selective package composition, and custom-provider scenarios.
  • FastMoq.Web covers controller, HttpContext, IHttpContextAccessor, claims-principal, and Blazor or bUnit-oriented test helpers.
  • FastMoq.Database adds DbContext-focused helpers, including mocked-set flows and explicit real in-memory test modes.
  • FastMoq.Azure adds Azure SDK test helpers for pageable builders, token credentials, Azure configuration and service-provider setup, and common client registration.
  • FastMoq.AzureFunctions adds Azure Functions worker and HTTP-trigger helpers for FunctionContext.InstanceServices, HttpRequestData, HttpResponseData, and request or response body readers.
  • FastMoq.Provider.Moq and FastMoq.Provider.NSubstitute add provider adapters when a suite wants provider-native arrange syntax while keeping the rest of the harness provider-first.
  • FastMoq.Analyzers keeps the provider-first diagnostics and code fixes available even when you want guidance without the full runtime package.

For the full install matrix and package-choice decision tree, start with Getting Started package choices.

🆕 Release Highlights Since 3.0.0

If you are coming from the last public 3.0.0 package, the biggest changes in the current line are:

  • provider-first architecture with automatic effective-provider discovery plus explicit provider registration and selection when needed
  • new package split across the aggregate runtime, Azure SDK helpers, Azure Functions helpers, database helpers, web helpers, and provider-specific adapters
  • first-party Azure SDK and Azure Functions HTTP-trigger helpers, with analyzer assets included by default in both FastMoq and FastMoq.Core
  • provider-neutral verification with TimesSpec, Verify(...), and VerifyLogged(...)
  • fluent Scenario.With(...).When(...).Then(...).Verify(...) support for workflow-style tests
  • explicit policy surfaces for constructor fallback, method fallback, known-type resolution, and optional-parameter behavior
  • expanded migration guidance, executable examples, and generated API coverage

Provider-First Authoring Ladder

Use this order when you are deciding which example or helper shape to copy into a new or actively edited test:

  1. Start with provider-neutral helpers such as GetOrCreateMock(...), Verify(...), VerifyLogged(...), VerifyNoOtherCalls(...), WhenHttpRequest(...), and AddType(...).
  2. Use tracked IFastMock<T> provider extensions such as Setup(...), SetupGet(...), SetupSequence(...), or AsNSubstitute() when the selected provider package exposes them and the arrange step still needs provider-specific syntax.
  3. Use explicit AsMoq(), raw provider-native APIs, or compatibility wrappers only for the remaining gaps such as protected members, out or ref verification, or other provider-specific pockets.

When a first-party FastMoq helper already exists for the dependency or framework primitive, prefer that helper over handwritten setup even when the handwritten version would still work.

📚 Documentation Structure

🚀 Getting Started

Perfect for developers new to FastMoq. Learn the basics and write your first test in minutes.

🔄 Migration Guide

Practical guidance for moving from the public 3.0.0 release toward the current 4.3.0 provider-first patterns.

  • Recommended API ladder
  • Migration decision table
  • Package and provider bootstrap guidance
  • Old-to-new API replacements and compatibility exceptions

🔎 API Reference

Use the docs-side API overview when you want example-first entry points and curated type routes. Use the generated API namespace and type pages under the site-wide API Reference navigation group when you want the full published namespace, type, and member reference.

  • Example-first API routes
  • Quick reference for common types
  • Provider contract entry points
  • Generated namespace and type reference

📊 Feature Parity

Comprehensive comparison of FastMoq with other popular mocking frameworks.

  • Side-by-side feature comparison
  • Migration guides from Moq and NSubstitute
  • Links to runnable benchmarks when raw overhead comparisons matter
  • When to choose FastMoq vs alternatives

👨‍🍳 Cookbook

Practical recipes for real-world testing scenarios.

  • API Controller testing
  • Entity Framework Core with DbContext
  • Background Services and hosted services
  • HttpClient and external API integration
  • Configuration and Options patterns
  • Logging verification
  • Azure Services integration
  • File system operations

🏗️ Sample Applications

Sample documentation plus repo-local executable examples that demonstrate FastMoq in production-like scenarios.

  • E-Commerce Order Processing - Complete sample documentation under docs/samples/ecommerce-orders
  • Executable Testing Examples - Smaller repo-local service tests that track current FastMoq guidance

📈 Benchmarks

Runnable BenchmarkDotNet coverage for current provider-first FastMoq flows.

  • FastMoq.Benchmarks compares direct Moq against current FastMoq usage
  • Includes the exact run command and benchmark scope for this branch
  • Links to the latest checked-in short-run results summary

🗺️ Roadmap Notes

Current provider-first direction, active architectural work, and intentionally deferred items.

🆕 What's New Since 3.0.0

Summary of the major architecture, packaging, API, and documentation changes after the May 12, 2025 3.0.0 baseline.

⚠️ Breaking Changes

Intentional v4 breaking changes, with migration notes for changed behavior.

🎯 Quick Navigation

By Experience Level

Experience Start Here Next Steps
New to Mocking Getting Started Simple Cookbook Examples
Coming from Moq Feature Parity Migration Guide
Enterprise Teams Sample Applications Testing Guide

By Use Case

Use Case Documentation Sample Code
Web APIs API Controller Testing E-Commerce Sample
Web helper migration Framework and web helper migration Repo-native testing guide
Database Testing EF Core Testing E-Commerce Sample
Azure Integration Sample Applications E-Commerce sample walkthrough
Background Jobs Background Services Executable Testing Examples
Blazor Apps bUnit and Blazor test migration Executable Testing Examples

Direct routes:

Package note: FastMoq is the aggregate package. Provider contracts for custom providers and advanced extensions live in FastMoq.Abstractions, FastMoq.Core keeps the provider-neutral runtime, shared Azure SDK helpers live in the FastMoq.Azure.* namespaces, EF-specific helpers live in FastMoq.Database, Azure Functions worker and HTTP-trigger helpers live in FastMoq.AzureFunctions.Extensions, provider-specific adapters live in FastMoq.Provider.*, web helpers live in FastMoq.Web.Extensions, and analyzer assets ship with both FastMoq and FastMoq.Core by default while the primary runtime calls stay in the FastMoq or FastMoq.Extensions namespaces.

Web helper note: if your test project references the aggregate FastMoq package, the web helpers are already included. If your test project references FastMoq.Core directly, add FastMoq.Web before using helpers such as CreateHttpContext(...), CreateControllerContext(...), SetupClaimsPrincipal(...), AddHttpContext(...), or AddHttpContextAccessor(...).

Azure SDK helper note: if your test project references the aggregate FastMoq package, the shared Azure SDK helpers are already included. If your test project references FastMoq.Core directly, add FastMoq.Azure before using PageableBuilder, the credential helpers, Azure-oriented configuration/service-provider helpers, or the client registration helpers.

Azure Functions helper note: if your test project references the aggregate FastMoq package, the Azure Functions helpers are already included. If your test project references FastMoq.Core directly, add FastMoq.AzureFunctions and import FastMoq.AzureFunctions.Extensions before using CreateFunctionContextInstanceServices(...), AddFunctionContextInstanceServices(...), CreateHttpRequestData(...), or CreateHttpResponseData(...).

See Getting Started package choices when you need the full install matrix instead of a quick reminder.

🏆 What This Site Covers

This documentation is intended to help you move quickly without guessing which FastMoq surface to reach for.

📝 Less Test Harness Boilerplate

  • tracked mocks through GetOrCreateMock<T>() instead of separate mock fields for each constructor dependency
  • automatic component construction so tests stay focused on behavior instead of constructor wiring
  • first-party helpers for framework-heavy types such as logging, HttpClient, IFileSystem, DbContext, and HTTP context flows

🎛️ Provider-First Authoring

  • provider-neutral helpers first, including Verify(...), VerifyLogged(...), VerifyNoOtherCalls(...), and TimesSpec
  • provider-package extensions such as Setup(...), SetupGet(...), SetupSequence(...), and AsNSubstitute() only when the arrange step actually needs provider-native syntax
  • explicit compatibility guidance for Moq-heavy migration pockets that still need raw provider APIs

🌐 Framework And Package Coverage

  • aggregate and split-package guidance for FastMoq, FastMoq.Core, FastMoq.Web, FastMoq.Azure, FastMoq.AzureFunctions, FastMoq.Database, and provider packages
  • repo-backed examples for controller, web, logging, background-service, and DbContext-style tests
  • API overview plus generated namespace and type pages for the current public surface

🔄 Migration And Release Guidance

  • focused guidance for teams moving from the public 3.0.0 release to the current v4 line
  • breaking-change notes, provider-selection guidance, and compatibility exceptions
  • executable examples and sample walkthroughs that reflect the provider-first direction of the current branch

📖 Learning Path

1. Foundation (30 minutes)

  1. Read Getting Started
  2. Read the Testing Guide
  3. Keep the API quick reference nearby for type lookups while you write tests

2. Raw Mock Cleanup (1 hour)

  1. Read the Recommended API ladder
  2. Use API replacements and migration exceptions for the high-churn old-to-new rewrites
  3. Keep migration-only Moq pockets explicit instead of letting them leak back into general-purpose helpers

3. Ambiguity And Multi-Instance Cases (30 minutes)

  1. Read Keyed services and same-type dependencies
  2. Read Provider and compatibility guidance
  3. Use the detached and tracked decision tables before introducing a fresh Mocker just to get a second mock

4. Equality And Verification Semantics (30 minutes)

  1. Read MockModel equality semantics
  2. Read the reflection-provider caveats in Provider capabilities
  3. Use Executable testing examples when you want detached and tracked verification examples backed by repository tests

🤝 Community and Support

Getting Help

  • Documentation: You're here! Start with the most relevant section above
  • Issues: GitHub Issues for bugs and feature requests
  • Discussions: GitHub Discussions for questions and community help
  • API Reference: API overview plus the generated API Reference navigation tree on the published site

Contributing

We welcome contributions! See our:

Stay Updated

  • ⭐ Star the repository for updates
  • 📋 Watch releases for new versions
  • 🐦 Follow discussions for community insights

🔗 External Links

🏷️ Version Information

This documentation tracks the FastMoq 4.3.0 line and the current v4 package layout.

Ready to get started? Jump to Getting Started or pick a specific topic from the navigation above!