1 of 10

Verification Methods

The following methods are also mixed in at run-time into mock objects and they will be used to verify behavior and calls from these mock/stub objects. These are great in order to find out how many mocked methods calls have been made and to find out the arguments that where passed to each mocked method call.

$count()

Get the number of times a method has been called or the entire number of calls made to ANY mocked method on this mock object. If the method has never been called, you will receive a 0. If the method does not exist or has not been mocked, then it will return a -1.

numeric $count([string methodName])

Parameters:

methodName - Name of the method to get the counter for (Optional)

mockUser = getMockBox().createMock("model.User");
mockUser.$("isAuthorized").$results(false,true);

debug(mockUser.$count("isAuthorized"));
//DUMPS 0

mockUser.isAuthorized();
debug(mockUser.$count("isAuthorized"));
//DUMPS 1

mockUser.isAuthorized();
debug(mockUser.$count("isAuthorized"));
//DUMPS 2

// dumps 2 also
debug( mockUser.$count() );

$times() or $verifyCallCount()

This method is used to assert how many times a mocked method has been called or ANY mocked method has been called.

Boolean $times(numeric count, [methodname])

Parameters:

count - The number of times any method or a specific mocked method has been called
methodName - The optional method name to assert the number of method calls

Examples

security = getMockBox().createMock("model.security");

//No calls yet
expect( security.$times(0) ).toBeTrue();

security.$("isValidUser",false);
security.isValidUser();

// Asserts
expect( security.$times(1) ).toBeTrue();
expect( security.$times(1,"isValidUser") ).toBeTrue();

security.$("authenticate",true);
security.authenticate("username","password");

expect( security.$times(2) ).toBeTrue();
expect( security.$times(1,"authenticate") ).toBeTrue();

$never()

This method is a quick notation for the $times(0) call but more expressive when written in code:

Boolean $never([methodname])

Parameters:

* methodName - The optional method name to assert the number of method calls

Examples:

security = getMockBox().createMock("model.security");

//No calls yet
expect( security.$never() ).toBeTrue();

security.$("isValidUser",false);
security.isValidUser();

// Asserts
expect( security.$never("isValidUser") ).toBeFalse();

$atLeast()

This method can help you verify that at least a minimum number of calls have been made to all mocked methods or a specific mocked method.

Boolean $atLeast(minNumberOfInvocations,[methodname])

Parameters:

minNumberOfInvocations - The min number of calls to assert
methodName - The optional method name to assert the number of method calls

// let's say we have a service that verifies user credentials
// and if not valid, then tries to check if the user can be inflated from a cookie
// and then verified again
function verifyUser(){

    if( isValidUser() ){
        log.info("user is valid, doing valid operations");
    }

    // check if user cookie exists
    if( isUserCookieValid() ){
        // inflate credentials
        inflateUserFromCookie();
        // Validate them again
        if( NOT isValidUser() ){
            log.error("user from cookie invalid, aborting");
        }
    }
}

// Now the test
it( "can verify a user", function(){
    security = createMock("model.security").$("isValidUser",false);
    security.storeUserCookie("invalid");
    security.verifyUser();

    // Asserts that isValidUser() has been called at least 5 times
    expect( security.$atLeast(5,"isValidUser") ).toBeFalse();
    // Asserts that isValidUser() has been called at least 2 times
    expect( security.$atLeast(2,"isValidUser") ).toBeFalse();
});

$once()

This method can help you verify that only ONE mocked method call has been made on the entire mock or a specific mocked method. Useful alias!

Boolean $once([methodname])

Parameters:

methodName - The optional method name to assert the number of method calls

Examples:

// let's say we have a service that verifies user credentials
// and if not valid, then tries to check if the user can be inflated from a cookie
// and then verified again
function verifyUser(){

    if( isValidUser() ){
        log.info("user is valid, doing valid operations");
    }

    // check if user cookie exists
    if( isUserCookieValid() ){
        // inflate credentials
        inflateUserFromCookie();
        // Validate them again
        if( NOT isValidUser() ){
            log.error("user from cookie invalid, aborting");
        }
    }
}

// Now the test
it( "can verify a user", function(){
    security = getMockBox().createMock("model.security").$("isValidUser",false);
    security.storeUserCookie("valid");
    security.verifyUser();

    expect( security.$once("isValidUser") ).toBeTrue();
});

$atMost()

This method can help you verify that at most a maximum number of calls have been made to all mocked methods or a specific mocked method.

Boolean $atLeast(minNumberOfInvocations,[methodname])

Parameters:

maxNumberOfInvocations - The max number of calls to assert
methodName - The optional method name to assert the number of method calls

Examples:

// let's say we have a service that verifies user credentials
// and if not valid, then tries to check if the user can be inflated from a cookie
// and then verified again
function verifyUser(){

    if( isValidUser() ){
        log.info("user is valid, doing valid operations");
    }

    // check if user cookie exists
    if( isUserCookieValid() ){
        // inflate credentials
        inflateUserFromCookie();
        // Validate them again
        if( NOT isValidUser() ){
            log.error("user from cookie invalid, aborting");
        }
    }
}

// Now the test
it( "can verify a user", function(){
    security = createMock("model.security").$("isValidUser",false);
    security.storeUserCookie("valid");
    security.verifyUser();

    // Asserts that isValidUser() has been called at most 1 times
    expect( security.$atMost(1,"isValidUser") ).toBeFalse();
});

$callLog()

This method is used to retrieve a structure of method calls that have been made on mocked methods of the mock object. This is extermely useful when you want to assert that a certain method was called with the appropriate arguments. Great for testing method calls that save or update data to some kind of persistent storage. Also great to find out what was the state of the data of a call at certain points in time.

Each mocked method is a key in the structure that contains an array of calls. Each array element can have 0 or more arguments that are traced when methods where called with arguments. If they where made with ordered or named arguments, you will be able to know the difference. We recommend dumping out the structure to check out its composition.

struct $callLog()

Examples:

security = getMockBox().createMock("model.security");
//Call methods on it that perform something, but mock the saveUserState method, it returns void
security.$("saveUserState");

//get the call log for this method
userStateLog = security.$callLog().saveUserState;
expect( arrayLen(userStateLog) eq 0 ).toBeTrue();

$reset()

This method is a utility method used to clear out all call logging and method counters.

void $reset()

security = getMockBox().createMock("model.security").$("isValidUser", true);
security.isValidUser( mockUser );

// now clear out all call logs and test again
security.$reset();
mockUser.$property("authorized","variables",true);
security.isValidUser( mockUser );

$debug()

This method is used for debugging purposes. If you would like to get a structure of all the mocking internals of an object, just call this method and it will return to you a structure of data that you can dump for debugging purposes.

<cfdump var="#targetObject.$debug()#">