1 of 14

Testing ColdBox Applications

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 HMVC and framework code, since you can unit test your event handlers, interceptors, model objects and even do integration testing and true BDD (Behavior Driven Development) 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.

TestBox is included with all ColdBox templates.

Installing TestBox

TestBox already comes defined in the box.json of all ColdBox application templates. However, if you have a custom ColdBox app or a custom template, then you can easily install it via CommandBox:

// stable
install testbox --saveDev

// bleeding edge
install testbox@be --saveDev

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

# Watch your files and execute the tests if they change
testbox watch

# 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

Our recommendation is to do BDD and integration testing first. Unit testing is important but it is more important to verify that your requirements are met.

Resources

Test Harness

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.

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

Tip: Make sure all the same settings and configs from your root Application.cfc are replicated in your tests Application.cfc

ColdBox Testing Classes

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 unit testing
BaseInterceptorTest - Used for interceptor unit testing
BaseHandlerTest - Used for isolated handler unit testing

Common Testing Methods

BaseSpec

It is important to get familiar with TestBox before adventuring into ColdBox testing. Therefore, we suggest you reference the TestBox Docs (https://testbox.ortusbooks.com/primers/testbox-bdd-primer) or the TestBox API Docs (http://apidocs.ortussolutions.com/testbox/current). Below you can see a few of the common methods available to you.

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

// Life Cycle Methods
beforeEach( body )
afterEach( body )
aroundEach( body, spec )

// Spec Methods
describe( title, body, labels, asyncAll, skip )
xdescribe( title, body, labels, asyncAll )
fdescribe( title, body, labels, asyncAll )

feature( title, body, labels, asyncAll, skip )
xfeature( title, body, labels, asyncAll )
ffeature( title, body, labels, asyncAll )


it( title, body, labels, skip )
xit( title, body, labels )
fit( title, body, labels, skip )

// Expectations
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 )

BaseTestCase

As we have seen that our BaseTestCase inherits from the BaseSpec you get all the goodness of TestBox. However, the BaseTestCase also has a wealth of methods to assist in your testing adventures: https://apidocs.ortussolutions.com/coldbox/6.0.0/coldbox/system/testing/BaseTestCase.html

Here are some useful methods:

announce(any state, [struct data='[runtime expression]'], [boolean async='false'], [boolean asyncAll='false'], [boolean asyncAllJoin='true'], [any asyncPriority='NORMAL'], [numeric asyncJoinTimeout='0'])

// Getters
getCache(any cacheName='default')
getCacheBox() 
getController() 
getFlashScope() 
getHandlerResults() 
getInstance([any name], [struct initArguments='[runtime expression]'], [any dsl]) 
getInterceptor(any interceptorName) 
getLogBox() 
getRenderData() 
getRenderedContent() 
getRequestContext() 
getStatusCode()
getUtil()
getWireBox()

// Get Mocking Objects
getMockController() 
getMockModel(any name, [boolean clearMethods='false'])
getMockRequestContext([boolean clearMethods='false'], [any decorator])


//Reset the persistence of the unit test coldbox app, basically removes the controller from application scope. 
reset([boolean clearMethods='false'], [any decorator]) 

// Prepare a ColdBox request
setup()

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
Execution of API requests can be done via the convenience request() method or the HTTP method aliases: get(), post(), put(), patch(), head(), options()
Most verifications and assertions are done via the contents of the request context object (request collections)



it( "can do a relocation", function() {
	var event = execute( event = "main.doSomething" );
	expect( event.getValue( "relocate_event", "" ) ).toBe( "main.index" );
} );

it( "can startup executable code", function() {
	var event = execute( "main.onAppInit" );
} );

it( "can handle exceptions", function() {
	// You need to create an exception bean first and place it on the request context FIRST as a setup.
	var exceptionBean = createMock( "coldbox.system.web.context.ExceptionBean" ).init(
		erroStruct   = structNew(),
		extramessage = "My unit test exception",
		extraInfo    = "Any extra info, simple or complex"
	);
	prepareMock( getRequestContext() ).setValue(
			name    = "exception",
			value   = exceptionBean,
			private = true
		)
		.$( "setHTTPHeader" );

	// TEST EVENT EXECUTION
	var event = execute( "main.onException" );
} );

describe( "Request Events", function() {
	it( "fires on start", function() {
		var event = execute( "main.onRequestStart" );
	} );

	it( "fires on end", function() {
		var event = execute( "main.onRequestEnd" );
	} );
} );

describe( "Session Events", function() {
	it( "fires on start", function() {
		var event = execute( "main.onSessionStart" );
	} );

	it( "fires on end", function() {
		// Place a fake session structure here, it mimics what the handler receives
		URL.sessionReference     = structNew();
		URL.applicationReference = structNew();
		var event                = execute( "main.onSessionEnd" );
	} );
} );

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.

Life-Cycle Events

ColdBox testing leverages TestBox's testing life-cycle events (https://testbox.ortusbooks.com/primers/testbox-bdd-primer/life-cycle-methods) in order to prepare the virtual ColdBox application, request context and then destroy it. By default, 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 running across multiple test bundle tests 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{
    
    this.unloadColdBox = false;
    
    function beforeAll(){
        super.beforeAll();
        // do your own stuff here
    }
}

Request Setup()

Since we are simulating a browser, the testing framework needs to know when to prepare a new virtual request internally. This is achieved via the setup() method provided to us via the BaseTestCase object. This method internally will simulate a new virtual request, if NOT, every test case will be treated as if you are in the same request.

The best way to accomplish this is to leverage the beforeEach() life-cycle event method. This makes sure that each spec execution is a new virtual request.

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( "can render the homepage", function() {
			var event = this.get( "main.index" );
			expect( event.getValue( name = "welcomemessage", private = true ) ).toBe( "Welcome to ColdBox!" );
		} );
	
		it( "can render some restful data", function() {
			var event = this.post( "main.data" );
	
			debug( event.getHandlerResults() );
			expect( event.getRenderedContent() ).toBeJSON();
		} );
	});
	
}

The execute() Method

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

Name

Type

Default

Description

This method will execute any ColdBox event/route just like if it's coming from the browser or mobile app. You will get back a request context object from which you can then do assertions with it.

WARNING: Please note that this method is limited to simulating GET operations. If you are building RESTFul services, then you will need to use our discussed next.

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.

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 to assert them. ColdBox will create a variable called: cbox_handler_results and expose to you a method in the request context called getHandlerResults() so you can do your assertions.

The handler (main.cfc)

The spec

Rendering Data

If you use the renderData() method in your handler, you can also get that rendering data struct via our convenience method: getRenderData() or via the request collection private variable: cbox_renderdata.

The handler (main.cfc)

The spec

Getting The Status Code

If you are expecting status codes to do expectations against, you can use our two convenience methods:

You most likely will use the getStatusCode() as this is the one used in mocks and relocations, the other one is a RAW approach to get the underlying status code from the page context response.

Mocking Relocations

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 relocate in the request collection and any arguments passed to the method are also saved as keys with the following pattern:

The possible arguments are:

event
URL
URI
queryString
persist
persistStruct
addToken
ssl
baseURL
postProcessExempt
statusCode

Subdomain/Domain Routing

HTTP Testing Methods

If you are building RESTFul services or you want to be able to simulate requests with other HTTP verbs that are not GET, then we have created a set of methods so you can test ANY HTTP method, param and even request headers.

request()

The request() method is the method to use to simulate ANY HTTP verb operation and get a response rendered into the request context. Please note that it expects a route and not an event. This means that it will also test your URL mappings, so make sure you pass the right URL.

/**
 * Shortcut method to making a request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @method The method type to execute.  Defaults to GET.
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function request(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	string method                 = "GET",
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

get()

/**
 * Shortcut method to making a GET request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function get(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

post()

/**
 * Shortcut method to making a POST request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function post(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

put()

/**
 * Shortcut method to making a PUT request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function put(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

patch()

/**
 * Shortcut method to making a PATCH request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function patch(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

delete()

/**
 * Shortcut method to making a DELETE request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function delete(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

Examples

story( "I want to authenticate a user via username/password and receive a JWT token", function(){
	given( "a valid username and password", function(){
		then( "I will be authenticated and will receive the JWT token", function(){
			// Use a user in the seeded db
			var event = this.post(
				"/api/v1/login",
				{
					username : variables.testEmployeeEmail,
					password : variables.testPassword
				}
			);
			var response = event.getPrivateValue( "Response" );
			expect( response.getError() ).toBeFalse( response.getMessagesString() );
			expect( response.getData() ).toHaveKey( "token,user" );
			
			// debug( response.getData() );
			
			var decoded = jwt.decode( response.getData().token );
			expect( decoded.sub ).toBe( variables.testEmployeeId );
			expect( decoded.exp ).toBeGTE( dateAdd( "h", 1, decoded.iat ) );
			expect( response.getData().user.userId ).toBe( variables.testEmployeeId );
		} );
	} );
	
	given( "invalid username and password", function(){
		then( "I will receive a 401 invalid credentials exception ", function(){
			var event = this.post(
				"/api/v1/login",
				{ username : "invalid", password : "invalid" }
			);
			var response = event.getPrivateValue( "Response" );
			expect( response.getError() ).toBeTrue();
			expect( response.getStatusCode() ).toBe( 401 );
		} );
	} );
	
	given( "an invalid token", function(){
		then( "I should get an error", function(){
			// Now Logout
			var event = GET(
				"/api/v1/whoami",
				{ "x-auth-token" : "123" }
			);
			expect( event.getResponse() ).toHaveStatus( 500 );
		} );
	} );
	
} );

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. However, 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;
}

This is a great approach if you still want to leverage the base test case for unit testing but without loading the entire virtual application.

Test Annotations

Here are the annotations you can add to your testing bundle CFC to change behavior:

Examples

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

Interceptor Testing

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.

Model Object 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(){

            });


        });

    }

}

Tips & Tricks

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

HTTP Testing Methods

request()

/**
 * Shortcut method to making a request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @method The method type to execute.  Defaults to GET.
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function request(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	string method                 = "GET",
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

get()

/**
 * Shortcut method to making a GET request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function get(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

post()

/**
 * Shortcut method to making a POST request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function post(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

put()

/**
 * Shortcut method to making a PUT request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function put(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

patch()

/**
 * Shortcut method to making a PATCH request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function patch(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

delete()

/**
 * Shortcut method to making a DELETE request through the framework.
 *
 * @route The route to execute.
 * @params Params to pass to the `rc` scope.
 * @headers Custom headers to pass as from the request
 * @renderResults If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content
 * @withExceptionHandling If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. Default: false.
 * @domain                Override the domain of execution of the request. Default is to use the cgi.server_name variable.
 */
function delete(
	string route                  = "",
	struct params                 = {},
	struct headers                = {},
	boolean renderResults         = true,
	boolean withExceptionHandling = false,
	domain                        = cgi.SERVER_NAME
)

Examples

story( "I want to authenticate a user via username/password and receive a JWT token", function(){
	given( "a valid username and password", function(){
		then( "I will be authenticated and will receive the JWT token", function(){
			// Use a user in the seeded db
			var event = this.post(
				"/api/v1/login",
				{
					username : variables.testEmployeeEmail,
					password : variables.testPassword
				}
			);
			var response = event.getPrivateValue( "Response" );
			expect( response.getError() ).toBeFalse( response.getMessagesString() );
			expect( response.getData() ).toHaveKey( "token,user" );
			
			// debug( response.getData() );
			
			var decoded = jwt.decode( response.getData().token );
			expect( decoded.sub ).toBe( variables.testEmployeeId );
			expect( decoded.exp ).toBeGTE( dateAdd( "h", 1, decoded.iat ) );
			expect( response.getData().user.userId ).toBe( variables.testEmployeeId );
		} );
	} );
	
	given( "invalid username and password", function(){
		then( "I will receive a 401 invalid credentials exception ", function(){
			var event = this.post(
				"/api/v1/login",
				{ username : "invalid", password : "invalid" }
			);
			var response = event.getPrivateValue( "Response" );
			expect( response.getError() ).toBeTrue();
			expect( response.getStatusCode() ).toBe( 401 );
		} );
	} );
	
	given( "an invalid token", function(){
		then( "I should get an error", function(){
			// Now Logout
			var event = GET(
				"/api/v1/whoami",
				{ "x-auth-token" : "123" }
			);
			expect( event.getResponse() ).toHaveStatus( 500 );
		} );
	} );
	
} );

The execute() Method

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

Name

Type

Default

Description

This method will execute any ColdBox event/route just like if it's coming from the browser or mobile app. You will get back a request context object from which you can then do assertions with it.

WARNING: Please note that this method is limited to simulating GET operations. If you are building RESTFul services, then you will need to use our discussed next.

Rendering Results

Then you can easily assert what the content would have been for an event.

it( "can render users", function(){

   var event = execute( event="rest.api.users", renderResults=true );
   
   // From Value
   expect( event.getValue( "cbox_rendered_content" ) ).toBeJSON();
   // From Method
   expect( event.getRenderedContent() ).toBeJSON();
   
} );

Handler Returning Results

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 );
    
    // From value
    expect(	event.getValue( "cbox_handler_results" ) ).toBe( "Hola Luis" );
    // From Method
    expect( event.getHandlerResults() ).toBe( "Hola Luis" );
});

Rendering Data

The handler (main.cfc)

function data( event, rc, prc ){
    event.renderData( data=myService.getData(), type="json" );
}

The spec

it( "can render data", function(){
    var event = execute( event="main.data", renderResults=true );
    
    // From value
    expect(	event.getPrivateValue( "cbox_renderdata" ).type ).toBe( "json" );
    // From Method
    expect( event.getRenderData().type ).toBe( "json" );
});

Getting The Status Code

If you are expecting status codes to do expectations against, you can use our two convenience methods:

Method

Description

You most likely will use the getStatusCode() as this is the one used in mocks and relocations, the other one is a RAW approach to get the underlying status code from the page context response.

Mocking Relocations

relocate_{argumentName}

The possible arguments are:

event
URL
URI
queryString
persist
persistStruct
addToken
ssl
baseURL
postProcessExempt
statusCode

it( "can do a relocation", function() {
    var event = execute( event = "main.doSomething" );
    expect( event.getValue( "relocate_event", "" ) ).toBe( "main.index" );
} );

Subdomain/Domain Routing

If you are building multi-tenant applications with ColdBox and are leveraging , then you can easily use the domain argument to simulate the domain in play for THAT specific spec execution.

describe( "subdomain routing", function(){
	beforeEach( function(){
		setup();
	} );
	
	it( "can match on a specific domain", function(){
		var event = execute( route: "/", domain: "subdomain-routing.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.index" );
	} );
	
	it( "skips if the domain is not matched", function(){
		var event = execute( route: "/", domain: "not-the-correct-domain.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "main.index" );
	} );
	
	it( "can match on a domain with wildcards", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.show" );
	} );
	
	it( "provides any matched values in the domain in the rc", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "username" );
		expect( rc.username ).toBe( "luis" );
	} );
} );