Why Every .NET Pro is Ditching Moq for NSubstitute — Your Ultimate Guide to Mocking in Unit Tests

Unit testing is an integral part of modern software development. For years, Moq has been a popular choice in the .NET ecosystem for creating mock objects. Recent concerns over Moq’s SponsorLink feature have prompted some developers to consider such a switch. In this article, we delve into why you might consider NSubstitute over Moq and how to make the transition.

A Reddit thread highlighted concerns about this behavior:

1. Privacy: Extracting and sending email addresses without explicit consent is a significant privacy concern.
2. Security: Such behavior can be seen as a potential supply chain attack vector. Even if Moq’s intentions are benign, it sets a precedent that other, less scrupulous developers might follow.

What is SponsorLink?

As described in the blog post by Daniel Cazzulino, the creator of Moq, SponsorLink is a .NET analyzer that, during build time:

1. Scans your local git config.
2. Extracts your email address.
3. Sends it to a service hosted in Azure to verify if you’re a sponsor.

If you’re not a sponsor, it provides a link to the GitHub Sponsors page for the library. The purpose is to encourage users to sponsor open-source projects they benefit from.

Implications for Developers:

This incident underscores the importance of reading release notes, understanding the behavior of dependencies, and being cautious about updating packages.

Considering an alternative library like NSubstitute:

Given the controversy and the importance of trust in open-source dependencies, some developers might consider switching to alternatives like NSubstitute. NSubstitute has a different approach and does not include such sponsor-oriented features.

Why NSubstitute?

Before diving into the specifics, it’s essential to understand why one might consider moving to NSubstitute:

1. Syntax: NSubstitute boasts a more fluent and readable syntax.
2. Intuitive API: NSubstitute’s API is designed to be more straightforward, reducing the learning curve.
3. Flexibility: NSubstitute offers robust argument matching and auto-mocking capabilities.

Transitioning Step-by-Step:

1. Setup:

This is the initial setup phase where mock objects are created.

Moq: Here, a new mock object of type IMyService is created.

var mockService = new Mock<IMyService>();

NSubstitute: Similarly, a substitute object for the same interface is created using NSubstitute.

var subService = Substitute.For<IMyService>();

2. Returning Values:

This is about setting up mock methods to return specific values.

Moq: This means when the Method() of the mockService is called, it will return the string "value".

mockService.Setup(x => x.Method()).Returns("value");

NSubstitute: The NSubstitute syntax is more concise. The same behavior as above is set.

subService.Method().Returns("value");

3. Argument Matchers:

Allows methods to return values for any argument of a specific type.

Moq: Here, regardless of the integer argument passed to Method(), it will return "value".

mockService.Setup(x => x.Method(It.IsAny<int>())).Returns("value");

NSubstitute: NSubstitute achieves the same with a different syntax.

subService.Method(Arg.Any<int>()).Returns("value");

4. Verifying Calls:

Ensures that methods were called a specific number of times.

Moq: This verifies that the Method() was called once with the argument 42.

mockService.Verify(x => x.Method(42), Times.Once);

NSubstitute: NSubstitute uses Received() to ensure that the method was called with the specified argument.

subService.Received().Method(42);

5. Ignoring Specific Calls:

Ensures that methods were never called with specific arguments.

Moq: This verifies that the Method() was never called with the argument 42.

mockService.Verify(x => x.Method(42), Times.Never);

NSubstitute: With NSubstitute, DidNotReceive() ensures the method wasn't called with the given argument.

subService.DidNotReceive().Method(42);

6. Argument Checking:

Allows for more complex argument matching based on conditions.

Moq: Using custom matchers or It.Is() This sets up the Method() to return "value" only if it's called with an integer argument greater than 10.

mockService.Setup(x => x.Method(It.Is<int>(arg => arg > 10))).Returns("value");

NSubstitute: NSubstitute uses a similar approach to achieve the same.

subService.Method(Arg.Is<int>(arg => arg > 10)).Returns("value");

7. Exception Handling:

Sets up methods to throw exceptions when called.

Moq: This means that when Method() is called, it will throw an exception with the message "Error".

mockService.Setup(x => x.Method()).Throws(new Exception("Error"));

NSubstitute: NSubstitute uses a different syntax. The When...Do construct allows you to define actions, in this case, throwing an exception.

subService.When(x => x.Method()).Do(x => { throw new Exception("Error"); });

By understanding these transitions, you can easily shift from Moq to NSubstitute while retaining the core logic and intent of your unit tests.

Advanced Use Cases:

1. Recursive Mocks:

Setting up mocks for chained calls.

Moq:

var mock = new Mock<IMyService>();
mock.Setup(m => m.ObjectA.PropertyB.MethodC()).Returns("value");

NSubstitute:

var sub = Substitute.For<IMyService>();
sub.ObjectA.PropertyB.MethodC().Returns("value");

2. Property Behavior:

Mocking property getters and setters.

Moq:

mock.SetupGet(m => m.MyProperty).Returns("value");
mock.SetupSet(m => m.MyProperty = "value");

NSubstitute:

sub.MyProperty.Returns("value");
sub.MyProperty = "value";

3. Callbacks:

Performing actions when a mocked method is called.

Moq:

string result = "";
mock.Setup(m => m.Method()).Callback(() => result = "Called!");

NSubstitute:

string result = "";
sub.Method().ReturnsForAnyArgs(x => { result = "Called!"; return true; });

4. Events:

Raising and subscribing to events.

Moq:

var mock = new Mock<IEvents>();
mock.Raise(m => m.MyEvent += null, EventArgs.Empty);

NSubstitute:

var sub = Substitute.For<IEvents>();
sub.MyEvent += Raise.EventWith(EventArgs.Empty);

5. Partial Mocks:

Mocking specific parts of a class.

Moq:

var mock = new Mock<MyClass>() { CallBase = true };
mock.Setup(m => m.VirtualMethod()).Returns("mocked value");

NSubstitute:

var sub = Substitute.ForPartsOf<MyClass>();
sub.VirtualMethod().Returns("mocked value");

6. Ordered Calls Verification:

Verifying the order of method calls.

Moq: Moq doesn’t support ordered verification natively. You’d need to use additional tools or techniques.

NSubstitute:

sub.Received().FirstMethod();
sub.Received().SecondMethod();

7. Advanced Argument Matchers:

More complex argument scenarios.

Moq:

mock.Setup(m => m.Method(It.IsRegex("[a-z]"))).Returns("matched");

NSubstitute:

sub.Method(Arg.Is<string>(arg => Regex.IsMatch(arg, "[a-z]"))).Returns("matched");

Tips for a Smooth Transition:

1. Incremental Changes: You don’t have to change all tests at once. Start with a few tests to get the hang of NSubstitute.
2. Read the Docs: NSubstitute’s documentation is comprehensive and will likely answer any questions you have.
3. Community Support: Engage with the community if you face issues. Both Moq and NSubstitute have active communities that can help.

BONUS: Regex for Transition:

For developers seeking an automated way to refactor their codebase, regex can be a valuable tool. Though not exhaustive, here are a few regex patterns that can replace basic Moq patterns with NSubstitute:

// 1. Setup:
Find:    var mock(\w+) = new Mock<(\w+)>\(\);
Replace: var sub$1 = Substitute.For<$2>();

// 2. Returning Values:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\(\)\)\.Returns\((\w+)\);
Replace: sub$1.$3().Returns($4);

// 3. Argument Matchers:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\(It\.IsAny<(\w+)>\(\)\)\)\.Returns\((\w+)\);
Replace: sub$1.$3(Arg.Any<$4>()).Returns($5);

// 4. Verifying Calls:
Find:    mock(\w+)\.Verify\((\w+) => \w+\.(\w+)\((\w+)\), Times\.Once\);
Replace: sub$1.Received().$3($4);

// 5. Ignoring Specific Calls:
Find:    mock(\w+)\.Verify\((\w+) => \w+\.(\w+)\((\w+)\), Times\.Never\);
Replace: sub$1.DidNotReceive().$3($4);

// 6. Argument Checking:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\(It\.Is<(\w+)>\(arg => arg condition\)\)\)\.Returns\((\w+)\);
Replace: sub$1.$3(Arg.Is<$4>(arg => arg condition)).Returns($5);

// 7. Exception Handling:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\(\)\)\.Throws\(new (\w+)\("(\w+)"\)\);
Replace: sub$1.When($2 => $2.$3()).Do($2 => { throw new $4("$5"); });

// 8. Recursive Mocks:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\.(\w+)\.(\w+)\(\)\)\.Returns\((\w+)\);
Replace: sub$1.$3.$4.$5().Returns($6);

// 9. Property Behavior:
Find:    mock(\w+)\.SetupGet\((\w+) => \w+\.(\w+)\)\.Returns\((\w+)\);
Replace: sub$1.$3.Returns($4);

// 10. Callbacks:
Find:    mock(\w+)\.Setup\((\w+) => \w+\.(\w+)\(\)\)\.Callback\(\(\) => action\);
Replace: sub$1.$3().ReturnsForAnyArgs(x => { action; return true; });

// 11. Events:
Find:    var mock = new Mock<(\w+)>();
Replace: var sub = Substitute.For<$1>();

Find:    mock\.Raise\((\w+) => \w+\.(\w+) \+= null, eventArgs\);
Replace: sub.$2 += Raise.EventWith(eventArgs);

To use these in Visual Studio:

1. Open the Find & Replace tool (Ctrl + H).
2. Make sure to select the “Use Regular Expressions” option (it looks like .* in the Find & Replace dialog).
3. Enter the “Find” pattern in the “Find what” box and the “Replace” pattern in the “Replace with” box.
4. Click “Replace All” or step through with “Find Next” and “Replace” to ensure accuracy.

These regex patterns are tailored to the examples you provided and the additional topics we discussed. Due to the complexity and variations of code patterns, manual adjustments may be necessary after using these patterns. Always review and test the replaced code to ensure correctness.

Conclusion:

While Moq has been a stalwart in the .NET mocking world, NSubstitute offers a compelling alternative, especially in light of recent concerns. As with any transition, it’s essential to weigh the pros and cons, understand the nuances, and thoroughly test the refactored code.

Regardless of the choice between Moq and NSubstitute, the broader lesson is clear: always stay informed about your dependencies and prioritize the security and privacy of your software and its users.

Happy testing!