Updated Apr 16, 2009 by kzu.net
Labels:	Featured

QuickStart

Introduction to Moq

Moq is intended to be simple to use, strong typed (no magic strings!, and therefore full compiler-verified and refactoring-friendly) and minimalistic (while still fully functional!).

Methods

var mock = new Mock<IFoo>();
mock.Setup(foo => foo.Execute("ping")).Returns(true);


// out arguments
var outString = "ack";
// TryParse will return true, and the out argument will return "ack", lazy evaluated
mock.Setup(foo => foo.TryParse("ping", out outString)).Returns(true);


// ref arguments
var instance = new Bar();
// Only matches if the ref argument to the invocation is the same instance
mock.Setup(foo => foo.Submit(ref instance)).Returns(true);


// access invocation arguments when returning a value
mock.Setup(x => x.Execute(It.IsAny<string>()))
		.Returns((string s) => s.ToLower());
// Multiple parameters overloads available


// throwing when invoked
mock.Setup(foo => foo.Execute("reset")).Throws<InvalidOperationException>();
mock.Setup(foo => foo.Execute("")).Throws(new ArgumentException("command");


// lazy evaluating return value
mock.Setup(foo => foo.Count()).Returns(() => count);


// returning different values on each invocation
var mock = new Mock<IFoo>();
var calls = 0;
mock.Setup(foo => foo.Execute("ping"))
    .Returns(() => calls)
    .Callback(() => calls++);
// returns 0 on first invocation, 1 on the next, and so on
Console.WriteLine(mock.Object.Execute("ping"));

Matching Arguments

// any value
mock.Setup(foo => foo.Execute(It.IsAny<string>())).Returns(true);


// matching Func<int>, lazy evaluated
mock.Setup(foo => foo.Add(It.Is<int>(i => i % 2 == 0))).Returns(true); 


// matching ranges
mock.Setup(foo => foo.Add(It.IsInRange<int>(0, 10, Range.Inclusive))).Returns(true); 


// matching regex
mock.Setup(x => x.Execute(It.IsRegex("[a-d]+", RegexOptions.IgnoreCase))).Returns("foo");

Properties

mock.Setup(foo => foo.Name).Returns("bar");


// auto-mocking hierarchies (a.k.a. recursive mocks)
mock.Setup(foo => foo.Bar.Baz.Name).Returns("baz");

// expects an invocation to set the value to "foo"
mock.SetupSet(foo => foo.Name = "foo");

// or verify the setter directly
mock.VerifySet(foo => foo.Name = "foo");

Setup a property so that it will automatically start tracking its value (also known as Stub):

// start "tracking" sets/gets to this property
mock.SetupProperty(f => f.Name);

// alternatively, provide a default value for the stubbed property
mock.SetupProperty(f => f.Name, "foo");


// Now you can do:

IFoo foo = mock.Object;
// Initial value was stored
Assert.Equal("foo", foo.Name);

// New value set which changes the initial value
foo.Name = "bar";
Assert.Equal("bar", foo.Name);

Stub all properties on a mock (not available on Silverlight):

mock.SetupAllProperties();

Events

// Raising an event on the mock
mock.Raise(m => m.FooEvent += null, new FooEventArgs(fooValue));

// Raising an event on a descendant down the hierarchy
mock.Raise(m => m.Child.First.FooEvent += null, new FooEventArgs(fooValue));

// Causing an event to raise automatically when Submit is invoked
mock.Setup(foo => foo.Submit()).Raises(f => f.Sent += null, EventArgs.Empty);
// The raised event would trigger behavior on the object under test, which 
// you would make assertions about later (how its state changed as a consequence, typically)

// Raising a custom event which does not adhere to the EventHandler pattern
public delegate void MyEventHandler(int i, bool b);
public interface IFoo
{
  event MyEventHandler MyEvent; 
}

var mock = new Mock<IFoo>();
...
// Raise passing the custom arguments expected by the event delegate
mock.Raise(foo => foo.MyEvent += null, 25, true);

Callbacks

var mock = new Mock<IFoo>();
mock.Setup(foo => foo.Execute("ping"))
    .Returns(true)
    .Callback(() => calls++);


// access invocation arguments
mock.Setup(foo => foo.Execute(It.IsAny<string>()))
    .Returns(true)
    .Callback((string s) => calls.Add(s));


// callbacks can be specified before and after invocation
mock.Setup(foo => foo.Execute("ping"))
    .Callback(() => Console.WriteLine("Before returns"))
    .Returns(true)
    .Callback(() => Console.WriteLine("After returns"));

Verification

mock.Verify(foo => foo.Execute("ping"));

// Verify with custom error message for failure
mock.Verify(foo => foo.Execute("ping"), "When doing operation X, the service should be pinged always");

// Method should never be called
mock.Verify(foo => foo.Execute("ping"), Times.Never());

// Called at least once
mock.Verify(foo => foo.Execute("ping"), Times.AtLeastOnce());

mock.VerifyGet(foo => foo.Name);

// Verify setter invocation, regardless of value.
mock.VerifySet(foo => foo.Name);

// Verify setter called with specific value
mock.VerifySet(foo => foo.Name ="foo");

// Verify setter with an argument matcher
mock.VerifySet(foo => foo.Value = It.IsInRange(1, 5, Range.Inclusive));

Customizing Mock Behavior

Make mock behave like a "true Mock", raising exceptions for anything that doesn't have a corresponding expectation: in Moq slang a "Strict" mock; default behavior is "Loose" mock, which never throws and returns default values or empty arrays, enumerables, etc. if no expectation is set for a member

var mock = new Mock<IFoo>(MockBehavior.Strict);

Invoke base class implementation if no expectation overrides the member (a.k.a. "Partial Mocks" in Rhino Mocks): default is false. (this is required if you are mocking Web/Html controls in System.Web!)

var mock = new Mock<IFoo> { CallBase = true };

Make an automatic recursive mock: a mock that will return a new mock for every member that doesn't have an expectation and whose return value can be mocked (i.e. it is not a value type)

var mock = new Mock<IFoo> { DefaultValue = DefaultValue.Mock };
// default is DefaultValue.Empty

// this property access would return a new mock of IBar as it's "mock-able"
IBar value = mock.Object.Bar;

// the returned mock is reused, so further accesses to the property return 
// the same mock instance. this allows us to also use this instance to 
// set further expectations on it if we want
var barMock = Mock.Get(value);
barMock.Setup(b => b.Submit()).Returns(true);

Centralizing mock instance creation and management: you can create and verify all mocks in a single place by using a MockFactory, which allows setting the MockBehavior, its CallBase and DefaultValue consistently

var factory = new MockFactory(MockBehavior.Strict) { DefaultValue = DefaultValue.Mock };

// Create a mock using the factory settings
var fooMock = factory.Create<IFoo>();

// Create a mock overriding the factory settings
var barMock = factory.Create<IBar>(MockBehavior.Loose);

// Verify all verifiable expectations on all mocks created through the factory
factory.Verify();

Miscellaneous

Setting expectations for protected members (you can't get intellisense for these, so you access them using the member name as a string):

// at the top of the test fixture
using Moq.Protected()

// in the test
var mock = new Mock<CommandBase>();
mock.Protected()
     .Setup<int>("Execute")
     .Returns(5);

// if you need argument matching, you MUST use ItExpr rather than It
// planning on improving this for vNext
mock.Protected()
    .Setup<string>("Execute",
        ItExpr.IsAny<string>())
    .Returns(true);

Advanced Features

// get mock from a mocked instance
IFoo foo = // get mock instance somehow
var fooMock = Mock.Get(foo);
fooMock.Setup(f => f.Submit()).Returns(true);


// implementing multiple interfaces in mock
var foo = new Mock<IFoo>();
var disposableFoo = foo.As<IDisposable>();
// now the IFoo mock also implements IDisposable :)
disposableFoo.Setup(df => df.Dispose());


// custom matchers
mock.Setup(foo => foo.Submit(IsLarge())).Throws<ArgumentException>();
...
public string IsLarge() 
{ 
  return Match<string>.Create(s => !String.IsNullOrEmpty(s) && s.Length > 100);
}

Note: when you need to pass the mock for consumption, you must use the mock.Object accessor as a consequence of a C# compiler restriction (vote to get it removed at Microsoft Connect)

Head on to the API documentation, download it and have fun! Engage in the discussion group to give us feedback, share your experiences or wishes for vNext!

Comment by david.kassa, Apr 06, 2009

Is there a way to view the old 2.6 QuickStart? We haven't quite ported over and it's a nice reference.

Comment by jcsston, Apr 09, 2009

It looks like you can see the old wiki pages in svn, http://code.google.com/p/moq/source/browse/wiki/QuickStart.wiki?r=477

Comment by danny.erunner, Apr 23, 2009

Hi, I'm newbie using VSE2008 that doesn't come with any unit test.

I've downloaded the Moq, so whats next? where to put the dll? how to create a unit test?

Appreciate if any one can help.

Thanks a lot.

Comment by benoit808, May 07, 2009

@danny.erunner Moq is a mocking framework which is only a part of unit testing. I'd suggest you take a look at NUnit or MbUnit? for unit tests

Comment by fostandy, Jun 29, 2009

There are a few old/unanswered discussions going around regarding how to mock a reference parameter. The quickstart guide provides us with a way of mocking a reference parameter which has a particular value but it is still unclear regarding whether it is possible how to (a) mock 'any' reference parameter and (b) change the value of that reference parameter in callback. Would it be possible to get some clarification on whether moq is capable of this, and if so, how?

Comment by dlang...@hawaii.edu, Jul 15, 2009

Suppose I want to do a unit test on classA.method1(int x, int y, int z)

classA.method1, in turn, calls classB.method2(int x, int y, int z, ref string msg)

It seems that it is impossible to mock classB.method2 because "msg", the argument to method2 is called inside method1, but it says in the documentation that to match my mock setup, msg must be the same instance as the string in my setup!

What can I do?

Comment by ryan.mcdonald82, Jul 17, 2009

"I've downloaded the Moq, so whats next? where to put the dll?"

Good question. Is the install REALLY so simple that it's not worth mentioning? I'm coming from the linux world, so I'm used to readme files, installation instructions, man pages, etc. The post above proves I'm not the only one with this sentiment - why not put up a couple of sentences explaining how to install moq (I'd suggest the top of the quickstart page). Thanks.

Comment by nathapolw, Aug 27, 2009

Ryan,

Just add reference to moq.dll to your project in Visual Studio and you are good to go!

Comment by randolpho, Sep 21, 2009

@ryan.mcdonald82:

To expand on @nathapolw's post:

You can simply download the zip file and extract it to a known location, then add a file reference to the moq.dll (using the "Browse" tab that appears in the Visual Studio "Add Reference..." command.

Comment by darcy.parks, Nov 03, 2009

I had some trouble understanding callbacks for multi-argument methods; here's what worked for me. If it's correct, could you consider adding it?

// access invocation arguments
mock.Setup(foo => foo.Execute(It.IsAny<int>(), It.IsAny<string>()))
    .Returns(true)
    .Callback<int, string>((int i, string s) => calls.Add(s));