Mockolate.Migration
0.8.0
Prefix Reserved
dotnet add package Mockolate.Migration --version 0.8.0
NuGet\Install-Package Mockolate.Migration -Version 0.8.0
<PackageReference Include="Mockolate.Migration" Version="0.8.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
<PackageVersion Include="Mockolate.Migration" Version="0.8.0" />
<PackageReference Include="Mockolate.Migration"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
paket add Mockolate.Migration --version 0.8.0
#r "nuget: Mockolate.Migration, 0.8.0"
#:package Mockolate.Migration@0.8.0
#addin nuget:?package=Mockolate.Migration&version=0.8.0
#tool nuget:?package=Mockolate.Migration&version=0.8.0
Mockolate.Migration
A Roslyn analyzer and code fix that migrate Moq and NSubstitute usage to Mockolate. Drop the package into a project that uses one of those libraries and the analyzer flags each mock it can migrate; the code fix rewrites the setup, verification, and event APIs to their Mockolate equivalents.
The documentation is at docs.testably.org/Mockolate/migration/automated.
Installation
The migration package does not reference Mockolate, so install Mockolate into the project you want to migrate as well, then the migration package:
dotnet add package Mockolate
dotnet add package Mockolate.Migration
The migration package only needs to be referenced while you are migrating: it ships the analyzer and the code fix, not runtime code.
How it works
After installing the package, every mock the code fix can migrate is reported as a warning. The code fix rewrites the whole mock (the construction call, all setup calls on that mock, the corresponding verification calls, event wiring, and trailing .Object accesses for Moq) in a single step and adds using Mockolate;.
| Diagnostic | Source library | Code fix title |
|---|---|---|
MockolateM001 |
Moq | Migrate Moq to Mockolate |
MockolateM002 |
NSubstitute | Migrate NSubstitute to Mockolate |
Workflow
- Install Mockolate and the migration package.
- Apply the code fix in your IDE (Visual Studio, Rider, VS Code with C# Dev Kit), with Fix all occurrences for many mocks at once, or from the command line with
dotnet format analyzers --diagnostics MockolateM001 MockolateM002. - Remove
using Moq;orusing NSubstitute;from the migrated files once nothing else in them uses the source library. The code fix keeps the directive, and with Moq,Itis ambiguous until you remove it. - Build, run your tests and check what needs manual review: the code fix leaves a
// TODO(MockolateM001)or// TODO(MockolateM002)comment where it cannot finish the migration on its own. The pages for Moq and NSubstitute also list where the migrated code behaves differently. - Remove Moq or NSubstitute and the migration package. Mockolate stays in the project.
To keep a mock as it is, suppress the warning with #pragma warning disable MockolateM001 (or MockolateM002) or with dotnet_diagnostic.MockolateM001.severity = none in .editorconfig.
Migrating from Moq
The Moq code fix rewrites new Mock<T>(...) to T.CreateMock(...), drops every trailing .Object access, and moves setups and verifications onto the strongly-typed Mock.Setup / Mock.Verify chains. Strict mocks are mapped to Mockolate.MockBehavior.Default.ThrowingWhenNotSetup() (qualified, because Moq has a MockBehavior as well), It.Is<T>(predicate) becomes It.Satisfies<T>(...), and event raising / verification are routed through Mock.Raise and event-specific Mock.Verify.<Event>.Subscribed() / Unsubscribed() calls.
// Before (Moq)
Mock<IFoo> mock = new Mock<IFoo>();
mock.Setup(m => m.Compute(It.IsAny<int>())).Returns(42);
Service sut = new Service(mock.Object);
sut.Run();
mock.Verify(m => m.Compute(It.IsAny<int>()), Times.Once());
// After (Mockolate)
IFoo mock = IFoo.CreateMock();
mock.Mock.Setup.Compute(It.IsAny<int>()).Returns(42);
Service sut = new Service(mock);
sut.Run();
mock.Mock.Verify.Compute(It.IsAny<int>()).Once();
// Before (Moq): properties and events
Mock<IFoo> mock = new Mock<IFoo>(MockBehavior.Strict);
mock.SetupProperty(m => m.Name, "initial");
mock.Raise(m => m.Changed += null, EventArgs.Empty);
mock.VerifyAdd(m => m.Changed += It.IsAny<EventHandler>(), Times.Once());
// After (Mockolate)
IFoo mock = IFoo.CreateMock(Mockolate.MockBehavior.Default.ThrowingWhenNotSetup());
mock.Mock.Setup.Name.InitializeWith("initial");
mock.Mock.Raise.Changed(null, EventArgs.Empty);
mock.Mock.Verify.Changed.Subscribed().Once();
Supported Moq migrations
| Moq construct | Rewritten to |
|---|---|
new Mock<IFoo>() |
IFoo.CreateMock() |
new Mock<IFoo>(MockBehavior.Strict) |
IFoo.CreateMock(Mockolate.MockBehavior.Default.ThrowingWhenNotSetup()) |
mock.Object |
mock (the .Object access is dropped) |
mock.Setup(m => m.Method(args)) |
mock.Mock.Setup.Method(args) |
mock.Setup(m => m.Prop) / mock.SetupGet(...) |
mock.Mock.Setup.Prop |
mock.SetupProperty(m => m.Prop) |
mock.Mock.Setup.Prop.Register() |
mock.SetupProperty(m => m.Prop, value) |
mock.Mock.Setup.Prop.InitializeWith(value) |
mock.SetupSequence(...).Returns(a).Returns(b) |
mock.Mock.Setup.Method(...).Returns(a).Returns(b).Returns(default(T)).Forever() |
mock.SetupSequence(...).Pass().Throws(e) (void method) |
mock.Mock.Setup.Method(...).DoesNotThrow().Throws(e).OnlyOnce() |
.Returns(...) / .ReturnsAsync(...) / .Throws(...) |
preserved on the Mockolate setup chain |
.Callback(...) |
.Do(...) on the Mockolate setup |
mock.InSequence(seq).Setup(...) (and other setups) |
.InSequence(...) wrapper is stripped; use Verify…Then(...) for ordering |
mock.Verify(m => m.Method(args), Times.Once()) |
mock.Mock.Verify.Method(args).Once() |
mock.VerifyGet(m => m.Prop, times) |
mock.Mock.Verify.Prop.Got().<times>() |
mock.VerifySet(m => m.Prop = value, times) |
mock.Mock.Verify.Prop.Set(value).<times>() |
mock.Raise(m => m.Event += null, eventArgs) |
mock.Mock.Raise.Event(null, eventArgs) |
mock.Raise(m => m.Event += null, args...) (custom delegate) |
mock.Mock.Raise.Event(args...) |
mock.VerifyAdd(m => m.Event += ..., times) |
mock.Mock.Verify.Event.Subscribed().<times>() |
mock.VerifyRemove(m => m.Event -= ..., times) |
mock.Mock.Verify.Event.Unsubscribed().<times>() |
Non-literal Times argument (e.g. a variable) |
Original Moq call kept, with a // TODO comment |
It.IsAny<T>() |
preserved as It.IsAny<T>() |
It.Is<T>(predicate) |
It.Satisfies<T>(predicate) |
It.IsInRange(lo, hi, Range.Inclusive) |
It.IsInRange(lo, hi) (the Range argument is dropped) |
It.IsRegex(pattern) |
It.Matches(pattern).AsRegex().CaseSensitive() |
It.IsRegex(pattern, options) |
It.Matches(pattern).AsRegex(options).CaseSensitive() |
It.Ref<T>.IsAny / out parameters |
It.IsAnyRef<T>() / It.IsOut(() => value) |
Nested mocks (mock.Setup(m => m.Child.Prop)) |
mock.Child.Mock.Setup.Prop plus a // TODO comment to register Child |
Migrating from NSubstitute
The NSubstitute code fix rewrites Substitute.For<T>(...) to T.CreateMock(...) and reroutes the implicit setup/verify calls (sub.Method(args).Returns(...), sub.Received().Method(...)) through the strongly-typed Mock.Setup / Mock.Verify chains. Arg.Any<T>() becomes It.IsAny<T>(), Arg.Is<T>(predicate) becomes It.Satisfies<T>(...), and Raise.Event(...) is rewritten to the corresponding sub.Mock.Raise.<Event>(...) call. Nested-mock setups (sub.Child.M(args).Returns(...)) are migrated with a // TODO comment because the parent must be wired up to return the child mock manually.
// Before (NSubstitute)
IFoo sub = Substitute.For<IFoo>();
sub.Compute(Arg.Any<int>()).Returns(42);
Service sut = new Service(sub);
sut.Run();
sub.Received(1).Compute(Arg.Any<int>());
// After (Mockolate)
IFoo sub = IFoo.CreateMock();
sub.Mock.Setup.Compute(It.IsAny<int>()).Returns(42);
Service sut = new Service(sub);
sut.Run();
sub.Mock.Verify.Compute(It.IsAny<int>()).Once();
// Before (NSubstitute): sequential returns, When/Do, events
IFoo sub = Substitute.For<IFoo>();
sub.Compute(0).Returns(1, 2, 3);
sub.When(x => x.Reset()).Do(_ => counter++);
sub.Changed += Raise.EventWith(EventArgs.Empty);
// After (Mockolate)
IFoo sub = IFoo.CreateMock();
sub.Mock.Setup.Compute(0).Returns(1).Returns(2).Returns(3).Forever();
sub.Mock.Setup.Reset().Do(() => counter++);
sub.Mock.Raise.Changed(null, EventArgs.Empty);
CallInfo callbacks
NSubstitute's Returns(call => …), When(...).Do(call => …), and AndDoes(call => …) callbacks
receive a CallInfo parameter that exposes the invocation arguments. Mockolate's equivalent
overloads instead take the method's parameters directly, so the migration rewrites the lambda:
- Body never reads the parameter: drop it,
Do(call => x++)→Do(() => x++). - Body uses statically resolvable accesses (
call.ArgAt<T>(literalIndex),call[literalIndex], or type-uniquecall.Arg<T>()): rewrite the lambda's parameter list to match the receiver method and replace each access with the matching parameter name:Returns(call => call.ArgAt<int>(0) + 1)→Returns((int x) => x + 1). - Anything else (bare
call, dynamic indices, indexer-write for out/ref, ambiguouscall.Arg<T>(), or local variables that would shadow the injected parameter names): preserve the original lambda and emit a// TODOcomment so the rewrite can be done by hand.
Supported NSubstitute migrations
| NSubstitute construct | Rewritten to |
|---|---|
Substitute.For<IFoo>() |
IFoo.CreateMock() |
Substitute.For<IFoo>(args) |
IFoo.CreateMock(args) |
Substitute.For<IFoo, IBar>() |
IFoo.CreateMock().Implementing<IBar>() (chains for additional types) |
Substitute.ForPartsOf<MyClass>() |
MyClass.CreateMock() (Mockolate calls base by default) |
Substitute.ForTypeForwardingTo<TInterface, TClass>(args) |
TInterface.CreateMock().Wrapping(new TClass(args)) |
sub.Method(args).Returns(v) |
sub.Mock.Setup.Method(args).Returns(v) |
sub.Method(args).Returns(v1, v2, v3) |
sub.Mock.Setup.Method(args).Returns(v1).Returns(v2).Returns(v3).Forever() |
sub.Method(args).Throws<E>() / Throws(ex) |
sub.Mock.Setup.Method(args).Throws<E>() / .Throws(ex) |
sub.Method(args).ReturnsForAnyArgs(v) |
sub.Mock.Setup.Method(args).AnyParameters().Returns(v) |
sub.Method(args).ThrowsForAnyArgs<E>() |
sub.Mock.Setup.Method(args).AnyParameters().Throws<E>() |
sub.Method(args).Returns(v).AndDoes(cb) |
sub.Mock.Setup.Method(args).Returns(v).Do(cb) |
sub.Property.Returns(v) |
sub.Mock.Setup.Property.Returns(v) |
sub.Received().Method(args) |
sub.Mock.Verify.Method(args).AtLeastOnce() |
sub.Received(n).Method(args) |
sub.Mock.Verify.Method(args).Exactly(n) (Once() for n == 1) |
sub.DidNotReceive().Method(args) |
sub.Mock.Verify.Method(args).Never() |
sub.ReceivedWithAnyArgs().Method(default, default) |
sub.Mock.Verify.Method(default, default).AnyParameters().AtLeastOnce() |
sub.DidNotReceiveWithAnyArgs().Method(default, default) |
sub.Mock.Verify.Method(default, default).AnyParameters().Never() |
_ = sub.Received().Prop |
sub.Mock.Verify.Prop.Got().AtLeastOnce() |
sub.Received().Prop = v |
sub.Mock.Verify.Prop.Set(v).AtLeastOnce() |
sub.ClearReceivedCalls() |
sub.Mock.ClearAllInteractions() |
sub.MyEvent += Raise.Event() |
sub.Mock.Raise.MyEvent(null, EventArgs.Empty) |
sub.MyEvent += Raise.EventWith(sender, args) |
sub.Mock.Raise.MyEvent(sender, args) |
sub.MyEvent += Raise.EventWith(args) |
sub.Mock.Raise.MyEvent(null, args) |
sub.MyEvent += Raise.Event<TDelegate>(args...) |
sub.Mock.Raise.MyEvent(args...) (delegate type dropped) |
sub.When(x => x.M(args)).Do(cb) |
sub.Mock.Setup.M(args).Do(cb) |
sub.When(x => x.M(args)).DoNotCallBase() |
sub.Mock.Setup.M(args).SkippingBaseClass() |
Arg.Any<T>() |
It.IsAny<T>() |
Arg.Is<T>(predicate) |
It.Satisfies<T>(predicate) |
Arg.Is(value) / Arg.Is<T>(value) |
It.Is(value) / It.Is<T>(value) |
Arg.Compat.X<T>(...) |
same as the corresponding Arg.X<T>(...) |
Nested mocks (sub.Child.M(args).Returns(v)) |
sub.Child.Mock.Setup.M(args).Returns(v) plus a // TODO comment to register Child |
Learn more about Target Frameworks and .NET Standard.
This package has no dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.