> For the complete documentation index, see [llms.txt](https://coldbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox.ortusbooks.com/the-basics/testing-quick-start/test-harness.md). # Test Harness The ColdBox test harness — the tests folder with Application.bx, runner, resources, and specs directories. Every ColdBox application template comes with a nice test harness inside of a `tests` folder.

Test Harness

File/FolderDescription
Application.bx (or .cfc for CFML)A unique application file for your test harness. It should mimic exactly the one in your root application folder
resourcesSome basic testing resources or any of your own testing resources
runner.bxm (or .cfm for CFML)The HTML runner for your test bundles
specsWhere you will write your testing bundle specs for integration, unit, and module testing, try to use the convention of {name}Spec.bx or {name}Test.bx (or .cfc for CFML)
test.xmlA TestBox ANT runner
## Application.bx (or .cfc for CFML) The `Application.bx` (or `.cfc` for CFML) for your tests is extremely important as it should mimic your applications real `Application.bx` (or `.cfc` for CFML). {% tabs %} {% tab title="BoxLang" %} ```js /** * Copyright 2005-2007 ColdBox Framework by Luis Majano and Ortus Solutions, Corp * www.ortussolutions.com * --- */ class { // APPLICATION CLASS PROPERTIES this.name = "ColdBoxTestingSuite"; this.sessionManagement = true; this.setClientCookies = true; this.sessionTimeout = createTimespan( 0, 0, 15, 0 ); this.applicationTimeout = createTimespan( 0, 0, 15, 0 ); this.whiteSpaceManagement = "smart"; this.enableNullSupport = shouldEnableFullNullSupport(); /** * -------------------------------------------------------------------------- * Location Mappings * -------------------------------------------------------------------------- * - cbApp : Quick reference to root application * - coldbox : Where ColdBox library is installed * - testbox : Where TestBox is installed */ // Create testing mapping this.mappings[ "/tests" ] = getDirectoryFromPath( getCurrentTemplatePath() ); // The root application mapping rootPath = reReplaceNoCase( this.mappings[ "/tests" ], "tests(\\|/)", "" ); this.mappings[ "/root" ] = this.mappings[ "/cbapp" ] = rootPath; this.mappings[ "/coldbox" ] = rootPath & "coldbox"; this.mappings[ "/testbox" ] = rootPath & "testbox"; /** * Fires on every test request. It builds a Virtual ColdBox application for you * * @targetPage The requested page */ public boolean function onRequestStart( targetPage ){ // Set a high timeout for long running tests setting requestTimeout ="9999"; // New ColdBox Virtual Application Starter request.coldBoxVirtualApp= new coldbox.system.testing.VirtualApp( appMapping = "/root" ); // If hitting the runner or specs, prep our virtual app if ( getBaseTemplatePath().replace( expandPath( "/tests" ), "" ).reFindNoCase( "(runner|specs)" ) ) { request.coldBoxVirtualApp.startup(); } // Reload for fresh results if ( structKeyExists( url, "fwreinit" ) ) { if ( structKeyExists( server, "lucee" ) ) { pagePoolClear(); } // ormReload(); request.coldBoxVirtualApp.restart(); } return true; } /** * Fires when the testing requests end and the ColdBox application is shutdown */ public void function onRequestEnd( required targetPage ){ request.coldBoxVirtualApp.shutdown(); } private boolean function shouldEnableFullNullSupport(){ var system = createObject( "java", "java.lang.System" ); var value = system.getEnv( "FULL_NULL" ); return isNull( value ) ? false : !!value; } } ``` {% endtab %} {% tab title="CFML" %} ```cfscript /** * Copyright 2005-2007 ColdBox Framework by Luis Majano and Ortus Solutions, Corp * www.ortussolutions.com * --- */ component { // APPLICATION CLASS PROPERTIES this.name = "ColdBoxTestingSuite"; this.sessionManagement = true; this.setClientCookies = true; this.sessionTimeout = createTimespan( 0, 0, 15, 0 ); this.applicationTimeout = createTimespan( 0, 0, 15, 0 ); this.whiteSpaceManagement = "smart"; this.enableNullSupport = shouldEnableFullNullSupport(); /** * -------------------------------------------------------------------------- * Location Mappings * -------------------------------------------------------------------------- * - cbApp : Quick reference to root application * - coldbox : Where ColdBox library is installed * - testbox : Where TestBox is installed */ // Create testing mapping this.mappings[ "/tests" ] = getDirectoryFromPath( getCurrentTemplatePath() ); // The root application mapping rootPath = reReplaceNoCase( this.mappings[ "/tests" ], "tests(\\|/)", "" ); this.mappings[ "/root" ] = this.mappings[ "/cbapp" ] = rootPath; this.mappings[ "/coldbox" ] = rootPath & "coldbox"; this.mappings[ "/testbox" ] = rootPath & "testbox"; /** * Fires on every test request. It builds a Virtual ColdBox application for you * * @targetPage The requested page */ public boolean function onRequestStart( targetPage ){ // Set a high timeout for long running tests setting requestTimeout ="9999"; // New ColdBox Virtual Application Starter request.coldBoxVirtualApp= new coldbox.system.testing.VirtualApp( appMapping = "/root" ); // If hitting the runner or specs, prep our virtual app if ( getBaseTemplatePath().replace( expandPath( "/tests" ), "" ).reFindNoCase( "(runner|specs)" ) ) { request.coldBoxVirtualApp.startup(); } // Reload for fresh results if ( structKeyExists( url, "fwreinit" ) ) { if ( structKeyExists( server, "lucee" ) ) { pagePoolClear(); } // ormReload(); request.coldBoxVirtualApp.restart(); } return true; } /** * Fires when the testing requests end and the ColdBox application is shutdown */ public void function onRequestEnd( required targetPage ){ request.coldBoxVirtualApp.shutdown(); } private boolean function shouldEnableFullNullSupport(){ var system = createObject( "java", "java.lang.System" ); var value = system.getEnv( "FULL_NULL" ); return isNull( value ) ? false : !!value; } } ``` {% endtab %} {% endtabs %} Please note that we provide already a mapping to your root application via `/root` and a mapping to the tests themselves via `/tests` . We recommend you add any ORM specs or any other mappings here. {% hint style="success" %} **Tip:** Make sure all the same settings and configs from your root `Application.bx` (or `.cfc` for CFML) are replicated in your tests `Application.bx` (or `.cfc` for CFML) {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://coldbox.ortusbooks.com/the-basics/testing-quick-start/test-harness.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.