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<T1, T2>(...) 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<bool>("InternalCheck", ItExpr.IsAny<int>()).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"));
}