1.3.2. Visitable Mock Objects

1.3.2. Visitable Mock Objects
Prev	1.3. Advanced Expectations	Next

To obtain a visitable mock object you must:

Derive and define your object with the methods you need
Create a helper object for each method and set up the behaviour
Activate and use the object

1.3.2.1. Using Macros

The following listing contains a short example and explains the basic features when using macros.


  class MyInterfaceClass 
  {
    public:

     virtual int access(unsigned &index) = 0;
  };

  class MyVisitableMockObject : public VisitableMockObject,  
                                public MyInterfaceClass
  {
    public:

      MyVisitableMockObject(const String &name)
        : VisitableMockObject(name, 0)
        , MOCKPP_CONSTRUCT_MEMBERS_FOR_VISTABLE1(access) 
      {}

      MOCKPP_VISITABLE1(MyVisitableMockObject, int, access, unsigned); 
  };

  MyVisitableMockObject mvo("mvo");

  MOCKPP_CONTROLLER_FOR(MyVisitableMockObject, access) ctr (&mvo); 

  ctr.addThrowable(std::string("throw"), 2); 
  ctr.addResponseValue(1, 13); 
  ctr.addResponseValue(2, 37);
  ctr.addResponseValue(3, lt(50u)); 

  mvo.access(1); 
  mvo.access(13);
  mvo.access(lt(123u)); 

  mvo.activate(); 

  // use the object

  mvo.verify();

	Define your interface class.
	Derive your mock object class from `VisitableMockObject` and the interface class.
	According to the type of method and the number of parameters it takes add a macro that does the construction part for all the necessary internal helper variables for that method.
	Similarly add another macro that implements the method with its internal variables and helper methods.
	Create a controller object for the method to set up its behaviour.
	Add some behaviour: tell the object to throw an exception when called the first and second time.
	More specific behaviour: depending on the parameters passed it shall respond with certain return values.
	The former controller parameters where strict and demanded exact equality. By using constraint objects it is possible to use arbitrary tolerance. In the example the parameter must be less than 50 to return 3.
	Describe the expected execution path and the expected parameters for the method how it shall happen in your test later. This is simply done by calling the methods.
	Demands that the parameter value is less than 123 by using an appropriate constraint object.
	Activate the object and use it in the tests.
	After the tests have completed verify all conditions that are still pending, for example unused return values or exceptions.

For a deeper documentation of the methods involved with a controller see the api documentation of VisitableMockObject::Controller.

1.3.2.2. Using Mock Method Templates

The second approach with mock method templates is almost the same as before. The difference is to replace the macros and the resulting controller object with the method object and forward the call to it.


  class MyVisitableMockObject : public VisitableMockObject,
                                public MyInterfaceClass
  {
    public:

      MyVisitableMockObject(const String &name)
        : VisitableMockObject(name, 0)
        , access_mocker("access", this) 
      {}

      virtual int access(unsigned index) 
      {
        return access_mocker.forward(index);
      }

      virtual void access(const ConstraintHolder<unsigned> &p) const 
      {
        return access_mocker.forward(p);
      }

      VisitableMockMethod1<int, unsigned> access_mocker; 
  };

  MyVisitableMockObject mvmo("mvmo");

  VisitableMockMethod1<int, unsigned> &ctr (mvmo.access_mocker); 

  ctr.addThrowable(std::string("throw"), 2);
  ctr.addResponseValue(1, 13);
  ctr.addResponseValue(2, 37);
  ctr.addResponseValue(3, eq(50u)); 

  mvmo.access(1);
  mvmo.access(13);
  mvmo.access(eq(123));

  mvmo.activate();

  // use the object

  mvmo.verify();

	Construct the mock method helper object.
	Provide the method as entry point and forward the call to the method which does the actual work.
	If you want to benefit from constraints you have to provide an overloaded method which forwards the constraint holder. This method has always return type void and should be const. Of course you can call this method only in record mode.
	Instantiate a mock method variable. Select the class according to the parameters the method takes. There is also a template without a trailing number which handles an arbitrary parameter count.
	For convenience create a reference to the mock method helper.
	Set up the mock objects behaviour in the same manner as described above using the macros.

1.3.2.3. Dispatching Order

The expectations are evaluated in the following order which of course also depends on the method definition itself. Parameters to the method can only be evaluated if they exist and void methods obviously can't return any objects.

verify that the expected method is called
find and throw an exception based on the parameters passed
if available: throw the next exception from the list created with addThrowable()
throw the default exception if defined
verify the values of the parameters passed
find and return an object based on the parameters passed
if available: return the next object from the list created with addReturnValue()
return the default object

There is a subtle difference in the behaviour of versions before 1.2.x which affects topics 3. and 7. in the above list. Older versions always checked if there is an exception available and threw them in the call. Newer version on the contrary use the order from the sources.

For example take the following code fragment:


  mock.addThrowable(xx);
  mock.addReturnValue(aa);
  mock.addThrowable(yy);
  mock.addReturnValue(bb);

In this case older versions would behave as follows:

throw(xx)
throw(yy)
return(aa)
return(bb)

Newer versions on the other hand will do what is written in the code:

throw(xx)
return(aa)
throw(yy)
return(bb)

If your code relies on the old behaviour you can switch back by calling unsetThrowablesInline(). This method is available for the controller object and only influences the according method. Additionally the method is also available in the container mock object itself and affects all registered sub-objects.