mockBox = new testbox.system.MockBox();

// Within a TestBox Spec
getMockBox()

The factory takes in one constructor argument that is not mandatory: generationPath. This path is a relative path of where the factory generates internal mocking stubs that are included later on at runtime. Therefore, the path must be a path that can be used using cfinclude. The default path the mock factory uses is the following, so you do not have to specify one, just make sure the path has WRITE permissions:

/testbox/system/stubs

Hint If you are using Lucee or ACF10+ you can also decide to use the ram:// resource and place all generated stubs in memory.

Introduction

TestBox includes a mocking and stubbing library we lovingly call MockBox. You don't have to install it or have a separate libary, it is part of TestBox.

MockBox shines by allowing you to create mock and stub objects.

Important Setup

Write capabilities on disk for the default path of /testbox/system/testings/stubs.

You can also choose the directory destination for stub creations yourself when you initialize TestBox. If using ColdFusion 9 or Lucee you can even use ram:// and use the virtual file system.

Useful Resources

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.

The approach that we take with MockBox is a dynamic and minimalistic approach. Why dynamic? Well, because we dynamically transform target objects into mock form at runtime. The API for the mocking factory is very easy to use and provides you a very simplistic approach to mocking.

We even use $()style method calls so you can easily distinguish when using or mocking methods, properties, etc. So what can MockBox do for me?

• Create mock objects for you and keep their methods intact (Does not wipe methods, so you can do method spys, or mock helper methods)

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.

"A mock object is an object that takes the place of a 'real' object in such a way that makes testing easier and more meaningful, or in some cases, possible at all". by Scott Bain (Emergent Design )

Here are some examples of real life mocks to get you in the mocking mood:

When doing unit testing of ColdFusion CFCs, we will come to a point where a single class can have multiple external dependencies or collaborators; whether they are classes themselves, data, external APIs, etc. Therefore, in order to unit test our class exclusively and easily we need to be able to mock this behavior or have full control of this behavior. Remember that unit testing is the testing of software units in isolation. If not, we would be instantiating and creating entire set of components, frameworks, pulling network plugs and so much more ridiculous but functional things just to test one single piece of functionality and/or behavior. So in summary, mock objects are just test oriented replacements for collaborators and dependencies.

In order to create a stub object you will use the : createStub() method.

public any createStub([boolean callLogging='true'], [extends], [implements])

Parameters:

• callLogging - Add method call logging for all mocked methods

• extends - Make the stub extend from certain CFC

• implement - Make the stub adhere to an interface(s)

This method will create an empty stub object that you can use and mock with methods and properties. It can then be used in any code to satisfy dependencies meanwhile you build them. This is great to start working on projects where you are relying on other teams to build functionality but you have agreed on specific data or code interfaces. It is also super fancy as it can allow you to tell the stub to inherit from another CFC and look like it, or even pass in one or more interfaces that it must implement. If they are interfaces, then MockBox will generate all the necessary methods to satisfy those interfaces.

CreateStub() Inheritance

The createStub() method has an argument called extends that accepts a class path. This will create and generate a stub that physically extends that class path directly. This is an amazing way to create stubs that you can override with inherited functionality or just make it look like it is EXACTLY the type of object you want.

CreateStub() Interfaces

The createStub() method has an argument called implements that accepts a list of interface class paths you want the stub to implement. MockBox will then generate the stub and it will make sure that it implements all the methods the interfaces have defined as per their contract. This is such a fantastic and easy way to create a stub that looks and feels and actually has the methods an interface needs.

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.

any $property(string propertyName, [string propertyScope='variables'], any mock)

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)!

MockBox now supports a $spy( method ) method that allows you to spy on methods with all the call log goodness but without removing all the methods. Every other method remains intact, and the actual spied method remains active. We decorate it to track its calls and return data via the $callLog() method.

Example of CUT:

void function doSomething(foo){
  // some code here then...
  local.foo = variables.collaborator.callMe(local.foo);
  variables.collaborator.whatever(local.foo);
}

Example Test:

function test_it(){
  local.mocked = createMock( "com.foo. collaborator" )
    .$spy( "callMe" )
    .$spy( "whatever" );
  variables.CUT.$property( "collaborator", "variables", local.mocked );
  assertEquals( 1, local.mocked.$count( "callMe" ) );
  assertEquals( 1, local.mocked.$count( "whatever" ) );
}

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.

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

Examples

Let's do some samples now

Once you have created a mock object, you can use it like the real object, which will respond exactly as it was coded. However, you can override its behavior by using the mocking methods 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):

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 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:

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

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!

Parameters:

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

Examples:

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

Parameters:

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

Examples:

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.

Now you have seen the power of the MockBox! A minimalistic and simplistic approach to mocking and stubbing for ColdFusion (CFML) applications. Welcome to the world of Mocks!!

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()#">

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.

Parameters:

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

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

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();
});

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.

In order to create a mock object you need to use any of the following methods: createMock(), createEmptyMock(), or prepareMock().

createMock()

Used to create a new mock object from scratch or from an already instantiated object.

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

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

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();

The Collaborator

The premise of a collaborator is that it is an object that collaborates with another object for some purpose. Usually this is a dependency of some sort. Now, you can have a collaborator that is injected into the target object by some form of dependency injection, or it is created by the target object. Either way, you need to be able to mock the behavior of this collaborator object. The latter approach is much harder to test because you are doing a createObject() call. However, you need to put into practice your testable and refactor skills to work, in order to make this more testable. Thanks Marc Esher!

Example:

The source above is too hard to test because you have no control over the create object call. Therefore you can have two solutions for this, which actually makes your code more testable.

1. Have a method return to you an instance of the Validator object.

2. Have the Validator object be injected via dependency injection into your target object.

Most of the time collaborators can be injected by dependency injection, but sometimes they will not as they are only in use by the target object. So let's do both approaches, starting with dependency injection via annotations: cfproperty.

Now that we have a annotation injection or a setter injection, let's mock the collaborator into our target object with the mocked method for isValid email.

There you go. Now let's refactor our method call:

As you can see, even our method look cleaner and sharper thanks to our refactoring. However, the most important aspect of our refactoring is that now we can mock the collaborator.

Method Spies

The premise of method spies is that you want to mock the return of method calls inside the target object that we are testing because these methods are helper methods. Also, maybe these helper methods have an access type of private which we cannot mock directly. Here is a typical example in one of my security objects:

Ok, this simple liner security validator throws tons of problems. Why? Well, I have three internal private calls:

• getUserSession() - supposed to return a nice user object

• isSSOCookieValid() - checks if a single sign on cookie is set

• authorizeUser() - Authorize a user in my system

Since I am unit testing this target object's userValidator method, I don't really care about the method calls, I just worry about the behavior that is associated with them because my other tests will go into detail about what they do. However, for my purposes of testing the userValidator method, I just need behavior. Thus, we need to be able to create mocking representations of these methods.

As you can see from the example above, I mocked all the necessary data and objects to test all the paths that I could follow in my userValidator method. Now we are cooking with MockBox.

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: