\/\/ Packages:\nInstall-Package NSubstitute\nInstall-Package NUnit\n\n\/\/ Interface:\ninterface ICalculator\n{\n int Add(int a, int b);\n int Divide(int n, int divisor, out float remainder);\n string Mode { get; set; }\n void SetMode(string mode);\n}\n<\/code><\/pre>\nCreating a substitute<\/h1>\n\/\/ For an interface\nICalculator nsub = Substitute.For<ICalculator>();\n\n\/\/ For a class\nCalculator nsub = Substitute.For<Calculator>(ctorArg1, ctorArg2);\n<\/code><\/pre>\nWhen substituting a class, only virtual\/abstract members can be mocked.
There are generic overloads for up to three different types. When providing multiple types, max one class can be used. For more than three:<\/p>\n
var sub = Substitute.For(\n new[] { typeof(IComparable), typeof(IDisposable), typeof(ICloneable), typeof(Calculator) },\n new object[] { \/* ctor arguments for Calculator *\/ }\n);\nAssert.IsInstanceOf<IDisposable>(sub);\nAssert.IsInstanceOf<Calculator>(sub);\n<\/code><\/pre>\nMatching arguments<\/h1>\n\/\/ Arg.Any and fixed value\nnsub.Add(Arg.Any<int>(), 5).Returns(10);\nAssert.That(nsub.Add(999, 5), Is.EqualTo(10));\n\n\/\/ Arg.Is: Fixed value and Predicate\nnsub.Add(Arg.Is(1), Arg.Is<int>(x => x < 0)).Returns(5);\nAssert.That(nsub.Add(1, -2), Is.EqualTo(5));\n\n\/\/ First matcher still applies\nAssert.That(nsub.Add(998, 5), Is.EqualTo(10));\n\n\/\/ ReturnsForAnyArgs overwrites everything\nnsub.Add(0, 0).ReturnsForAnyArgs(100);\nAssert.That(nsub.Add(1, -2), Is.EqualTo(100));\n<\/code><\/pre>\nVerification<\/h1>\n
Did receive calls:<\/strong><\/p>\n\/\/ Methods\nnsub.Add(0, 1);\nnsub.Received().Add(0, 1);\nnsub.ReceivedWithAnyArgs().Add(0, 0);\n\n\/\/ Property Getter\nstring call = nsub.Mode;\nstring result = nsub.Received().Mode;\n\n\/\/ Property Setter\nnsub.Mode = \"BIN\";\nnsub.Received().Mode = \"BIN\";\n\n\/\/ Reset calls\nnsub.ClearReceivedCalls();\n\n\/\/ Verify with predicate\nnsub.Add(0, 1);\nnsub.Add(0, 2);\nnsub.Add(0, 3);\nnsub.Received(2).Add(Arg.Is(0), Arg.Is<int>(x => x <= 2));\n\/\/ In this case the Arg.Is(0) is required by NSubstitute\n\/\/ (providing 0 directly results in an AmbiguousArgumentsException)\n<\/code><\/pre>\nDid not receive calls:<\/strong><\/p>\nnsub.DidNotReceive().Add(Arg.Any<int>(), 9);\n\n\/\/ The actual arguments to Add are simply ignored with DidNotReceiveWithAnyArgs\nnsub.DidNotReceiveWithAnyArgs().Add(0, 0);\n<\/code><\/pre>\nProviding values<\/h1>\n
Without setup the following is returned:<\/p>\n
\n- For primitives:
default(int)<\/code><\/li>\n- For strings:
string.Empty<\/code><\/li>\n- For IEnumerables:
Enumerable.Empty<T>()<\/code><\/li>\n- For interfaces: a
Substitute.For<T>()<\/code>, the same reference when called with the same arguments<\/li>\n<\/ul>\nWhen substituting a class, non-virtual methods returning an interface cannot be mocked and will return null<\/code>.<\/p>\nMethods and properties<\/h2>\n\/\/ Methods\nnsub.Add(1, 3).Returns(4);\nAssert.That(nsub.Add(1, 3), Is.EqualTo(4));\nAssert.That(nsub.Add(1, 3), Is.EqualTo(4));\n\n\/\/ Properties\nnsub.Mode = \"HEX\";\nAssert.That(nsub.Mode, Is.EqualTo(\"HEX\"));\n\n\/\/ Can also use the same syntax as for methods:\nnsub.Mode.Returns(\"DEC\");\nAssert.That(nsub.Mode, Is.EqualTo(\"DEC\"));\n\n\n\/\/ Provide multiple return values\nnsub.Mode.Returns(\"DEC\", \"HEX\", \"BIN\");\nAssert.AreEqual(\"DEC\", nsub.Mode);\nAssert.AreEqual(\"HEX\", nsub.Mode);\nAssert.AreEqual(\"BIN\", nsub.Mode);\n\n\/\/ Multiple return values with a function\nnsub.Mode.Returns(\n x => \"DEC\",\n x => \"HEX\",\n x => throw new Exception()\n);\nAssert.AreEqual(\"DEC\", nsub.Mode);\nAssert.AreEqual(\"HEX\", nsub.Mode);\nAssert.Throws<Exception>(() => { var result = nsub.Mode; });\n<\/code><\/pre>\nFor all of type<\/h3>\nusing NSubstitute.Extensions;\n\nnsub.Add(1, 3).Returns(3);\nnsub.ReturnsForAll<int>(5);\n\nAssert.That(nsub.Add(1, 3), Is.EqualTo(3));\nAssert.That(nsub.Add(0, 9), Is.EqualTo(5));\nAssert.That(nsub.Divide(0, 9, out float remainder), Is.EqualTo(5));\n<\/code><\/pre>\nOut and ref<\/h3>\n
ref<\/code> works in the same way as out<\/code>.<\/p>\nnsub.Divide(12, 5, out float remainder).Returns((CallInfo callInfo) => {\n callInfo[2] = 0.4F; \/\/ [2] = 3th parameter = remainder\n return 2;\n});\n\nAssert.AreEqual(2, nsub.Divide(12, 5, out remainder));\nAssert.AreEqual(0.4F, remainder);\n<\/code><\/pre>\nExceptions<\/h2>\nusing NSubstitute.ExceptionExtensions;\n\nnsub.Add(1, 1).Throws(new Exception());\nAssert.Throws<Exception>(() => nsub.Add(1, 1));\n\nnsub.When(x => x.SetMode(\"HEX\")).Throw<Exception>();\nAssert.Throws<Exception>(() => nsub.SetMode(\"HEX\"));\n<\/code><\/pre>\nSide effect callbacks<\/h1>\n
AndDoes<\/strong>:
Do something after Add<\/code> was called.<\/p>\nint counter = 0;\nnsub\n .Add(0, 0)\n .ReturnsForAnyArgs(x => 0)\n .AndDoes(x => counter++);\n\nnsub.Add(7, 3);\nnsub.Add(2, 2);\nAssert.AreEqual(counter, 2);\n<\/code><\/pre>\nMake voids do something<\/strong>:<\/p>\nbool called = false;\nsub\n .When(x => x.SetMode(\"HEX\"))\n .Do(x => called = true);\n\nsub.SetMode(\"HEX\");\nAssert.True(called);\n<\/code><\/pre>\nDo something with arguments passed<\/strong>:<\/p>\nint argumentUsed = 0;\nnsub.Add(10, Arg.Do<int>(x => argumentUsed = x));\n\nnsub.Add(10, 42);\nnsub.Add(11, 0); \/\/ does not overwrite argumentUsed because first arg is not 10\n\nAssert.AreEqual(42, argumentUsed);\n<\/code><\/pre>\nLess frequently used<\/h1>\nPartial Class Substitution<\/h2>\npublic class SummingReader\n{\n \/\/\/ <summary>\n \/\/\/ We will actually execute this\n \/\/\/ <\/summary>\n public virtual int CalculateSum(string path)\n {\n var s = ReadFile(path);\n return s.Split(',').Select(int.Parse).Sum();\n }\n\n \/\/\/ <summary>\n \/\/\/ While substituting this behavior\n \/\/\/ <\/summary>\n public virtual string ReadFile(string path)\n {\n throw new Exception($\"Actually attempted to access '{path}' on filesystem!\");\n }\n}\n\n\/\/ Tests:\nvar reader = Substitute.ForPartsOf<SummingReader>();\n\n\/\/ Without Arg. matchers, the actual ReadFile will be executed\nAssert.Throws<Exception>(() => reader.ReadFile(\"foo.txt\").Returns(\"1,2,3\"));\n\n\/\/ The Arg.Is makes sure that ReadFile is not executed\nreader.ReadFile(Arg.Is(\"foo.txt\")).Returns(\"1,2,3\");\nint result = reader.CalculateSum(\"foo.txt\");\nAssert.That(result, Is.EqualTo(6));\n\n\/\/ Alternatively: Use DoNotCallBase to play it (a bit) safer.\n\/\/ Make sure the ReadFile call won't call real implementation\nreader = Substitute.ForPartsOf<SummingReader>();\nreader.When(x => x.ReadFile(\"foo.txt\")).DoNotCallBase(); \/\/ <-- Magic here\nreader.ReadFile(\"foo.txt\").Returns(\"1,2,3\");\nresult = reader.CalculateSum(\"foo.txt\");\nAssert.That(result, Is.EqualTo(6));\n<\/code><\/pre>\nProvide values using CallInfo callback<\/h2>\nnsub\n .Add(Arg.Any<int>(), Arg.Any<int>())\n .Returns((CallInfo callInfo) =>\n {\n \/\/ Get argument value with indexer\n int firstArg = (int)callInfo[0];\n\n \/\/ By position\n int secondArg = callInfo.ArgAt<int>(1);\n\n \/\/ By type\n \/\/ Throws because there should be a Single parameter of the type\n Assert.Throws<AmbiguousArgumentsException>(() => callInfo.Arg<int>());\n\n \/\/ Get parameter type information\n Assert.That(callInfo.ArgTypes().First(), Is.EqualTo(typeof(int)));\n\n \/\/ Actual return value\n return firstArg + secondArg;\n });\n\nAssert.That(nsub.Add(1, 3), Is.EqualTo(4));\n\n<\/code><\/pre>\nEvents<\/h2>\n\n- Checking event subscriptions<\/a><\/li>\n
- Checking event invocation<\/a><\/li>\n
- Raising events<\/a><\/li>\n<\/ul>\n
Summary<\/h1>\n
So I like NSubstitute. Like a lot. That\u2019s it.<\/p>\n
For more examples – as UnitTests – check the Github source<\/a>.<\/p>\nAlso in this series<\/h1>\n
![](\"https:\/\/img.shields.io\/github\/stars\/nsubstitute\/NSubstitute.svg?style=social&label=Star\")
<\/a>