Rhino Mocks Version 2.3

Project page.

Download Rhino Mocks

License: BSD

Last Updated At: Wednesday, 17. August 2005 10:55:59

Elevator Speech: Top

Rhino Mocks allows you to easily create mock objects and setup a wide range of expectations on them using strongly typed notation instead of compiler opaque strings. It's as simple as:

IProjectView projectView = (IProjectView)mocks.CreateMock(typeof(IProjectView));
Expect.Call(projectView.Title).Return("Project's Title");

Definitions:

What is new? Top

Version 2.3:

Version 2.2:

Version 2.1:

Version 2.0:

Rhino Mocks capabilities:Top

Let's get down to the code, okay? [I tried to create an example for this article, but the example was both contrived and didn't portrayed the possibilities correctly. So most of the code samples here were taken from NHibernate Query Analyzer tests and are "real code".]

The purpose of mock objects is to allow you to test the interactions between components, this is very useful when you test code that doesn't lend itself easily to state base testing. Most of the examples here are tests to check that the save routine for a view is working as expected. The requirements for this method are:

So we have five tests here:

  1. Project is new project, and the user cancels on new name.

  2. Project is new project, the user gives a new name, and the project is saved.

  3. Project is new project, the user gives a name that already exists and don't approve overwrite.

  4. Project is new project, the user gives a name that already exist and approve overwrite.

  5. Project already exists, so just save it.

Trying to test that using state based testing is going to be both awkward and painful, using interaction based testing, it would be a breeze (other types of tests would be just as painful to test using interaction testing but easy using state testing.)

That is enough talking, let's see some code:Top

[Test]
public void SaveProjectAs_CanBeCanceled()
{
  using(MockRepository mocks = new MocksRepository())
  {
    IProjectView projectView = (IProjectView)projectView.CreateMock(typeof(IProjectView));
    Project prj = new Project("Example Project");
    IProjectPresenter presenter = new ProjectPresenter(prj,projectView);
    Expect.Call(projectView.Title).Return(prj.Name);
    Expect.Call(projectView.Ask(question,answer)).Return(null);
    mocks.ReplayAll();
    Assert.IsFalse(presenter.SaveProjectAs());          
  }
}

We create a MockRepository and create a mock project view, project and a project presenter, then we set the expectations. After we finished with setting up the expectations, we move to the replay state, and call the SaveProjectAs() method, which should return false if the user canceled the save process.

This example clarify several key concepts with Rhino Mocks.

This is about as simple example as can be had, the real test moves creating the MockRepository, the project, the view and presenter to the setup method, since they are require for each test. You can see that we expected two methods to be called, with specific arguments, and that we set a result for each. This method uses parameter matching expectations, Rhino Mocks supports several more. More info: Method Calls.

Mock Objects and Dynamic Mocks: Top

Rhino Mocks currently support the creation of two types of mock objects.

What is the meaning of strict vs. loose replay semantics?

Strict replay semantics: only the methods that were explicitly recorded are accepted as valid. This mean that any call that is not expected would cause an exception and fail the test. All the expected methods must be called if the object is to pass verification.

Loose replay semantics: any method call during the replay state is accepted and if there is no special handling setup for this method a null or zero is returned. All the expected methods must be called if the object is to pass verification.

Let's see some code that would explain it better than words. The difference between the tests are marked with bold. First, the mock object code:

[Test]
[ExpectedException(typeof (ExpectationViolationException), 
    "IDemo.VoidNoArgs(); Expected #0, Actual #1.")]
public void MockObjectThrowsForUnexpectedCall()
{
  using(MockRepository mocks = new MockRepository())
  {
    IDemo demo = (IDemo)mocks.CreateMock(typeof(IDemo));
    mocks.ReplayAll();
    demo.VoidNoArgs();
  }
}

As you can see, calling a method that wasn't explicitly setup will cause an exception to be thrown, now let's try it with a dynamic mock:

[Test]
public void DyamicMockAcceptUnexpectedCall()
{
  using(MockRepository mocks = new MockRepository())
  {
    IDemo demo = (IDemo)mocks.DynamicMock(typeof(IDemo));
    mocks.ReplayAll();
    demo.VoidNoArgs();
  }
}

As you can see, an unexpected call is ignored when you are using a dynamic mock.

However, this is the only difference between the two types, in all other ways they are identical (ordering, recording a method expectation, callbacks, etc). An expectations that was created during the record phase must be satisfied if the dynamic mock is to pass verification.

Dynamic mocks are useful when you want to check a small piece of functionality and you don't care about whatever else may happen to the object. Mock objects are useful when you want complete control over what happens to the mocked object.

Ordered / Unordered: Top

Method calls in Rhino Mocks can be ordered or unordered. The default state for a recorder is unordered recording, this means that during replay, methods can come at any order. If the recorder is changed to ordered, then the methods must be called in the exact same order as they were recorded. Here is a code sample:

[Test]
public void SaveProjectAs_NewNameWithoutConflicts()
{
  using(mocks.Ordered())
  {
    Expect.Call(projectView.Title).
      Return(prj.Name);
    Expect.Call(projectView.Ask(question,answer)).
      Return( newProjectName);
    Expect.Call(repository.GetProjectByName(newProjectName)).
      Return(null);
    projectView.Title = newProjectName;
    projectView.HasChanges = false;
    repository.SaveProject(prj);
  }
  mocks.ReplayAll();
  Assert.IsTrue(presenter.SaveProjectAs());
  Assert.AreEqual(newProjectName,prj.Name);
}

In the above code example we ask Rhino Mocks to verify that the calls come in the exact same order. Notice that we specify expectations on several mock objects, and Rhino Mocks will handle the ordering between them. This mean that if I set the project view title before I get a project from the repository, the test will fail. In Rhino Mocks, the default is to use unordered matching, but it support unlimited depth of nesting between ordered and unordered, this means that you can create really powerful expectations. Here is a somewhat contrived example:

[Test]
public void MovingFundsUsingTransactions()
{
  using(MockRepository mocks = new MockRepository())
  {
     IDatabaseManager databaseManager = (IDatabaseManager)mocks.CreateMock(typeof(IDatabaseManager));
     IBankAccount accountOne = (IBackAccount)mocks.CreateMock(typeof(IBackAccount)),
         accountTwo = (IBackAccount)mocks.CreateMock(typeof(IBankAccount)); 
     using(mocks.Ordered())
     {
        Expect.Call(databaseManager.BeginTransaction()).
           Return(databaseManager);
         using(mocks.Unordered())
         {
            accountOne.Withdraw(1000);
            accountTwo.Deposit(1000);
         }
         databaseManager.Dispose();
     }
     mocks.ReplayAll();
 
     Bank bank = new Bank(databaseManager);
     bank.TransferFunds(accountOne,accountTwo,1000);
  }
}

This code verify that the transfer of funds from one account to another is wrapped in a transaction, but the implementation is free to withdraw from the first account first, or to deposit into the second account first, both are legal, as long as both actions happens. The reverse is true as well, you may specified unordered sequence of ordered events (I want A then B then C to happen, and I want D then E then F to happen, but I don't care which sequence comes first).

Ordering have two caveats:

The IDisposable pattern:Top

The using(...) syntax & IDisposable are very convenient when it comes to make sure you're not forgetting to clean up resources, in Rhino Mocks, it's used in two places:

Method Calls: Top

When Rhino Mocks intercept a call from a mocked object it determines if the call is expected by checking the method signature, the object this method was called on, whatever the expectation on this method match the arguments passed for the method. The matching of the mocked object and the method signature is not very interesting, but the expectations on a method call is. Rhino Mocks support the following expectations:

Properties: Top

If you want to mock properties, you need to keep in mind that properties are merely special syntax for normal methods, a get property will translate directly to propertyType get_PropertyName() and a set property will translate directory to void set_PropertyName(propertyType value). So how do you create expectations for a property? Exactly as you would for those methods.

Here is how you set the return value for a get property:

IList list = (IList)mocks.CreateType(typeof(IList));
Expect.Call(list.Count).Return(42);

And here is how you would set an expectation for a set property:

IList list = (IList)mocks.CreateType(typeof(IList));
list.Capacity = 500;//Will create an expectation for this call
LastCall.IgnoreArguments();//Ignore the amounts that is passed.

Callbacks: Top

A callback is a user supplied delegate that is called whenever Rhino Mocks needs to evaluate whatever a method call is expected or not. This is useful in some scenarios when you want to do a complex validation on a method arguments, or have a complex interactions between objects that you need to mock in the tests. I added this feature because I want to test some threading code which had the semantics of: Start Job, and notify me when you're done. The only way to re-create that without bringing the real thread (and kill tests isolations) was to plug my own code during the replay state and call the tested object myself.

Some things to consider before you decide to use callbacks:

If it so open to abuse, why add it?

The technical details - In order to be a valid callback, the callback must return a Boolean, and have the same arguments as the mocked methods. You register a delegate using the following code:

IProjectRepository repository = (IProjectRepository) mocks.CreateMock(typeof(IProjectRepository));
IProjectView view = (IProjectView )mocks.CreateMock(typeof(IProjectView ));
Expect.Call(view.Ask(null,null)).Callback(new AskDelegate(DemoAskDelegateMethod)).Return(null);

Notice that you cannot change the return value for the method, but must pass it explicitly.

Recursive Expectations: Top

One final word of warning regarding callbacks. If your callback will initiate an action that cause another call on a mocked object, this will fail when mixed with Ordered(). The reason for that is that the framework cannot decide whatever to accept the call or not, and calling another mocked method while evaluating means that the currently expected call is the one still being evaluated. This will fail the test. Using Unordered(), it will work, since the second expectation is not dependant on the first one being accepted first. In short, Ordered() is not re-entrant :-)

Method Options Interface: Top

The IMethodOptions allows you to set various options on a method call. Here is an example of telling Rhino Mocks to ignore the arguments of a method:

IProjectRepository repository = (IProjectRepository)mocks.CreateMock(typeof(IProjectRepository));
IProjectView view = (IProjectView ) mocks.CreateMock(typeof(IProjectView ));
Expect.Call(view.Ask(null,null)).IgnoreArguments().Return(null);
repository.SaveProject(null);
LastCall.IgnoreArguments();

As you can see, we use the Expect.Call() for methods that has return values, and LastCall for methods that return void to get the IMethodOptions interface. I find the Expect.Call() syntax a bit clearer, but there is no practical difference between the two. I would recommend using Expect wherever possible (anything that return a value). For properties setters, or methods returning void, the Expect syntax is not applicable, since there is no return value. Thus, the need for the LastCall. The idea of Last Call is pervasive in the record state, you can only set the method options for the last call - even Expect.Call() syntax is merely a wrapper around LastCall.

Expect.Call() & LastCall allows you to set the following options:

Expect.Call(view.Ask(null,null)).
  Return(null);
Expect.Call(view.Ask(null,null)).
  Throw(new Exception("Demo"));
Expect.Call(view.Ask(null,null)).Return(null).
  Repeat.Twice();
Expect.Call(view.Ask(null,null)).Return(null).
  IgnoreArguments();
Expect.Call(view.Ask(null,null)).Return(null)
  .Constraints(Text.StartsWith("Some"),Text.EndsWith("Text"));
Expect.Call(view.Ask(null,null)).Return(null).
  Callback(new AskDelegate(VerifyAskArguments));

Note: For methods that return a value, you must specify either a return value or an exception to throw. You will not be able to continue recording or move to replay state otherwise.

Note II: Method chaining really makes writing this cod easier.

Constraints: Top

Constraints are a way to verify that a method arguments match a certain criteria. Rhino Mocks include a number of built in constraints, and allows you to define you own custom one, which will integrate cleanly into the framework. You specify constraints on method arguments using the following syntax:

Expect.Call(view.Ask(null,null)).Return(null).
  Constraints(Text.StartsWith("Some"),Text.EndsWith("Text"));

You need to pass the exact same number of constraints as the number of arguments of the method. When a method is called during replay state, Rhino Mocks evaluate each constraint against the parameter in the same index, and accept the method if all the constraints were met. As a note, I got the idea of the current constraints syntax from NMock2, it is much leaner approach to create constraints.

Rhino Mocks built in constraints:

Rhino mocks ships with the following constraints:

Constraint:

Example:

Accepted Value(s):

Unaccepted Value(s):

Object

Anything

Is.Anything()

Anything at all {0,"","whatever",null, etc}

(Nothing at all!)

Equal

Is.Equal(3)

(int)3

3f, 4,"", new object()

Not Equal

Is.NotEqual(3) or !Is.Equal(3)

3f,43,null,DateTime.Now

(int)3

Null

Is.Null()

null

5,"",new object()

Not Null

Is.NotNull()

DateTime.Now, "asbcd", 0xHead

null

Type Of

Is.TypeOf(typeof(string))

"","Hello",String.Empty

null, 3, DateTime.Now

Greater Than

Is.GreaterThan(10)

15,100,300

3,4,5, 10

Greater Than Or Equal

Is.GreaterThanOrEqual(10)

10,15,100

4,2,8,9

Less Than

Is.LessThan(10)

1,2,9

10,32,100

Less Than Or Eqaul

Is.LessThanOrEqual(10)

1,9,10

11,33,43

Property

Equal To Value

Property.Value("Length",0)

new ArrayList(),String.Empty

"Hello", 5

Null

Property.IsNull("InnerException")

new Exception("exception without inner exception")

new Exception("Exception with inner Exception", new Exception("Inner")

Not Null

Property.IsNotNull("InnerException")

new Exception("Exception with inner Exception", new Exception("Inner")

new Exception("exception without inner exception")

List

Is In List [the parameter is a collection that contains this value]

List.IsIn(4)

new int[]{1,2,3,4}, new int[]{4,5,6}

new object[]{"",3}

One Of [parameter equal to one of the objects in this list]

List.OneOf(new int[]{3,4,5})

3,4,5

9,1,""

Equal

List.Equal(new int[]{4,5,6})

new int[]{4,5,6}, new object[]{4,5,6}

new int[]{4,5,6,7}

Text

Starts With

Text.StartsWith("Hello")

"Hello, World", "Hello, Rhino Mocks"

"", "Bye, Bye"

Ends With

Text.EndsWith("World")

"World","Champion Of The World"

"world", "World Seria"

Contains

Text.Contains("or")

"The Horror Movie...", "Either that or this"

"Movie Of The Year"

Like [perform regular expression validation]

Text.Like("Rhino|rhino|Rhinoceros|rhinoceros" )

"Rhino Mocks", "Red Rhinoceros"

"Hello world", "Foo bar", Another boring example string"

Operator Overloading

And - operator &

Text.StartsWith("Hello") & Text.Contains("bar")

"Hello, Foobar"

"Hello, World", "Foo bar"

Or - operator |

Text.StartsWith("Hello") & Text.Contains("bar")

"Hello, Foobar", "Hello, World", "Foo bar"

"boring string"

Not - operator !

!Text.StartsWith("Hello")

"Foo bar", "index.html"

"Hello, Rhino Mocks"

Operator Overloading warning: Pay attention to operator precedence if you are using several operators in a single statement, otherwise you may get unexpected results.

Creating custom constraints: Creating you custom constraint is easy, just derive a class from AbstractConstraint and return true from the Eval() method.

Setup Result: Top

Sometimes you have a method on your mocked object where you don't care how / if it was called, you may want to set a return value (or an exception to be thrown), but for this specific test, you just don't care. For example, you may have some interaction that you already verified, or you are testing some other class and just need to get the right value from a method. The way to do it in Rhino Mocks is to use SetupResult.For(). Here is the code:

[Test]
public void SetupResultUsingOrdered()
{
  SetupResult.For(demo.Prop).Return("Ayende");
  using(mocks.Ordered())  
  {
    demo.VoidNoArgs();
    LastCall.On(demo).Repeat.Twice();
  }
  mocks.ReplayAll();
  demo.VoidNoArgs();
  for (int i = 0; i < 30; i++)
  {
    Assert.AreEqual("Ayende",demo.Prop);        
  }
  demo.VoidNoArgs();
}

When we use SetupResult.For() we tell Rhino Mocks: "I don't care about this method, it need to do X, so just do it, but otherwise ignore it." Using SetupResult.For() completely bypass the expectations model in Rhino Mocks. In the above example, we define demo.Prop to return "Ayende", and we can all it no matter in what the currently expected method is.

What about methods returning void? You would use LastCall.Repeat.Any(), which has identical semantics (ignore ordering, etc).

The reverse of setup result is to specify that this method should never be called (useful if you're using dynamic mocks), which is done like this:

Expect.Call(view.Ask(null,null)).IgnoreArguments().
  .Repeat.Never();

This has the same semantics as ExpectNoCall() in NMock and this tells the framework that any call to this method is an error. Notice that I still call IgnoreArguments(), since otherwise the expectation that this method will not be called would've been for a method call with null as both parameters. Like setup result and Repeat.Any(), using Repeat.Never() transcend ordering.

Note: If you want to have a method that can repeat any number of time, but still obey ordering, you can use: LastCall.On().Repeat.Times(0,int.MaxValue), this does obey all the normal rules.

Mocking classes: Top

Rhino Mocks supports mocking concrete classes as well as interfaces. In fact, it can even mock classes that doesn't have a default constructor! To mock a class, simply pass its type to MockRepository.CreateMock() along with any parameters for the constructor.

[Test]
public void AbuseArrayList()
{
  using(MockRepository mocks = new MockRepository())
  {
    ArrayList list = (ArrayList)mocks.CreateMock(typeof(ArrayList));
    Expect.Call(list.Capacity).Return(999);
    mocks.ReplayAll();
    Assert.AreEqual(999,list.Capacity);
  }
}

If you want to call the non default constructor, just add the parameters after the type. Like this:

ArrayList list = (ArrayList)mocks.CreateMock(typeof(ArrayList),500);

Some things to be aware of:

Limitations: Top