Moq vs NSubstitute: Choosing the Right Mocking Framework for Modern .NET Projects

-

 


Introduction

Mocking frameworks are one of those tools that quietly shape the quality of your test suite. You don’t think about them much—until your tests become brittle, unreadable, or painful to refactor.

For many years, Moq has been the default choice in the .NET ecosystem. It’s powerful, expressive, and deeply integrated with expression trees. However, over the last decade, NSubstitute has steadily gained popularity as teams look for simpler, more readable, and more refactor-friendly tests.

If you’re starting a new .NET project today, or reconsidering your current testing approach, this question comes up often:

Should I still use Moq, or is NSubstitute the better choice now?

This article explores that question in depth, with real-world code examples, trade-offs, and guidance based on modern development practices.


A Quick Overview

Moq

NSubstitute

Neither is “wrong”. But they encourage very different testing styles.

Philosophy: Power vs Intent

Moq’s Philosophy

Moq is designed to be explicit and powerful. You describe exactly what should happen, how often it should happen, and under what conditions.

This power is great, but it comes with ceremony.

NSubstitute’s Philosophy

NSubstitute aims to make tests read like specifications:

  • “When this happens, return that”

  • “This method should have been called”

  • “This should not have happened”

Less configuration, fewer moving parts, more focus on what rather than how.

Basic Setup Comparison

Scenario

We’re testing a service that depends on a repository.

public interface IUserRepository
{
    User GetById(Guid id);
}

public class UserService
{
    private readonly IUserRepository _repo;
    public UserService(IUserRepository repo)
    {
        _repo = repo;
    }
    public string GetDisplayName(Guid id)
    {
        var user = _repo.GetById(id);
        return user == null ? "Unknown" : user.Name;
    }
}

Moq: Basic Example

var repoMock = new Mock<IUserRepository>();

repoMock
    .Setup(r => r.GetById(It.IsAny<Guid>()))
    .Returns(new User { Name = "Alice" });

var service = new UserService(repoMock.Object);

var result = service.GetDisplayName(Guid.NewGuid());

Assert.Equal("Alice", result);

Observations

  • Explicit setup using expression trees

  • Requires Mock<T> wrapper

  • Clear, but verbose


    NSubstitute: Basic Example

    var repo = Substitute.For<IUserRepository>();

repo.GetById(Arg.Any<Guid>())
    .Returns(new User { Name = "Alice" });

var service = new UserService(repo);

var result = service.GetDisplayName(Guid.NewGuid());

result.ShouldBe("Alice");

    Observations

    • No wrapper object

    • Reads closer to natural language

    • Fewer concepts to learn

    Verifying Calls

    Moq Verification

    repoMock.Verify(
    r => r.GetById(It.IsAny<Guid>()),
    Times.Once);

    This is powerful, but:

    • Requires Times

  • Encourages call-count assertions everywhere


    • NSubstitute Verification

    repo.Received(1)
    .GetById(Arg.Any<Guid>());

    Or simply:

    repo.Received()
    .GetById(Arg.Any<Guid>());

    Why this matters

    NSubstitute’s API nudges you away from over-verification.
    You assert behaviour only when it matters.

    Handling “Should Not Be Called”

    Moq

    repoMock.Verify(
    r => r.Delete(It.IsAny<Guid>()),
    Times.Never);

    NSubstitute

    repo.DidNotReceive()
    .Delete(Arg.Any<Guid>());

    This reads almost exactly like English, and that matters when scanning tests in PRs.

    Argument Matching

    Moq

    repoMock.Setup(r =>
    r.GetById(It.Is<Guid>(id => id != Guid.Empty))
);

    NSubstitute

    repo.GetById(Arg.Is<Guid>(id => id != Guid.Empty));

    Both are expressive, but NSubstitute avoids expression-tree complexity.

    Async Methods

    Moq

    repoMock
    .Setup(r => r.GetAsync(It.IsAny<Guid>()))
    .ReturnsAsync(user);

    NSubstitute

    repo.GetAsync(Arg.Any<Guid>())
    .Returns(Task.FromResult(user));

    Both are fine today, but NSubstitute keeps the API surface smaller.

    Strict Mocks vs Forgiving Defaults

    Moq Strict Mode

    var mock = new Mock<IUserRepository>(MockBehavior.Strict);

    Pros:

    • Forces explicit expectations

    Cons:

    • Adding a new dependency call breaks many tests

    • High maintenance cost

    NSubstitute Defaults

    • Unconfigured calls return defaults

    • Encourages testing outcomes, not implementation

    Refactoring Experience

    This is where teams feel the biggest difference.

    With Moq

    • Rename a method → broken setups

    • Change overloads → runtime exceptions

    • Subtle failures when expressions no longer match

    With NSubstitute

    • Compiler errors appear earlier

    • Fewer runtime surprises

    • Tests break where intent changes, not implementation details

    Over-Mocking and Test Smell

    Moq’s power makes it easy to:

    This often leads to:

    NSubstitute doesn’t prevent this—but it doesn’t encourage it either.

    When Moq Is Still a Good Choice

    Choose Moq if:

    • Your team already uses it heavily

    • You rely on expression-tree-heavy setups

    • You need very precise interaction verification

    • You’re maintaining a large existing codebase

    When NSubstitute Is the Better Default

    Choose NSubstitute if:

    Verdict

    For new .NET projects in 2025:

    NSubstitute is usually the better default choice.

    It produces tests that:

    • are easier to read

    • are easier to maintain

    • break less during refactoring

    • communicate intent clearly

    Moq is still powerful, but power comes at a cost.

Comments

Post a Comment

Popular posts from this blog

Using a Semantic Model as a Reasoning Layer (Not Just Metadata)

-
Image
  Part 1: Using a Semantic Model as a Reasoning Layer (Not Just Metadata) Most systems treat semantic models as documentation. But what if they were active participants in query execution? This question came up while thinking about natural language analytics. Natural Language Is Ambiguous by Default If someone asks: “Show me sales by product this year” There are immediate ambiguities: Which sales measure? At what product level? Calendar or fiscal year? Gross or net? Most tools resolve this by: Picking defaults Or asking the user to clarify But what if the system could reason about the question? The Semantic Model as Context Imagine a model that explicitly defines: Valid measures Valid rollups Default aggregation logic Synonyms and aliases Before executing anything, the system can ask: Is this aggregation valid? Are these measures comparable? Does this level change meaning? This shifts failure from: “The numbers look...
Read more

A Thought Experiment: What If Analytics Models Were Semantic, Not Structural?

-
Image
I’ve been thinking a lot about why analytics and forecasting platforms feel harder to use than they should. Not harder to build,  harder to think with . Most modern data stacks are incredibly capable: Fast databases Columnar storage In-memory caches ML forecasting libraries Yet the questions users struggle to answer haven’t changed much: “Compared to what?” “At what level?” “Is this rolled up correctly?” “Why does this number look wrong?” This feels less like a compute problem and more like a meaning problem . Where Meaning Lives Today In most systems I’ve worked on, meaning is scattered across: Database schemas ETL logic Cube definitions BI metadata Tribal knowledge None of this is explicit. If someone asks: “Can we compare forecast vs actual by category this year?” The system doesn’t reason about that question. It executes SQL and hopes the result makes sense. A Different Framing What if we treated analytics as a sem...
Read more

Dev Tunnels with Visual Studio 2022 and Visual Studio 2026

-
Image
  Securely exposing your local development environment to the world — explained Introduction Developers building web APIs and web applications often face a familiar challenge: how to expose a localhost app to external services, collaborators, mobile devices or testing environments without deploying it to production. Enter Dev Tunnels ,  a powerful feature in Visual Studio that allows you to securely share your local development server over the internet with a public or authenticated URL. It dramatically simplifies workflows involving webhooks , remote debugging, and cross-device testing.  In this article, we’ll explore what Dev Tunnels are, how they work in Visual Studio 2022 , what’s new in the context of Visual Studio 2026 , and practical scenarios for using them. What Are Dev Tunnels? Dev tunnels let you expose a local web app running on localhost to the internet using a secure tunnel endpoint. Once created: You get a remote HTTPS URL that maps to your loc...
Read more