One of the best things you can do when you develop software applications is TEST! I know nobody likes it, but hey, you need to do it right? With the advocation of frameworks today, you get all these great tools to build your software applications, but how do you test your framework code. ColdBox has revolutionized testing MVC and framework code, since you can unit test your event handlers, interceptors, model objects and even do integration testing and test your entire application with no browser at all.

ColdBox has already all the hooks in place to provide Behavior and Test Driven Development via TestBox and mocking/stubbing capabilities via MockBox.

TestBox is a testing framework for ColdFusion (CFML) that is based on BDD (Behavior Driven Development) for providing a clean obvious syntax for writing tests. It also includes MockBox for mocking and stubbing.

Installing TestBox

So let's get started by opening a CommandBox prompt (box) in your application root and installing TestBox.

// stable
install testbox --saveDev

// bleeding edge
install testbox@be --saveDev

Info The --saveDev flag tells CommandBox to save TestBox locally only for testing purposes as it will not be used to send TestBox for production (http://commandbox.ortusbooks.com/content/packages/dependencies.html)

Please also note that CommandBox ships with tons of commands for interacting with TestBox and ColdBox testing classes. You can explore them by issuing the following commands or viewing the latest CommandBox API Docs (http://apidocs.ortussolutions.com/commandbox/current)

# testbox namespace help
testbox help

# generations
testbox create help

# run tests
testbox run help

# coldbox creation help
coldbox create help

Benefits

It might be that testing is tedious and takes time to get into the flow of Behavior/Test Driven Development. However, there are incredible benefits to testing:

• Can improve code quality

• Quick error discovery

• Code confidence via immediate verification

• Can expose high coupling

• Encourages refactoring to produce testable code

• Testing is all about behavior and expectations

Resources

• Wikipedia - http://en.wikipedia.org/wiki/Unit_test

• TestBox - http://ortussolutions.com/products/testbox

• TestBox BDD Book - http://testbox.ortusbooks.com

• ColdFusion Builder TestBox Extensions - http://forgebox.io/view/coldbox-platform-utilities

• Sublime TestBox Extension - https://github.com/lmajano/cbox-coldbox-sublime

• VSCode TestBox Extension - https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-testbox

Every ColdBox application template comes with a nice test harness inside of a tests folder.

Here is a breakdown of what it contains:

• Application.cfc - A unique application file for your test harness. It should mimic exactly the one in your root application folder

• resources - Some basic testing resources or any of your own testing resources

• results - Where automated results are archived

• runner.cfm - The HTML runner for your test bundles

• specs - Where you will be writing your testing bundle specs for integration testing, unit testing and module testing.

• test.xml - Your ANT runner

Application.cfc

The Application.cfc for your tests is extremly important as it should mimic your applications real Application.cfc.

component{

    // APPLICATION CFC PROPERTIES
    this.name                 = "ColdBoxTestingSuite" & hash(getCurrentTemplatePath());
    this.sessionManagement     = true;
    this.sessionTimeout     = createTimeSpan( 0, 0, 15, 0 );
    this.applicationTimeout = createTimeSpan( 0, 0, 15, 0 );
    this.setClientCookies     = true;

    // Create testing mapping
    this.mappings[ "/tests" ] = getDirectoryFromPath( getCurrentTemplatePath() );
    // Map back to its root
    rootPath = REReplaceNoCase( this.mappings[ "/tests" ], "tests(\\|/)", "" );
    this.mappings["/root"]   = rootPath;

}

Please note that we provide already a mapping to your root application via /root. We would recommend you add any ORM specs here or any other mappings here as well.

Before we begin our adventures in testing, let's review what classes does ColdBox give you for testing and where you can find them. From the diagram you can see that our pivot class for testing is the TestBox BaseSpec class.

From that super class we have our own ColdBox BaseTestCase which is our base class for any testing in ColdBox and the class used for Integration Testing. We then spawn several child classes for targeted testing of different objects in your ColdBox applications:

• BaseTestCase - Used for Integration Testing

• BaseModelTest - Used for model object testing

• BaseInterceptorTest - Used for interceptor testing

• BaseHandlerTest - Used for isolated handler testing

You can test all your model objects directly with no need of doing integration testing. This way you can unit test model objects very very easily using great mocking capabilities. All you need to do is the following:

coldbox create model-test path=models.UserService methods=save,list,search --open

This testing support class will create your model object, and decorate with mocking capabilities via MockBox and create some mocking classes you might find useful in your model object unit testing. The following are the objects that are placed in the variables scope for you to use:

• model : The target model object to test

• mockLogger : A mock logger class

• mockLogBox : A mock LogBox class

• mockCacheBox : A mock Cache Factory class

• mockWireBox : A mock WireBox Injector class

Caution We do not initialize your model objects for you. This is your job as you might need some mocking first.

Basic Setup

/**
* The base model test case will use the 'model' annotation as the instantiation path
* and then create it, prepare it for mocking and then place it in the variables scope as 'model'. It is your
* responsibility to update the model annotation instantiation path and init your model.
*/
component extends="coldbox.system.testing.BaseModelTest" model="UserService"{

    /*********************************** LIFE CYCLE Methods ***********************************/

    function beforeAll(){
        // setup the model
        super.setup();        

        // init the model object
        model.init();
    }

    function afterAll(){
    }

    /*********************************** BDD SUITES ***********************************/

    function run(){

        describe( "UserService Suite", function(){

            it( "should save", function(){

            });

            it( "should search", function(){

            });

            it( "should list", function(){

            });


        });

    }

}

Here are some useful tips for you when doing testing with ColdBox Applications:

• If you are using relative paths in your application, you might encounter problems since the running application is different from the test application. Try to always use paths based on the application's AppMapping

• Always use setNextEvent() for relocations so they can be mocked

• Leverage querySim() for query mocking

• Leverage for mocking and stubbing

• Integration tests are NOT the same as handler tests. Handler tests will just test the handler CFC in isolation, so it will be your job to mock everything around it.

• You can extend the coldbox.system.testing.BaseModelTest to test any domain object

• The has over 5,000 tests, mocking scripts and more for you to learn from

You can test interceptors directly with no need of doing integration testing via the BaseInterceptorTest. This way you can unit test interceptors in isolation. All you need to do is the following:

This testing support class will create your interceptor, and decorate with mocking capabilities via MockBox and mock all the necessary companion objects around interceptors. The following are the objects that are placed in the variables scope for you to use:

• interceptor : The target interceptor to test

• mockController : A mock ColdBox controller in use by the target interceptor

• mockRequestService : A mock request service object

• mockLogger : A mock logger class in use by the target interceptor

• mockLogBox : A mock LogBox class in use by the target interceptor

• mockFlash : A mock flash scope in use by the target interceptor

All of the mock objects are essentially the dependencies of interceptor objects. You have complete control over them as they are already mocked for you.