This method is used in order to mock an internal property on the target object. Let's say that the object has a private property of userDAO that lives in the variables scope and the lifecycle for the object is controlled by its parent, in this case the user service. This means that this dependency is created by the user service and not injected by an external force or dependency injection framework. How do we mock this? Very easily by using the $property() method on the target object.

Parameters:

• propertyName - The name of the property to mock

• propertyScope - The scope where the property lives in. The default is variables scope.

• mock - The object or data to inject and mock

Not only can you mock properties that are objects, but also mock properties that are simple/complex types. Let's say you have a property in your target object that controls debugging and by default the property is false, but you want to test the debugging capabilities of your class. So we have to mock it to true now, but the property exists in variables.instance.debugMode? No problem mate (Like my friend Mark Mandel says)!

This method is used to tell MockBox that you want to mock a method with a SPECIFIC number of argument calls. Then you will have to set the return results for it, but this is absolutely necessary if you need to test an object that makes several method calls to the same method with different arguments, and you need to mock different results coming back. Example, let's say you are using a ColdBox configuration bean that holds configuration data. You make several calls to the getKey() method with different arguments:

How in the world can I mock this? Well, using the mock arguments method.

Hint So remember that if you use the $args() call, you need to tell it what kind of results you are expecting by calling the $results() method after it or you might end up with an exception.

This method can only be used in conjunction with $() as a chained call as it needs to know for what method are the results for.

The purpose of this method is to make a method return more than 1 result in a specific repeating sequence. This means that if you set the mock results to be 2 results and you call your method 4 times, the sequence will repeat itself 1 time. MUMBO JUMBO, show me!! Ok Ok, hold your horses.

As you can see, the sequence repeats itself once the call counter increases. Let's say that you have a test where the first call to a user object's isAuthorized() method is false but then it has to be true. Then you can do this:

This method is NOT injected into mock objects but avaialble via MockBox directly in order to create queries very quickly. This is a great way to simulate cfquery calls, cfdirectory or any other cf tag that returns a query.

function testGetUsers(){
    // Mock a query
    mockQuery = mockBox.querySim("id,fname,lname
    1 | luis | majano
    2 | joe | louis
    3 | bob | lainez");

    // tell the dao to return this query
    mockDAO.$("getUsers", mockQuery);
}

This is the method that you will call upon in order to mock a method's behavior and return results. This method has the capability of mocking a return value or even making the method throw a controlled exception. By default the mocked method results will be returned all the time the method is called. So if the mocked method is called twice, the results will always be returned.

any $(string method, [any returns], boolean preserveReturnType='true', [boolean throwException='false'], [string throwType=''], [string throwDetail=''], [string throwMessage=''], [boolean callLogging='false'], [boolean preserveArguments='false'], [any callback])

Parameters:

• method - The method you want to mock or spy on

• returns - The results it must return, if not passed it returns void or you will have to do the mockResults() chain

• preserveReturnType - If false, the mock will make the returntype of the method equal to ANY

• throwException - If you want the method call to throw an exception

• throwType - The type of the exception to throw

• throwDetail - The detail of the exception to throw

• throwMessage - The message of the exception to throw

• callLogging - Will add the machinery to also log the incoming arguments to each subsequent calls to this method

• preserveArguments - If true, argument signatures are kept, else they are ignored. If true, BEWARE with $args() matching as default values and missing arguments need to be passed too.

• callback - A callback to execute that should return the desired results, this can be a UDF or closure. It also receives all caller arguments as well.

• throwErrorCode - The error code to throw in the exception

The cool thing about this method is that it also returns the same instance of the object. Therefore, you can use it to chain calls to the object and do multiple mocking of methods all within the same line. Remember that if no returns argument is provided then the return is void

function beforeAll(){
    mockUser = createMock("model.security.User");

    //Mock several methods all in one shot!
    mockUser.$("isFound",false).$("isDirty",false).$("isSaved",true);
}

Examples

Let's do some samples now

//make exists return true in a mocked session object
mockSession.$(method="exists",returns=true);
expect(mockSession.exists('whatevermanKey')).toBeTrue();

//make exists return true and then false and then repeat the sequence
mockSession.$(method="exists").$results(true,false);
expect( mockSession.exists('yeaaaaa') ).toBeTrue();
expect( mockSession.exists('nada') ).toBeFalse();

//make the getVar return a mock User object
mockUser = createMock(className="model.User");
mockSession.$(method="getVar",results=mockUser);

expect( mockSession.getVar('sure') ).toBe( mockUser );

//Make the call to user.checkPermission() throw an invalid exception
mockUser.$(method="checkPermission",
        throwException=true,
        throwType="InvalidPermissionException",
        throwMessage="Invalid permission detected",
        throwDetail="The permission you sent was invalid, please try again.");

try{
    mockUser.checkPermission('invalid');
}
catch(Any e){
    if( e.type neq "InvalidPermissionException"){
      fail('The type was invalid #e.type#');
    }
}

//mock a method with call logging
mockSession.$(method="setVar",callLogging=true);
mockSession.setVar("Hello","Luis");
mockSession.setVar("Name","luis majano");
//dump the call logs
<cfdump var="#mockSession.$callLog()#">

This method is used to tell MockBox that you want to mock a method with to throw a specific exception. The exception will be thrown instead of the method returning results. This is an alternative to passing the exception in the initial $() call. In addition to the fluent API, the $throws() method also has the benefit of being able to be tied to specific $args() in a mocked object.

To continue with our getKey() example:

configBean.getKey('DebugMode'); // Exists
configBean.getKey('OutgoingMail'); // Exists
configBean.getKey('IncmingMail'); // Does not exist (see the typo?)

We want to test that keys that don't exists throw a MissingSetting exception. Let's do that using the $throws() method:

// get a mock config bean
mockConfig = getMockBox().createEmptyMock( "coldbox.system.beans.ConfigBean" );
// mock the method with args
mockConfig.$( "getKey" ).$args( "debugmode" ).$results( true );
mockConfig.$( "getKey" ).$args( "OutgoingMail" ).$results( "devmail@mail.com" );

// Here's the new $throw call
mockConfig.$( "getKey" ).$args( "IncmingMail" ).$throws( type = "MissingSetting" );

// Then you can call and get the expected results
expect( function(){
    mockConfig.getKey( "IncmingMail" );
} ).toThrow( "MissingSetting" );

Hint Remember that the $throws() call must be chained to a $() or a $args() call.

This method can help you retrieve any public or private internal state variable so you can do assertions. You can also pass in a scope argument so you can not only retrieve properties from the variables scope but from any nested structure inside of any private scope:

any $getProperty(name [scope='variables']

Parameters:

• name - The name of the property to retrieve

• scope - The scope where the property lives in. The default is variables scope.

expect( model.$getProperty("dataNumber", "variables") ).toBe( 4 );
expect( model.$getProperty("name", "variables.instance") ).toBe(  "Luis" );

Once you have created a mock object, you can use it like the real object as it will respond exactly as it was coded. However, you can override its behavior by using the mocking methods that have been placed on the mocked object at run-time. The methods that you can call upon in your object are the following (we will review them in detail later):