Mocking with Moq: Missing Setup Returns Null in Production

Every serious C# application talks to things it doesn't control — databases that can go offline, payment APIs that cost money per call, email servers that send real emails to real people. When you want to test the logic that orchestrates all those moving parts, you can't just fire up the real infrastructure for every test run. That's not just slow — it's unpredictable, expensive, and a maintenance nightmare. This is the problem unit testing was born to solve, and it's the reason mocking frameworks exist. Moq is the most popular mocking library in .NET. It's mature, flexible, and it handles the vast majority of what you'll need. But it's not magic. Without understanding its internals — how Setup, Returns, Verify, Callback, and SetupSequence actually work — you'll write tests that pass in isolation but fail in production. This guide goes deep into those mechanics and the patterns that separate senior engineers from the rest.

What Is Mocking with Moq in C#?

Moq (pronounced 'mock-you') is a .NET library that generates proxy implementations of interfaces and abstract classes at runtime. When you call a method on the proxy, Moq intercepts it and returns the value you specified via Setup. This lets you replace real dependencies — a database context, an HTTP client, a file system — with a controllable fake. The two fundamental operations are:

1. Setup — tell the mock how to behave when a method is called.
2. Verify — assert that the method was called with the expected arguments.

Senior engineers almost always start with Strict in new tests and loosen only when there's a good reason, typically to reduce boilerplate for test utility methods.

namespace TheCodeForge.MoqDemo;

public interface IEmailService
{
    void Send(string to, string subject, string body);
}

// Test example
[Fact]
public void Send_email_calls_service()
{
    var mock = new Mock<IEmailService>(MockBehavior.Strict);
    mock.Setup(m => m.Send("user@example.com", "Hi", It.IsAny<string>()));

    var service = new NotificationService(mock.Object);
    service.SendWelcomeEmail("user@example.com");

    mock.Verify(m => m.Send("user@example.com", "Hi", It.IsAny<string>()), Times.Once);
}

Setting Up Mocks — Returns, Throws, and Parameters

Setup is the core operation. You express: 'When method X is called with arguments matching these conditions, do Y.' The matching engine supports exact values, predicate expressions, and wildcard matchers like It.IsAny<T>(), It.Is<T>(predicate), and It.IsInRange<T>(min, max).

Returns() specifies the return value or an expression that computes it lazily. Throws() makes the mock throw an exception. For void methods, you call .Callback to execute side effects, though Returns is not applicable.

Parameters can be matched by value, condition, or any. Be careful with reference types — Moq uses Equals() for matching, so custom objects need proper Equals override or use It.Is<T>(x => x.SomeProperty == expected).

namespace TheCodeForge.MoqDemo;

public interface IOrderRepository
{
    Order GetById(int id);
    void Save(Order order);
}

// Test: setup with predicate and Returns
[Fact]
public void GetById_returns_specific_order()
{
    var mock = new Mock<IOrderRepository>(MockBehavior.Strict);
    mock.Setup(r => r.GetById(It.Is<int>(id => id > 0)))
        .Returns<int>(id => new Order { Id = id, Amount = 100 });

    var result = mock.Object.GetById(42);
    Assert.Equal(100, result.Amount);
}

// Setup throws
mock.Setup(r => r.Save(It.IsAny<Order>()))
    .Throws<DbConcurrencyException>();

Verification — Ensuring Methods Were Called

Verification is the second pillar. After the SUT runs, you ask: 'Was method X called exactly N times with these arguments?' The Verify method takes the same expression as Setup, plus an optional Times constraint. Without the times parameter, it defaults to Times.AtLeastOnce().

namespace TheCodeForge.MoqDemo;

[Fact]
public void Verify_multiple_invocations()
{
    var mock = new Mock<ILogger>(MockBehavior.Loose);
    var service = new Processor(mock.Object);
    
    service.RunBatch(new[] { 1, 2, 3 });
    
    // Verify exactly 3 calls to LogInfo
    mock.Verify(l => l.LogInfo(It.IsAny<string>()), Times.Exactly(3));
    // Verify LogError was never called
    mock.Verify(l => l.LogError(It.IsAny<string>()), Times.Never);
}

Advanced Patterns — Callbacks, Sequences, and Recursive Mocks

Callbacks allow you to inspect or modify the arguments passed to the mocked method. Use .Callback(...) with matching argument types to capture values. This is invaluable for testing code that pushes data into a dependency — you can assert what was sent.

Sequences model multi-step interactions where the same method must return different values on successive calls. SetupSequence() accepts a chain of Returns, Throws, or Callbacks. After the last item, subsequent calls throw by default (unless you add a final Returns for covering).

Recursive mocks happen when a mock returns another mock. If your interface returns an interface, and that interface returns another, you can set up the chain automatically using DefaultValue.Mock. This reduces boilerplate but can hide deep failures.

namespace TheCodeForge.MoqDemo;

public interface IStateMachine
{
    State GetNext();
}

[Fact]
public void Sequence_returns_in_order()
{
    var mock = new Mock<IStateMachine>(MockBehavior.Strict);
    mock.SetupSequence(m => m.GetNext())
        .Returns(State.Initial)
        .Returns(State.Processing)
        .Returns(State.Final);

    Assert.Equal(State.Initial, mock.Object.GetNext());
    Assert.Equal(State.Processing, mock.Object.GetNext());
    Assert.Equal(State.Final, mock.Object.GetNext());
}

//Callback to capture argument
var callbackArg = string.Empty;
mock.Setup(x => x.Log(It.IsAny<string>()))
    .Callback<string>(msg => callbackArg = msg);

Production Gotchas — MockBehavior, Async, and Timeouts

Even with solid test coverage, Moq can betray you in production. The most common incidents:

1. Loose behavior masking missing setups — your test passes because Moq returns null/0 for unset methods, but production code expects a real object.
2. Async mocks not awaited — a method returning Task but not awaited in the SUT means the mock's ReturnsAsync is never observed; the test may pass but production runs synchronously or deadlocks.
3. Time-dependent mocks — mocking DateTime.Now or similar static calls is impossible with Moq; you need to inject an abstraction (e.g., ISystemClock).
4. Out/ref parameters — hard to set up and verify. Use It.Ref<T>.IsAny for ref matching and store output values via Callback.

Senior engineers always run their test suite with both mock behaviors at least once during CI to catch Loose-vs-Strict discrepancies.

namespace TheCodeForge.MoqDemo;

// Async setup
mock.Setup(x => x.GetDataAsync()).ReturnsAsync(new Data());

// SUT must await, else test may pass but production runs sync
// public async Task<Data> Fetch() => await _dependency.GetDataAsync();

// Ref parameter
mock.Setup(x => x.TryGetValue(It.IsAny<int>(), out It.Ref<int>.IsAny))
    .Callback(new InvocationAction(invocation =>
    {
        invocation.Arguments[1] = 42; // assign output
    }))
    .Returns(true);

Partial Mocks — When You Need a Real Object with a Few Fakes

You're testing a legacy payment service that makes a database call you can't untangle easily. You don't want to mock the entire thing — that's 14 interfaces and a prayer. You need one real method and one fake.

Partial mocks let you create a real instance of a class and override specific members. Moq does this with As() or by passing a mock to the constructor. The rule: default behavior is real, setup behavior overrides it.

Why reach for this? When you own the code and refactoring isn't on the table. When a third-party SDK has 50 virtual methods and you only need to intercept two. It's surgical.

Warning: partial mocks are a code smell. If you're doing this more than once a quarter, your design is broken. The real fix is an interface. But for today's hotfix at 2 AM, this is what saves your ass.

// io.thecodeforge — csharp tutorial

public class PaymentProcessor
{
    public virtual bool Authorize(string card)
    {
        return ExternalSdk.Call(card); // Real call
    }

    public virtual bool Refund(string transactionId)
    {
        throw new NotImplementedException(); // Legacy junk
    }
}

[Test]
public void Refund_Fails_Gracefully()
{
    var mock = new Mock<PaymentProcessor>();
    mock.Setup(p => p.Refund(It.IsAny<string>()))
        .Returns(false);

    // Authorize uses real implementation
    // Refund uses our fake
    var processor = mock.Object;
    var refunded = processor.Refund("txn_abc");

    Assert.That(refunded, Is.False);
}

Mocking Internals and Protected Members — Breaking the Barrier

You need to test an internal method that does the heavy lifting. Someone sealed the class. The method is protected virtual. Moq doesn't care about your access modifiers if you use Mock.Protected().

This is for white-box testing. You're asserting how the sausage is made, not just what comes out. You're doing it because the public interface is too coarse to isolate the bug.

Setup a protected member: mock.Protected().Setup("InternalCheck", ItExpr.IsAny()).Returns(true). Verification works the same way. The string name must match exactly. No refactoring safety. No compiler errors if you rename it. That's the cost.

Senior shortcut: use this only when you control the source and the test proves a specific logic path. If you find yourself mocking internals of a third-party assembly, stop. You're doing integration testing in a unit test harness. That's a different tool.

// io.thecodeforge — csharp tutorial

public class ReportEngine
{
    protected virtual bool ValidateReport(string reportId)
    {
        // Complex validation logic
        return reportId.StartsWith("RPT");
    }

    public string Generate(string reportId)
    {
        return ValidateReport(reportId) ? "OK" : "FAIL";
    }
}

[Test]
public void Generate_Returns_OK_When_Validation_Passes()
{
    var mock = new Mock<ReportEngine>();
    mock.Protected()
        .Setup<bool>("ValidateReport", ItExpr.IsAny<string>())
        .Returns(true);

    var result = mock.Object.Generate("RPT_001");

    Assert.That(result, Is.EqualTo("OK"));
}

Mock.Of() for One-Line Mock Creation

Moq provides a concise syntax for creating mocks in a single line using Mock.Of<T>(). This is particularly useful when you need a simple mock without explicit setup, or when you want to inline mock creation in test parameters. For example, var mock = Mock.Of<IFoo>(); creates a mock with default behavior (all methods return default values). You can also set up expectations directly: var mock = Mock.Of<IFoo>(m => m.Name == "test" && m.DoSomething() == true);. This approach reduces boilerplate and improves readability, especially in Arrange-Act-Assert patterns. However, be cautious: Mock.Of<T>() returns the mocked object directly, not the Mock<T> wrapper, so you lose access to verification and advanced setup. For scenarios where you only need the mock as a stub, this is ideal. In production, use Mock.Of<T>() for simple dependencies in unit tests where you don't need to verify interactions.

public interface IFoo
{
    string Name { get; set; }
    bool DoSomething();
}

// One-line mock creation with default behavior
var foo = Mock.Of<IFoo>();

// One-line mock with setup
var fooWithSetup = Mock.Of<IFoo>(m => m.Name == "test" && m.DoSomething() == true);

// Usage
Console.WriteLine(fooWithSetup.Name); // "test"
Console.WriteLine(fooWithSetup.DoSomething()); // true

AutoMock with AutoFixture + Moq for Cleaner Tests

AutoFixture with the AutoMoq extension automates the creation of mocks and test data, reducing boilerplate in unit tests. By combining AutoFixture's data generation with Moq's mocking, you can create SUTs (System Under Test) with minimal setup. For example, using var fixture = new Fixture().Customize(new AutoMoqCustomization());, you can then call fixture.Create<MyClass>() to automatically create an instance of MyClass with all its dependencies mocked. This is especially powerful for classes with many dependencies, as it eliminates repetitive mock creation. You can also inject specific setups using fixture.Freeze<Mock<IDependency>>() to control behavior. In production, AutoMock reduces test maintenance when dependencies change, as new interfaces are automatically mocked. However, be aware that it can hide important setup details, so use it judiciously for integration-style tests or when dependencies are trivial.

using AutoFixture;
using AutoFixture.AutoMoq;

public class MyService
{
    private readonly IDependency _dep;
    public MyService(IDependency dep) => _dep = dep;
    public int Compute() => _dep.GetValue() * 2;
}

public interface IDependency { int GetValue(); }

// Arrange
var fixture = new Fixture().Customize(new AutoMoqCustomization());
var mockDep = fixture.Freeze<Mock<IDependency>>();
mockDep.Setup(d => d.GetValue()).Returns(5);
var sut = fixture.Create<MyService>();

// Act
var result = sut.Compute();

// Assert
Assert.Equal(10, result);

MockBehavior.Strict vs Loose: When to Use Each

Moq supports two mock behaviors: MockBehavior.Loose (default) and MockBehavior.Strict. Loose mocks return default values (e.g., null, 0, false) for any method or property that hasn't been set up, without throwing exceptions. Strict mocks throw an exception if any member is called without a corresponding setup. Use Loose mocks for most tests where you only care about specific interactions and want to avoid clutter. Strict mocks are useful when you want to ensure that only expected methods are called, often in behavior verification scenarios. For example, var mock = new Mock<IFoo>(MockBehavior.Strict); will throw if mock.Object.DoSomething() is called without a setup. In production, Loose is preferred for its flexibility; Strict can be too brittle for large codebases. However, Strict can catch unintended calls during refactoring. Choose based on test intent: Loose for state-based testing, Strict for interaction-based testing.

public interface IFoo { int GetValue(); void DoSomething(); }

// Loose mock (default) - returns 0 for GetValue, no exception for DoSomething
var looseMock = new Mock<IFoo>(MockBehavior.Loose);
Console.WriteLine(looseMock.Object.GetValue()); // 0
looseMock.Object.DoSomething(); // no exception

// Strict mock - throws if method not set up
var strictMock = new Mock<IFoo>(MockBehavior.Strict);
// strictMock.Object.GetValue(); // throws MockException

// Setup to avoid exception
strictMock.Setup(m => m.GetValue()).Returns(42);
Console.WriteLine(strictMock.Object.GetValue()); // 42