A cheat sheet to migrate from Moq to NSubstitute

Modified August 02, 2024

Tim Deschryver

timdeschryver.dev

Initialization: new Mock<T>() => Substitute.For<T>()

 Moq.cs 
var mock = new Mock<IService>();
 
// or, if you don't need to customize and verify the mock
var mock = Mock.Of<IService>();
// when using the above, you can still get the mock instance using Mock.Get
var mockInstance = Mock.Get(mock);

 NSubstitute.cs 
var mock = Substitute.For<IService>();

Argument matchers

Matches any value: It.IsAny<T>() => Arg.Any<T>()

 Moq.cs 
It.IsAny<string>()

 NSubstitute.cs 
Arg.Any<string>()
 
// shorthand: use `default` im combination with `WithAnyArgs` methods
// instead of the `Arg` syntax in (examples follow later)

Matches a specific value: It.Is<T>() => Arg.Is<T>()

 Moq.cs 
It.Is<string>(matcher => matcher == "foo")
It.Is<int>(matcher => matcher >= 10 && matcher <= 20)

 NSubstitute.cs 
Arg.Is<string>(matcher => matcher == "foo")
Arg.Is<string>("foo")
Arg.Is<int>(matcher => matcher >= 10 && matcher <= 20)
 
// shorthand: use `value` directly instead of the `Arg` syntax (examples follow later)

Matches a generic type: It.IsAnyType() => TBD

Moq's helpers It.IsAnyType, It.IsValueType, and It.IsSubtype<T> are currently not supported by NSubstitute. Keep an eye on this issue #634 for updates.

Testing method invocations: Verify() => Received()

Method without arguments

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Object.Method();
 
mock.Verify(x => x.Method());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.Method();
 
mock.Received().Method();

Method invoked with any arguments

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Object.MethodWithArgument("foo");
 
mock.Verify(x => x.MethodWithArgument(It.IsAny<string>()));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithArgument("foo");
 
mock.Received().MethodWithArgument(Arg.Any<string>());
 
// or use `ReceivedWithAnyArgs` in combination with `default` instead of the `Arg` syntax
mock.ReceivedWithAnyArgs().MethodWithArgument(default);

Method invoked with specific arguments

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Object.MethodWithArgument("foo");
 
mock.Verify(x => x.MethodWithArgument(It.Is<string>(match => match == "foo")));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithArgument("foo");
 
mock.Received().MethodWithArgument(Arg.Is<string>(match => match == "foo"));
 
// shorthand for the `Arg` syntax
mock.Received().MethodWithArgument(Arg.Is("foo"));
 
// or directly use the value instead of the `Arg` syntax
mock.Received().MethodWithArgument("foo");

Number of invocations: Times.Exactly(N) => Received(N)

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.MethodWithArgument("foo");
mock.MethodWithArgument("bar");
mock.MethodWithArgument("bar");
 
// is invoked
mock.Verify(x => x.MethodWithArgument(It.IsAny<string>()));
 
// is invoked exactly once
mock.Verify(x => x.MethodWithArgument(It.Is<string>(match =>  match == "foo")), Times.Once());
 
// is invoked exactly x times
mock.Verify(x => x.MethodWithArgument(It.Is<string>(match => match == "bar")), Times.Exactly(2));
 
// there are also other options like `Times.Between(N, N)`, `Times.AtMost(N)`, `Times.AtLeast(N)`
// these do not have a direct equivalent in NSubstitute

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithArgument("foo");
mock.MethodWithArgument("bar");
mock.MethodWithArgument("bar");
 
// is called
mock.ReceivedWithAnyArgs().MethodWithArgument(default);
 
// is called exactly once
mock.Received(1).MethodWithArgument(Arg.Is<string>(match => match == "foo"));
 
// is called x times
mock.Received(2).MethodWithArgument(Arg.Is<string>(match => match == "bar"));

Is not invoked: Times.Never() => DidNotReceive()

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Object.MethodWithArgument("foo");
 
mock.Verify(x => x.Method(), Times.Never());
mock.Verify(x => x.MethodWithArgument(It.Is<string>(match => match == "bar")), Times.Never());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithArgument("foo");
 
mock.DidNotReceiveWithAnyArgs().Method();
 
// with argument check
mock.DidNotReceive().MethodWithArgument(Arg.Is<string>(match => match == "bar"));
mock.DidNotReceive().MethodWithArgument(Arg.Is<string>("bar"));
 
// shorthand for the `Arg` syntax
mock.DidNotReceive().MethodWithArgument("bar");

Reset invocations: Reset() => ClearReceivedCalls()

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Object.Method();
 
mock.Verify(x => x.Method());
 
mock.Reset();
 
mock.Verify(x => x.Method(), Times.Never());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.Method();
 
mock.Received().Method();
 
mock.ClearReceivedCalls();
 
mock.DidNotReceive().Method();

Task invocation

 Moq.cs 
var mock = new Mock<IMyDependency>();
await mock.Object.MethodAsync();
 
mock.Verify(x => x.MethodAsync());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
await mock.MethodAsync();
 
// also works without `await` but results in a warning
await mock.Received().MethodAsync();

Setting the return value

Static return value: Setup().Returns() => Returns()

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Setup(m => m.MethodWithReturnValue()).Returns("output");
 
var result = mock.Object.MethodWithReturnValue();
Assert.That(result, Is.EqualTo("output"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithReturnValue().Returns("output");
 
var result = mock.MethodWithReturnValue();
Assert.That(result, Is.EqualTo("output"));

Return value based on input: method arguments => callInfo

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Setup(m => m.MethodWithReturnValue(It.IsAny<int>(), It.IsAny<string>()))
    .Returns((int input, string prefix) => $"{prefix}_{input}");
 
var result = mock.Object.MethodWithReturnValue(1, "prefix");
Assert.That(result, Is.EqualTo("prefix_1"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
// get the argument based on the type, and if needed include the index
mock.MethodWithReturnValue(Arg.Any<int>(), Arg.Any<string>())
    .Returns(callInfo => $"{callInfo.Arg<string>()}_{callInfo.ArgAt<int>(0)}");
 
// using `ReturnsForAnyArgs` in combination with `default` instead of the `Arg` syntax
mock.MethodWithReturnValue(default, default)
    .ReturnsForAnyArgs(callInfo => $"{callInfo.Arg<string>()}_{callInfo.ArgAt<int>(0)}");
 
var result = mock.MethodWithReturnValue(1, "prefix");
Assert.That(result, Is.EqualTo("prefix_1"));

Fine grained control over return value based on input

 Moq.cs 
 var mock = new Mock<IMyDependency>();
mock.Setup(m => m.MethodWithReturnValue(It.IsAny<int>(), It.IsAny<string>()))
    .Returns((int input, string prefix) => $"{prefix}_{input}");
mock.Setup(m => m.MethodWithReturnValue(It.Is<int>(i => i == 1), It.IsAny<string>()))
    .Returns((int input, string prefix) => $"special_{prefix}_{input}");
 
var result1 = mock.Object.MethodWithReturnValue(1, "prefix");
// matches the second setup, its return value is used
Assert.That(result1, Is.EqualTo("special_prefix_1"));
 
var result2 = mock.Object.MethodWithReturnValue(2, "prefix");
// doesn't match the second setup so it uses the return value of the first setup
Assert.That(result2, Is.EqualTo("prefix_2"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithReturnValue(Arg.Any<int>(), "prefix")
    .Returns(callInfo => $"{callInfo.Arg<string>()}_{callInfo.ArgAt<int>(0)}");
mock.MethodWithReturnValue(1, "prefix")
    .Returns(callInfo => $"special_{callInfo.Arg<string>()}_{callInfo.ArgAt<int>(0)}");
 
// fallback: ReturnsForAll is used to set the return value for all calls
// that don't have a specific setup (if the return type matches the generic)
mock.ReturnsForAll<string>("fallback");
 
// fallback: using the callInfo to create the return value
mock.ReturnsForAll<string>(callInfo => $"{callInfo.Arg<string>()}_{callInfo.Arg<int>()}");
 
// NOTE: the callbacks are invoked in the order they are defined
// the last return value is used as the return value of the method
// this can become problematic when using callbacks that have side effects (more on this later)
// as a workaround, use `Configure` to ensure previous callbacks do not run
// e.g. this is useful when previous callbacks throw exceptions
mock.Configure().MethodWithReturnValue(10, "prefix").Returns("prefix_10");
 
var result1 = mock.MethodWithReturnValue(1, "prefix");
// matches the second setup, its return value is used
Assert.That(result1, Is.EqualTo("special_prefix_1"));
 
var result2 = mock.MethodWithReturnValue(2, "prefix");
// doesn't match the second setup so it uses the return value of the first setup
Assert.That(result2, Is.EqualTo("prefix_2"));
 
var result3 = mock.MethodWithReturnValue(1, "other");
// doesn't match any setup, thus the fallback is used
Assert.That(result3, Is.EqualTo("other_1"));

Async (Task) return value: ReturnsAsync() => Returns()

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Setup(m => m.MethodWithReturnValueAsync(It.IsAny<long>()))
    .ReturnsAsync("output");
 
var result = await mock.Object.MethodWithReturnValueAsync(1);
 
Assert.That(result, Is.EqualTo("output"));
mock.Verify(x => x.MethodWithReturnValueAsync(It.IsAny<long>()), Times.Once());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithReturnValueAsync(default)
    .ReturnsForAnyArgs("output");
 
var result = await mock.MethodWithReturnValueAsync(1);
 
Assert.That(result, Is.EqualTo("output"));
await mock.ReceivedWithAnyArgs(1).MethodWithReturnValueAsync(default);

Multiple return values: SetupSequence().Returns() => Returns()

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.SetupSequence(m => m.MethodWithReturnValue(It.IsAny<int>()))
    .Returns("one")
    .Returns("two");
 
var result1 = mock.Object.MethodWithReturnValue(1);
var result2 = mock.Object.MethodWithReturnValue(2);
var result3 = mock.Object.MethodWithReturnValue(3);
 
Assert.That(result1, Is.EqualTo("one"));
Assert.That(result2, Is.EqualTo("two"));
Assert.That(result3, Is.Null);

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.MethodWithReturnValue(default)
    .ReturnsForAnyArgs("one", "two");
 
var result1 = mock.MethodWithReturnValue(1);
var result2 = mock.MethodWithReturnValue(2);
var result3 = mock.MethodWithReturnValue(3);
 
Assert.That(result1, Is.EqualTo("one"));
Assert.That(result2, Is.EqualTo("two"));
// 👇 different from Moq, NSubstitute will return the last value for all subsequent calls
Assert.That(result3, Is.EqualTo("two"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
// also supports multiple return values based on the input
mock.MethodWithReturnValue(default)
    .ReturnsForAnyArgs(callInfo => callInfo.Arg<int>().ToString(), callInfo => callInfo.Arg<int>().ToString());
 
var result1 = mock.MethodWithReturnValue(1);
var result2 = mock.MethodWithReturnValue(2);
var result3 = mock.MethodWithReturnValue(3);
 
Assert.That(result1, Is.EqualTo("1"));
Assert.That(result2, Is.EqualTo("2"));
Assert.That(result3, Is.EqualTo("3"));

Callbacks: Callback() => AndDoes()

 Moq.cs 
var mock = new Mock<IMyDependency>();
var result = "";
mock.Setup(m => m.MethodWithReturnValue(It.IsAny<int>()))
    .Returns("output")
    .Callback((int x) =>
    {
        result = $"callback {x}";
    });
 
mock.Object.MethodWithReturnValue(1);
 
Assert.That(result, Is.EqualTo("callback 1"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
var result = "";
mock
    .MethodWithReturnValue(default)
    .ReturnsForAnyArgs("output")
    .AndDoes(callInfo =>
    {
        result = $"callback {callInfo.Arg<int>()}";
    });
 
mock.MethodWithReturnValue(1);
 
Assert.That(result, Is.EqualTo("callback 1"));

Callback for void methods (or methods without a defined result): Callback() => When().Do()

 Moq.cs 
var mock = new Mock<IMyDependency>();
var result = "";
mock.Setup(m => m.MethodWithReturnValue(It.IsAny<int>()))
    .Callback((int x) =>
    {
        result = $"callback {x}";
    });
 
mock.Object.MethodWithReturnValue(1);
 
Assert.That(result, Is.EqualTo("callback 1"));

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
var result = "";
mock
    .WhenForAnyArgs(m => m.MethodWithReturnValue(default))
    .Do(callInfo =>
    {
        result = $"callback {callInfo.Arg<int>()}";
    });
 
mock.MethodWithReturnValue(1);
 
Assert.That(result, Is.EqualTo("callback 1"));

Throwing Exceptions: Throws() => When().Do(() => throw)

 Moq.cs 
var mock = new Mock<IMyDependency>();
mock.Setup(m => m.Method())
    .Throws(new InvalidOperationException());
 
Assert.Throws<InvalidOperationException>(() => mock.Object.Method());

 NSubstitute.cs 
var mock = Substitute.For<IMyDependency>();
mock.When(w => w.Method())
    .Do((callInfo) => throw new InvalidOperationException());
 
Assert.Throws<InvalidOperationException>(() => mock.Method());

Automate Migration

Because both syntaxes resemble each other, it is possible to use a couple of smart find and (RegExp) replace commands to help with the migration. These are not perfect, but they can be an enoourmous boost to get you started, and migrate 80% of your codebase in a matter of minutes.

Here are a few that I used. Before using them, make sure that you're working on a clean branch.

I based mine implementation of these expression on the following resources:

• https://github.com/AlbertoMonteiro/moq-to-nsubstitute
• https://github.com/moq/moq/issues/1374#issuecomment-1671241122

Conclusion

In this cheat sheet, we've seen the syntax differences between Moq and NSubstitute, more specifically how to convert Moq code to NSubstitute code. We've also touched on how to automate the migration of your codebase.

What I like about NSubstitute is that it's a lot more lightweight than Moq, and it doesn't require a lot of wrapping to mock interfaces. This makes the syntax more compact and easier to read.

For more information on NSubstitute, take a look at the NSubstitute documentation.

Feel free to update this blog post on GitHub, thanks in advance!

Support me

I appreciate it if you would support me if have you enjoyed this post and found it useful, thank you in advance.

Share this post