A Guide to NSubstitute for Rhino.Mocks Users

I’ve been a big fan of Rhino.Mocks for many years, but the original Rhino.Mocks maintainer (Oren Eini aka Ayende) stated in 2013 that he is no longer maintaining the project and has handed the project over to a new maintainer (Mike Meisinger), but Mike has not been actively maintaining the project. It’s effectively dead and very unlikely to support future versions of .NET, including .NET core.

A while back I wrote a Quick Guide to Using Rhino.Mocks and in last week’s post, I gave an overview of Moq for Rhino.Mocks Users. While Moq seems to be the current front runner as a Rhino.Mocks replacement, there’s another player in town with NSubstitute. So in the same vane as my Moq post, I’m providing a guide to help people make the transition (or at least help with a review) from Rhino.Mocks to NSubstitue.

The format of this post will follow that of the others to help with cross-referencing between them.

Overall, I’m not a big fan of NSubstitute’s syntax, as it looks too similar to just calls to the methods themselves, which:

  • makes it harder to understand, as the reader must know which calls are setting up stubs and which are real calls.
  • makes it much more likely you’ll accidentally do the wrong thing and call a real method.

Now, if you’re only mocking interfaces, then this wouldn’t be an issue — but rarely do I find a codebase that allows everything to be an interface.

Generating Different Mock Types

By default, NSubstitue’s .For<T> method generates something close to a Dynamic mock — that is, if you don’t explicitly provide a return value, it will return the default value for the data type of the return value if it’s a value type (0 for numbers, false for bools, empty string for string), but for object types, it’s a bit more complicated. From their documentation:

…any properties or methods that return an interface, delegate, or purely virtual class* will automatically return substitutes themselves.

A pure virtual class is defined as one with all its public methods and properties defined as virtual or abstract and with a default, parameterless constructor defined as public or protected.

So it won’t return null in those cases. Instead, it creates a new mock of the return type. Otherwise, it will return null.

Be careful, thought — if you are using a real class (not an interface), it will call the underlying methods if they aren’t virtual.

That said, there is the concept of a partial mock using .ForPartsOf<T> — that is, a mock that can use the underlying object’s implementation. However, to prevent calling the real methods for the methods you do want to mock, you must use the syntax described in the Advanced Argument Constraints section below.

Rhino.Mocks NSubstitute
Dynamic-ish Mock IFoo mock = MockRepository.GenerateMock<IFoo>(); IFoo substitute = Substitute.For<IFoo>();
Partial Mock IFoo mock = MockRepository.GeneratePartialMock<IFoo>(); IFoo substitute = Substitue.ForPartsOf<IFoo>();

There isn’t an option to create a Strict mock in NSubstitute, and it looks like there won’t ever be one.

Passing Constructor Arguments

If you need to pass arguments to the constructor of the class you’re trying to mock, there are overloads to allow you to do that.

Rhino.Mocks NSubstitute
IFoo mock = MockRepository.GenerateMock<SomeClass>(param1, param2); Substitue.ForPartsOf<SomeClass>()(param1, param2);

Stubs vs Mocks (or not)

The syntax for NSubstitute is a little different than the others. In most cases, there’s not an explicit method you call to create the mock/stub — rather, you basically call the method you want to create a substitue for. Also, there’s no distinction between a mock and a stub — they’re all just substitutions. But since they don’t create expectations, I would classify them as stubs.

You use the .Returns() method to setup the stub. Note that you can provide multiple values to .Returns() which will set up a chain of calls, like this: .Returns(valueForFirstCall, valueForSecondCall, valueForThirdCall). This works for methods and properties.

For Methods:

Rhino.Mocks NSubstitute
Stub mock.Stub(x => x.SomeMethod()).Return(true); substitute.SomeMethod().Returns(true);
Mock mock.Expect(x => x.SomeMethod()).Return(true); (not supported)

For Properties:

Rhino.Mocks NSubstitute
Stub mock.Stub(x => x.SomeProperty).Return(true); substitute.SomeProperty.Returns(true);
or
substitute.SomeProperty = true;
Mock mock.Expect(x => x.SomeProperty).Return(true); (not supported)

Unlike Rhino.Mocks, however, if some other code sets the property value to something else, NSubstitute’s stub will return the new value, not the value you stipulated in your stub. In other words, NSubstitue’s properties will act like regular properties, and your stub just sets an initial value.

Verifying expectations

Since you’re not creating expectations with NSubstitute, there are no mass validation options. Instead, you need to check each stub (which, being more explicit, is probably the better route anyway).

For Methods:

Rhino.Mocks NSubstitute
Called mock.AssertWasCalled(x => x.SomeMethod()); substitute.Received().SomeMethod();
Called a specific number of times mock.AssertWasCalled(x => x.SomeMethod(), options => options.Repeat.Times(2) ); substitute.Received(2).SomeMethod();
Not called mock.AssertWasNotCalled(x => x.SomeMethod()); substitute.DidNotReceive().SomeMethod();
or
substitute.DidNotReceiveWithAnyArgs().SomeMethod();

For Properties:

Rhino.Mocks NSubstitute
Get mock.AssertWasCalled(x => x.SomeProperty); var temp = substitue.Received().SomeProperty;
Set mock.AssertWasCalled(x => x.SomeProperty = true); substitue.Received().SomeProperty = true;
Not called mock.AssertWasNotCalled(x => x.SomeProperty = true); substitue.DidNotReceive().SomeProperty = true;
or
substitue.DidNotReceiveWithAnyArgs().SomeProperty = true;

Note that for the getter, you must set a variable to the return value to prevent a compiler error.

The WithAnyArgs versions will ignore whatever parameters (for methods) or set values (for properties) you use in your check and will verify against any inputs.

Advanced Argument Constraints

Both frameworks provide ways to put advanced constraints on the arguments that trigger a mock. Below are examples — you’ll need to consult the framework documentation for the full list of available constraints.

Rhino.Mocks

 mock.Stub(dao => dao.GetRecordFromDatabase(
                         Arg<int>.Is.GreaterThanOrEqual(0),
                         Arg<decimal>.Is.NotEqual(2.0),
                         Arg<List<string>>.List.ContainsAll(new List<string> { "foo", "bar" }),
                         Arg<object>.Is.NotNull,
                         Arg<object>.Is.Anything))
                 .Return(recordFromDatabase);

NSubstitute

  substitute.GetRecordFromDatabase(
                         Arg.Is<int>(i => i >= 0),
                         Arg.Is<decimal>(d => d != 2.0m),
                         Arg.Do<int>(x => capturedValue = x ),
                         Arg.Any<object>()))
         .Returns(recordFromDatabase);

Or, to ignore the arguments altogether, use .ReturnsForAnyArgs(). This is similar to Rhino.Mocks’ .IgnoreArguments() method.

Providing a Method Implementation / Using the Input Params

For Rhino.Mocks, in order to provide an alternate implementation, you use the .Do() method to provide a delegate. In NSubstitue, you provide a delegate to the .Returns() call.

Rhino.Mocks

  mock.Stub(dao => dao.GetRecordFromDatabase(0))
                .IgnoreArguments()
                .Repeat.Any()
                .Do((Func<int, ImportantData>)(input => new ImportantData
                {
                    Name = "Orignal Name",
                    RecordId = input
                }));

NSubstitute


substitute.GetRecordFromDatabase(0) .ReturnsForAnyArgs(input => new ImportantData { Name = "Orignal Name", RecordId = input.ArgAt<int>(0) });

Throwing an Exception Instead

If the return type of the method is not void, you just provide a delegate to .Returns() that throws an exception. However, if the return type is void, then you use a .When().Do() syntax instead:

Rhino.Mocks NSubstitute
mock.Stub(x => x.SomeMethod()).Throw(new Exception("POW!")); substitute.SomeMethod().Returns(x => { throw new Exception("POW!"); });
or
substitute.When(x => x.VoidMethod()).Do(x => { throw new Exception("POW!"); });

Testing Non-Public Members

With Rhino.Mocks, you can’t mock private or internal members, but you can mock internal members if you add an InternalsVisibleTo attribute for the Castle dynamic proxy assembly. NSubstitute also uses the same proxy, so you’ll still need to add the attribute. See the Moq Quickstart Guide for details on how to do this.

A Guide to Moq for Rhino.Mocks Users

I’ve been a big fan of Rhino.Mocks for many years, but the original Rhino.Mocks maintainer (Oren Eini aka Ayende) stated in 2013 that he is no longer maintaining the project and has handed the project over to a new maintainer (Mike Meisinger), but Mike has not been actively maintaining the project. It’s effectively dead and very unlikely to support future versions of .NET, including .NET core.

Moq (pronounced “Mock”) has become the de facto replacement.

This post hopes to serve as a guide for people making the transition from Rhino.Mocks to Moq.

One big difference between Rhino.Mocks and Moq is what gets returned when you generate the mock and how you operate against it. With Rhino.Mocks, the MockRepository returns to you an instance of the type you’re mocking and you apply the mock operators (.Stub(), .Expect(), .VerifyAllExpectations(), etc) directly to that mocked object. Moq, on the other hand, creates a wrapper object that contains a reference to the
mocked type.

So in this example, I’m creating an mock of IFoo. For Rhino.Mocks, I get back an IFoo object, but Moq returns a Mock<IFoo> and to get the IFoo object, you access it with the .Object property.

Rhino.Mocks Moq
IFoo mock = MockRepository.GenerateMock<IFoo>(); Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>();
IFoo mockedObject = mockWrapper.Object;

When using Moq, if you have a reference to the mocked object, you can get back to the wrapper object with this helper method: Mock<IFoo> mockWrapper = Mock.Get(mockedObject);

Generating Different Mock Types

For those of you that read my Using Rhino.Mocks Quick Guide, you may recall there are three types of mocks that can be generated by Rhino.Mocks:

Strict Mock
A strict mock requires you to provide alternate implementations for each method/property that is used on the mock. If any methods/properties are used which you have not provided implementations for, an exception will be thrown.
Dynamic Mock
With a dynamic mock, any methods/properties which are called by your tests for which you have not provided an implementation will return the default value for the data type of the return value.  In other words, you’ll get back a 0 for number types, false for Booleans and a null for any object types.
Partial Mock
A partial mock will use the underlying object’s implementation if you don’t provide an alternate implementation.  So if you’re only wanting to replace some of the functionality (or properties), and keep the rest, you’ll want to use this.  For example, if you only want to override the method IsDatabaseActive(), and leave the rest of the class as-is, you’ll want to use a partial mock and only provide an alternate implementation for IsDatabaseActive().

Note that Moq uses the term “Loose Mock” for the Dynamic mock concept. Both frameworks default to Dynamic\Loose mocks.

Here’s how you generate the same concepts in Moq:

Mock Type Rhino.Mocks Moq
Strict Mock IFoo mock = MockRepository.GenerateStrictMock<IFoo>(); Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>(MockBehavior.Strict);
Dynamic\Loose Mock IFoo mock = MockRepository.GenerateMock<IFoo>(); Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>();
or
Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>(MockBehavior.Loose);
Partial Mock IFoo mock = MockRepository.GeneratePartialMock<IFoo>(); Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>() { CallBase = true };

I’m not a fan of this syntax, because it lets you mix methods in ways that don’t make sense, like a strict mock that calls it’s base methods: Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>(MockBehavior.Strict) { CallBase = true };. It’s not clear what will happen in this scenario if I call a method I haven’t explicitly mocked, because using two different inputs (a constructor argument and a property) to represent competing concepts leads to confusion. That said, I can tell you what happens: The Strict setting takes precedent and a runtime exception is thrown:

Moq.MockException : Class1.GetFoo() invocation failed with mock behavior Strict.
All invocations on the mock must have a corresponding setup.

Passing Constructor Arguments

If you need to pass arguments to the constructor of the class you’re trying to mock, there are overloads to allow you to do that.

Rhino.Mocks Moq
IFoo mock = MockRepository.GenerateMock<IFoo>(param1, param2); Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>(param1, param2);
or
Mock<IFoo> mockWrapper = new Moq.Mock<IFoo>(MockBehavior.Strict, param1, param2);

Stubs vs Mocks

Again, from my Using Rhino.Mocks Quick Guide, you may recall that:

A stub is simply an alternate implementation. A mock, however, is more than that. A mock sets up an expectation that

  • A specific method will be called
  • It will be called with the provided inputs
  • It will return the provided results

In Rhino.Mocks, you used the .Stub() and .Expect() extension methods to generate your stubs and mocks directly off your mock object. Moq, on the other hand, uses the .Setup() method on the wrapper object to create both. By default, it will create a stub (no expectation), but if you add Verifiable(), it will generate the expectations (thus, becoming a mock).

For both frameworks, you can explicitly verify stubs, but if you want to do mass verification, you must create the expectations up front.

For Methods:

Rhino.Mocks Moq
Stub mock.Stub(x => x.SomeMethod()).Return(true); mockWrapper.Setup(x => x.SomeMethod()).Returns(true);
Mock mock.Expect(x => x.SomeMethod()).Return(true); mockWrapper.Setup(x => x.SomeMethod()).Returns(true).Verifiable();

Properties are a different story. In Moq, in addition to Mocks that carry expectations, you can generate stubs for properties that basically allow the properties to be set and have them return the values when the getter is called. You can do this for individual properties (and optionally provide an initial value) or you can do it for all properties with a single call using .SetupAllProperties().

Rhino.Mocks, on the other hand, doesn’t provide the ability to track property values, so to get that same functionality, you’d need to use a callback (.Do() or .Callback()) and track the value yourself.

For Properties:

Rhino.Mocks Moq
Stub
(always return same value)
mock.Stub(x => x.SomeProperty).Return(true); mock.Setup(foo => foo.SomeProperty).Returns("bar");
Stub
(returns tracked value)
(must use a callback) mock.SetupProperty(f => f.SomeProperty);
Stub w/ initial value
(returns tracked value)
(must use a callback) mock.SetupProperty(f => f.SomeProperty, "bar");
Mock
(always return same value, create expectation)
mock.Expect(x => x.SomeProperty).Return(true); mock.SetupSet(foo => foo.SomePropertyName).Returns("bar");
mock.SetupGet(foo => foo.SomeProperty)

Verifying expectations

The concepts here are pretty similar. You can verify individual call patterns, or (if you created a Mock and not a Stub) you can verify all of the expectations you created in a single pass.

For Methods:

Rhino.Mocks Moq
Called mock.AssertWasCalled(x => x.SomeMethod()); mockWrapper.Verify(x => x.SomeMethod());
Called a specific number of times mock.AssertWasCalled(x => x.SomeMethod(), options => options.Repeat.Times(2) ); mockWrapper.Verify(x => x.SomeMethod(), Times.Exactly(2));
Not called mock.AssertWasNotCalled(x => x.SomeMethod()); mockWrapper.Verify(x => x.SomeMethod(), Times.Never);

For Properties

Rhino.Mocks Moq
Get mock.AssertWasCalled(x => x.SomeProperty); mockWrapper.VerifyGet(x => x.SomeProperty);
Set mock.AssertWasCalled(x => x.SomeProperty = true); mockWrapper.VerifySet(x => x.SomeProperty);
Not called mock.AssertWasNotCalled(x => x.SomeProperty = true); mockWrapper.VerifySet(x => { x.SomeProperty = true; }, Times.Never);

Mass Verification

Moq can do mass verification in two ways. If you have created a mock that sets up expectations using .Expect() in Rhino.Mocks or .Verifiable() in Moq, you can use Moq’s .Verify() method to validate just those expectations. Moq also provides a .VerifyAll() method which will validate all of the mocks and stubs you’ve created with .Setup().

Rhino.Mocks Moq
Verify Mocks only mock.VerifyAllExpectations(); mockWrapper.Verify();
Verify Mocks and Stubs (not available) mockWrapper.VerifyAll();

Controlling Mock Behaviors

Here are some of the general behavior modifications in Rhino.Mocks and their Moq equivalents:

Rhino.Mocks Moq
Change how many times to use the mock use .Repeat():

mock.Expect(x => x.SomeProperty)
.Repeat.Times(2)
.Return(true);

use .SetupSequence():

mockWrapper.SetupSequence(x => x.SomeMethod())
.Returns(true)
.Returns(true)
.Throws( new Exception("Called too many times"));

Ignore arguments use .IgnoreArguments():

mock.Expect(x => x.SomeMethod("param"))
.IgnoreArguments()
.Return(true);

use argument constraints:

mockWrapper.Setup(x => x.SomeMethod(It.IsAny<string>()))
.Returns(true);

Advanced Argument Constraints

Both frameworks provide ways to put advanced constraints on the arguments that trigger a mock. Below are examples — you’ll need to consult the framework documentation for the full list of available constraints.

Rhino.Mocks

 mock.Stub(dao => dao.GetRecordFromDatabase(
                         Arg<int>.Is.GreaterThanOrEqual(0),
                         Arg<decimal>.Is.NotEqual(2.0),
                         Arg<List<string>>.List.ContainsAll(new List<string> { "foo", "bar" }),
                         Arg<object>.Is.NotNull,
                         Arg<object>.Is.Anything))
                 .Return(recordFromDatabase);

Moq

 mockWrapper.Setup(dao => dao.GetRecordFromDatabase(
                         It.Is<int>(i => i >= 0),
                         It.Is<decimal>(d => d != 2.0m),
                         It.IsRegex("[a-d]+"),
                         It.IsNotNull<object>(),
                         It.IsAny<object>()))
         .Return(recordFromDatabase);

Providing a Method Implementation / Using the Input Params

For Rhino.Mocks, in order to provide an alternate implementation, you use the .Do() method to provide a delegate. In Moq, the .Returns() method has an overload that lets you provide a delegate.

Rhino.Mocks

  mock.Stub(dao => dao.GetRecordFromDatabase(0))
                .IgnoreArguments()
                .Repeat.Any()
                .Do((Func<int, ImportantData>)(input => new ImportantData
                {
                    Name = "Orignal Name",
                    RecordId = input
                }));

Moq


mockWrapper.Setup(dao => dao.GetRecordFromDatabase(It.IsAny<int>())) .Returns((Func<int, ImportantData>)(input => new ImportantData { Name = "Orignal Name", RecordId = input }));

Throwing an Exception Instead

This is pretty much a drop-in replacement when creating the mock/stub. Where Rhino.Mocks uses .Throw() for this purpose, Moq uses .Throws();

Testing Non-Public Members

With Rhino.Mocks, you can’t mock private or protected members, but you can mock internal members if you add an InternalsVisibleTo attribute for the Castle dynamic proxy assembly. Moq also uses the same proxy, so you’ll still need to add the attribute, but Moq has the added benefit of being able to mock protected members. See the Moq Quickstart Guide for details on how to do this.

GaragePi: Experimenting with languages

In my previous posts, (Garage Pi – My Raspberry Pi Playground, GaragePi v2: Temperature and Light, and GaragePi v3: Data Persistence and Visualization and Other Small Improvements) I described the Raspberry Pi-based system I had setup in my garage to detect when the garage door was left open or the light was left on and turn on an LED inside the house. It also reads the current temperature in the garage. This was all originally written in Python (with a node.js-based website added in the third post), but I wanted to play around with other languages on the Pi, so I followed it up with a port to JavaScript and .Net (using Mono).

I’m not going to go into too much detail in this post, because (as I hope to write up a post here shortly), I’ve since abandoned the RaspPi platform for this project and converted it over to an Arduino-based solution.

Some general notes:

In both cases, I tried to keep the layout of the code similar to the Python layout to provide better side-by-side comparisons of the codebase. In some cases, this may result in code that doesn’t match the languages’ general styling.

The hardware didn’t change for these — just the software. I also didn’t change the website or MongoDB, which let me switch back and forth between languages and compare results using the same db and website. (I added a “source language” field to the db records to help call out any oddness.)

All of this was done about a year ago (Feb 2015) — I’m just lazy and never got around to writing it up.

.NET/Mono Implementation

The .NET implementation, using Mono, was extremely straightforward. Now, in all fairness, this is the language I spend all day writing at my day job, so it’s clearly the one I’m most familiar with, but this is running on Linux and interacting with the hardware — this is supposed to be hard!

I used the “raspberry-sharp-io” library to interact with the GPIO pins. I had to add RaspPi 2 pin support and wrote a driver for the 1-wire temp sensor, both of which have since been merged to the main repository (open source pull requests for the win!). I also used a NuGet package for the MongoDB client.

If you’re thinking about going this route, this may not be a good guide. Since the time that I wrote this code, Microsoft has shifted .NET in major ways, including (pre-release) support for the next version of the framework to run natively on Linux. Additionally, Windows10 IoT edition will run natively on the RaspPi, so you could do this without Linux. At the time I went through this excersize, there wasn’t good GPIO/1-wire support in the Win10 IoT releases — that’s likely changed.

I initial expected the performance of running in .NET/Mono to be bad. While I’ve lost the raw numbers I collected, the performance generally was very good, both for CPU and memory utilization

You can find my code on GaragePi GitHub repo in the “dotNet” folder: https://github.com/johnmwright/GaragePi

JavaScript Implementation

Wow — this did not go well. Since several of my sensors rely on precise timing (the Ultrasonic Range Finder in particular), it did not fit well with the JavaScript callback model. I ended up using the r-pi-usonic npm module which is a Node module written in C so that it can better handle the timing. Note: the r-pi-usonic project is no longer maintained..

I also used the rpi-gpio npm module for GPIO pin interactions. For some reason, I had to pull it from a personal clone of the GitHub repo instead of from the npm website, though I don’t recall why. I think the version on npm was very stale at the time.

Ultimately, this solution never fully worked for me. It would periodically just die and I never got all the kinks worked it. It also took me significantly more time (like 2 orders of magnitude or more) to implement than Python and .NET combined!

I also investigated projects like Cylon.js, but ended up going deep into a rabbit hole only to hit a major roadblock. Again, this was a year ago, which in JS terms is lifetimes, so your millage may vary.

A big thanks to Clark Sell, Brett Slaski and Brandon Martinez, who worked through some of the uglier JavaScript bits with me. These guys are all on the That Conference Staff and we have a #microcontrollers Slack channel! You should consider going to That Conference is you’re reading my post and live anywhere near the US Midwest!

You can find my code on GaragePi GitHub repo in the “JavaScript” folder: https://github.com/johnmwright/GaragePi