A friendly substitute for .NET mocking libraries.
Alternatives To Nsubstitute
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Testify20,99714,68877,23321 hours ago42May 30, 2023411mitGo
A toolkit with common assertions and mocks that plays nicely with the standard library
Mockito14,32838,95014,25914 hours ago346November 02, 2023367mitJava
Most popular Mocking framework for unit tests written in Java
Msw13,8242,1906 hours ago200November 24, 202385mitTypeScript
Seamless REST/GraphQL API mocking library for browser and Node.js.
Mockery10,505112,37918,4114 days ago41August 06, 2023106bsd-3-clausePHP
Mockery is a simple yet flexible PHP mock object framework for use in unit testing with PHPUnit, PHPSpec or any other testing framework. Its core goal is to offer a test double framework with a succinct API capable of clearly defining all possible object operations and interactions using a human readable Domain Specific Language (DSL).
Mock9,0574,53310,3264 months ago55May 12, 202285apache-2.0Go
GoMock is a mocking framework for the Go programming language.
Go Sqlmock5,5231,435a month ago21June 28, 202076otherGo
Sql mock driver for golang to test database interactions
Mockoon5,522812 hours ago48October 30, 202368otherTypeScript
Mockoon is the easiest and quickest way to run mock APIs locally. No remote deployment, no account required, open source.
Mockery5,2143147 days ago151November 21, 202333bsd-3-clauseGo
A mock code autogenerator for Go
7 days ago257apache-2.0Kotlin
mocking library for Kotlin
1,238a month ago60December 02, 202054mitObjective-C
Stub your network requests easily! Test your apps with fake network data and custom response time, response code and headers!
Alternatives To Nsubstitute
Select To Compare

Alternative Project Comparisons


Build status Nuget

Visit the NSubstitute website for more information.

What is it?

NSubstitute is designed as a friendly substitute for .NET mocking libraries.

It is an attempt to satisfy our craving for a mocking library with a succinct syntax that helps us keep the focus on the intention of our tests, rather than on the configuration of our test doubles. We've tried to make the most frequently required operations obvious and easy to use, keeping less usual scenarios discoverable and accessible, and all the while maintaining as much natural language as possible.

Perfect for those new to testing, and for others who would just like to to get their tests written with less noise and fewer lambdas.


Getting help

If you have questions, feature requests or feedback on NSubstitute please raise an issue on our project site. All questions are welcome via our project site, but for "how-to"-style questions you can also try StackOverflow with the [nsubstitute] tag, which often leads to very good answers from the larger programming community. StackOverflow is especially useful if your question also relates to other libraries that our team may not be as familiar with (e.g. NSubstitute with Entity Framework). You can also head on over to the NSubstitute discussion group if you prefer.

Basic use

Let's say we have a basic calculator interface:

public interface ICalculator
    int Add(int a, int b);
    string Mode { get; set; }
    event Action PoweringUp;

We can ask NSubstitute to create a substitute instance for this type. We could ask for a stub, mock, fake, spy, test double etc., but why bother when we just want to substitute an instance we have some control over?

_calculator = Substitute.For<ICalculator>();

Note: NSubstitute will only work properly with interfaces or with virtual members of classes. Be careful substituting for classes with non-virtual members. See Creating a substitute for more information.

Now we can tell our substitute to return a value for a call:

_calculator.Add(1, 2).Returns(3);
Assert.That(_calculator.Add(1, 2), Is.EqualTo(3));

We can check that our substitute received a call, and did not receive others:

_calculator.Add(1, 2);
_calculator.Received().Add(1, 2);
_calculator.DidNotReceive().Add(5, 7);

If our Received() assertion fails, NSubstitute tries to give us some help as to what the problem might be:

NSubstitute.Exceptions.ReceivedCallsException : Expected to receive a call matching:
    Add(1, 2)
Actually received no matching calls.
Received 2 non-matching calls (non-matching arguments indicated with '*' characters):
    Add(1, *5*)
    Add(*4*, *7*)

We can also work with properties using the Returns syntax we use for methods, or just stick with plain old property setters (for read/write properties):

Assert.That(_calculator.Mode, Is.EqualTo("DEC"));

_calculator.Mode = "HEX";
Assert.That(_calculator.Mode, Is.EqualTo("HEX"));

NSubstitute supports argument matching for setting return values and asserting a call was received:

_calculator.Add(10, -5);
_calculator.Received().Add(10, Arg.Any<int>());
_calculator.Received().Add(10, Arg.Is<int>(x => x < 0));

We can use argument matching as well as passing a function to Returns() to get some more behaviour out of our substitute (possibly too much, but that's your call):

   .Add(Arg.Any<int>(), Arg.Any<int>())
   .Returns(x => (int)x[0] + (int)x[1]);
Assert.That(_calculator.Add(5, 10), Is.EqualTo(15));

Returns() can also be called with multiple arguments to set up a sequence of return values.

_calculator.Mode.Returns("HEX", "DEC", "BIN");
Assert.That(_calculator.Mode, Is.EqualTo("HEX"));
Assert.That(_calculator.Mode, Is.EqualTo("DEC"));
Assert.That(_calculator.Mode, Is.EqualTo("BIN"));

Finally, we can raise events on our substitutes (unfortunately C# dramatically restricts the extent to which this syntax can be cleaned up):

bool eventWasRaised = false;
_calculator.PoweringUp += () => eventWasRaised = true;

_calculator.PoweringUp += Raise.Event<Action>();


NSubstitute and its tests can be compiled and run using Visual Studio and Visual Studio for Mac. Note that some tests are marked [Pending] and are not meant to pass at present, so it is a good idea to exclude tests in the Pending category from test runs.

There are also build scripts in the ./build directory for command line builds, and CI configurations in the project root.

To do full builds you'll also need Ruby, as the jekyll gem is used to generate the website.

Other libraries you may be interested in

  • Moq: the original Arrange-Act-Assert mocking library for .NET, and a big source of inspiration for NSubstitute.
  • FakeItEasy: another modern mocking library for .NET. If you're not sold on NSubstitute's syntax, try FIE!
  • substitute.js: a mocking library for TypeScript inspired by NSubstitute's syntax (@fluffy-spoon/substitute on NPM)
Popular Mocking Projects
Popular Mock Projects
Popular Software Quality Categories

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
C Sharp
Testing Tools