Here is a spec written for you. Please note that in the beforeEach() life-cycle method you need to execute the setup() method will will setup a new ColdBox request for each spec you run.

component extends="coldbox.system.testing.BaseTestCase" appMapping="/apps/MyApp"{
	
	function run(){

		describe( "Main Handler", function(){

			beforeEach(function( currentSpec ){
				// Setup as a new ColdBox request, VERY IMPORTANT. ELSE EVERYTHING LOOKS LIKE THE SAME REQUEST.
				setup();
			});

			it( "+homepage renders", function(){
				var event = execute( event="main.index", renderResults=true );
				expect(	event.getValue( name="welcomemessage", private=true ) ).toBe( "Welcome to ColdBox!" );
			});
		
		});
	}

}

The base test cases all inherit from TestBox so here are a few of the common methods you can find in every test bundle CFC (http://testbox.ortusbooks.com/content/test_bundles/index.html):

// quick assertion methods
assert( expression, [message] )
fail(message)

// bdd methods
beforeEach( body )
afterEach( body )
describe( title, body, labels, asyncAll, skip )
xdescribe( title, body, labels, asyncAll )
it( title, body, labels, skip )
xit( title, body, labels )
expect( actual )

// extensions
addMatchers( matchers )
addAssertions( assertions )

// runners
runRemote( testSpecs, testSuites, deubg, reporter );

// utility methods
console( var, top )
debug( var, deepCopy, label, top )
clearDebugBuffer()
getDebugBuffer()
print( message )
printLn( message )

// mocking methods
makePublic( target, method, newName )
querySim( queryData )
getmockBox( generationPath )
createEmptyMock( className, object, callLogging )
createMock( className, object, clearMethods, callLogging )
prepareMock( object, callLogging )
createStub( callLogging, extends, implements )
getProperty( target, name, scope, defaultValue )

ColdBox testing leverages TestBox's testing life-cycle events (http://testbox.ortusbooks.com/content/life-cycle_methods/index.html) in order to prepare the virtual ColdBox application, request context and then destroy it. For performance, a virtual application is loaded for all test cases contained within a test bundle CFC via the beforeAll() and destroyed under afterAll().

function beforeAll(){
    super.beforeAll();
    // do your own stuff here
}

function afterAll(){
    // do your own stuff here
    super.afterAll();
}

Important If you override any of these methods and do not funnel the super call, then you might get cached or unexpected results.

Improving Performance: Unloading ColdBox

The default for integration testing is that the virtual ColdBox application will be destroyed or unloaded in each test. To keep the virtual application accross requests you will need to use the unloadColdBox=false annotation or the this.unloadColdBox=false setting in your beforeAll() method. This will stop the testing classes from destroying ColdBox and improving performance.

component extends="coldbox.system.testing.BaseTestCase" unloadColdBox=false{


    function beforeAll(){
        this.unloadColdBox = false;
        super.beforeAll();
        // do your own stuff here
    }
}

Here are the annotations you can add to your testing bundle CFC.

Examples

component extends="coldbox.system.testing.BaseTestCase" appMapping="/apps/MyApp"{}

component extends="coldbox.system.testing.BaseTestCase"
    appMapping="/apps/MyApp" 
    configMapping="apps.MyApp.test.resources.Config"{}

Caution The AppMapping setting is the most important one. This is how your test connects to a location of a ColdBox application to test.

The execute() method is your way of making requests in to your ColdBox application. It can take the following parameters:

Integration Testing

We will begin our adventure with integration testing. Integration testing allows you to test a real life request to your application without using a browser. Your test bundle CFC will load a new virtual application for you to test each specification under it; all aspects of your application are loaded: caching, dependency injection, AOP, etc. Then you can target an event to test and verify its behavior accordingly. First of all, these type of tests go in your integration folder of your test harness or in the specific module folder if you are testing modules.

Basics

Here are the basics to follow for integration testing:

• Create one test bundle CFC for each event handler you would like to test or base it off your BDD requirements

• Bundle CFC inherits from coldbox.system.testing.BaseTestCase

• The bundle CFC can have some annotations that tell the testing framework to what ColdBox application to connect to and test

• Execution of the event is done via the execute() method, which returns a request context object

• Most verifications and assertions are done via the contents of the request context object (request collections)

/**
* My integration test bundle
*/
component extends="coldbox.system.testing.BaseTestCase" appMapping="/root"{

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

    function beforeAll(){
        super.beforeAll();
        // do your own stuff here
    }

    function afterAll(){
        // do your own stuff here
        super.afterAll();
    }

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

    function run(){

    }

We will explain later the life-cycle methods and the run() method where you will be writing your specs.

Hint Please refer to our BDD primer to start: http://testbox.ortusbooks.com/content/primers/bdd/index.html

CommandBox Generation

Also remember that you can use CommandBox to generate integration tests with a few simple commands:

coldbox create integration-test handler=main actions=index,save,run --open
# help
coldbox create integration-test help

Info Please also note that whenever you create a handler, interceptor or model with CommandBox it will automatically create the integration or unit test for you.

The Handler To Test

Let's use a sample event handler so we can test it:

Mocking Relocations

I can test this entire handler without me building any views yet. I can even test the relocations that happen via setNextEvent(). ColdBox will wire itself up with some mocking classes to intercept those relocations for you and place those values in the request collection for you so you can assert them. It creates a key called setnextevent in the request collection and any arguments passed to the method are also saved as keys with the following pattern:

Caution Any relocation produced by the framework via the setNextEvent method will produce some variables in the request collection for you to verify relocations.

Here is the integration test for the Main handler.

Testing Without Virtual Application

The BaseTestCase leverages an internal virtual ColdBox application so you can do integration testing. Meaning that whenever you extend from the BaseTestCase the virtual ColdBox will be loaded. You can tell the testing framework to NOT load it by using the this.loadColdBox variable:

component extends="coldbox.system.testing.BaseTestCase"{
	// Do not load the Virtual Application
	this.loadColdBox = false;
}

That's it! You will be able to use anything from the BaseTestCase but the virtual application will not be loaded.

HTTP Method Mocking

There are times when building RESTFul web services that you need to mock the incoming HTTP verb. This is done via MockBox:

function run(){

    describe( "Main Handler", function(){
    
      beforeEach(function( currentSpec ){
        setup();
      });
    
      it( "+homepage renders", function(){
        prepareMock( getRequestContext() )
    	    .$( "getHTTPMethod", "DELETE" );
        FORM.userID = 123;
        var event = execute( event = "user.delete" );
      });	
    });
}

Rendering Results

The execute() method has an argument called renderResults which defaults to false. If you pass in true then ColdBox will go through the normal rendering procedures and save the results in a request collection variable called: cbox_rendered_content and expose to you a method in the request context called getRenderedContent(). It will even work with renderData() or if you are returning RESTful information. Then you can easily assert what the content would have been for an event.

getRenderedContent()

In testing mode, the ColdBox request context event object has a convenience method called getRenderedContent() that will give you the rendered content instead of you going directly to the request context and finding the cbox_rendered_content variable.

Handler Returning Results

If you have written event handlers that actually return data, then you will have to get the values from the request collection. The following are the keys created for you in the request collection.

The handler (main.cfc)

function list(event,rc,prc){
    return "Hola Luis";
}

The spec

it( "+homepage renders", function(){
	var event = execute( event="main.list", renderResults=true );
	expect(	event.getValue( name="cbox_handler_results" ) ).toBe( "Hola Luis" );
});