Getting Started with running tests on existing CF app in ColdFusion Builder 2016

I am new to testbox. I have an existing CF app in ColdFusion Builder 2016 on Windows 7 and I’d like to create some unit tests that I can run by either browsing to a url or running from a command line.
I am also somewhat new to ColdFusion Builder since I code most of the time in Visual Studio/C#/IIS).

I have a folder in my app called UnitTests. I’d like to put a bunch of unit tests in that folder and easily run them and report on them using testbox. How do I do that? Here are some details with associated questions:

I looked at Running Tests at but I am missing info on setting up folders and paths and coordinating the running of tests with my app.

For instance, I saw that the C:\Users\myUserName.CommandBox folder was set up when I ran box.exe after downloading it. This is outside my doc root which is at C:\ColdFusion2016\cfusion\wwwroot .
My project is contained under that folder, e.g. C:\ColdFusion2016\cfusion\wwwroot\MyWebProject . The UnitTests folder is under that at C:\ColdFusion2016\cfusion\wwwroot\MyWebProject\UnitTests .
I assume that I will need to create a Server Setting Mapping (virtual directory) to a folder where I can launch the testbox runner file using the CFIDE, correct?

I have created a unit test file called SimpleTest.cfc (docs don’t give an example of what to name the file but I assume it should be a .cfc) that looks like the following and I put it in the UnitTests folder:

component extends=“testbox.system.BaseSpec”{

// executes before all suites-setup
function beforeAll(){}

// executes after all suites-tear down
function afterAll(){}

// All suites go in here
//add the unit tests here
function run( testResults, testBox ){



UnitTest1() {//eventually move this to separate file in its own folder for tests in the same category of tests
describe(“Unit Test 1”, function() {
it(“contains spec with an awesome expectation”,
function() {
expect( true ).toBeTrue();
UnitTest2() {//eventually move this to separate file in its own folder for tests in the same category of tests
describe(“Unit Test 2”, function() {
it(“contains spec with an awesome expectation”,
function() {
expect( true ).toBeTrue();
I tried running the above CFC in the browser but it can’t seem to find testbox.system.BaseSpec . I also tried it with extends=“testbox.system”. How do I make sure it can find the required component(s)?

How do I configure things so I can run the unit tests in SimpleTest.cfc and see the results in the browser and from CommandBox?

Since users will often have existing CFM apps that they want to add testbox tests to, ideally the docs would contain a CF Builder sample setup where your app and testbox locations are very different and it would walk you through how to setup and run the test.
Right now, I just see bits and pieces that I am trying to weave together. If something like this exists, could you please provide a url for it?


Steve Shier

The easiest thing to look at is our ColdBox app templates. They come with a fully functioning test running. Run these commands with CommandBox in a new folder:

coldbox create app
install testbox
server open /test/runner.cfm

You can edit the contents of runner.cfm to see what it does. By default, it runs all test CFCs recursively inside your /tests/specs/ folder. Whether you need to create CF mappings for stuff is up o to you. Either way, /testbox needs to resolve to the root of the testbox install. So if it’s not in your web root, then you’ll need a mapping for it.



Thanks Brad. I was able to run the tests in the ColdBox app templates at with the following adjustment:

server open /test/runner.cfm should be
server open /tests/runner.cfm instead because the directory is called tests not test.

After that I created a mapping of /testbox to C:/Users/myUserName/Downloads/commandbox-win-3.5.0/testbox in my CF admin . How do I get it to run the tests I outlined in my original post that are in my CF app
which is under wwwrroot? commandbox is not under wwwroot.
Basically I am looking to point testbox to the tests I want to run that are not in the /tests folder under commandbox-win-3.5.0. Where is that mapping set and how do I do it?
I am assuming it is in the C:\Users\myUserName\Downloads\commandbox-win-3.5.0\testbox\tests\runner.cfm folder and is

If that is it then it is not clear to me how to set the default attribute in this cfparam tag to a directory under wwwroot which might be something like C:\ColdFusion2016\cfusion\wwwroot\MyWebProject\UnitTests. If I put default=“MyWebProject.UnitTests”, I don’t understand how testbox would know where this is.



Is there a reason you installed testbox into a folder on your hard drive that doesn’t appear to be related to the actual app you want to test? Most people install TestBox right into the actual app where the tests live. Secondly, I guess it really doesn’t matter as long as the tests are reachable via a mapping (or are part of the same web root). The default value of “tests.specs” is just the CFC instantiation path to the folder where the tests CFCs live. This really has nothing to do with TestBox at all and just boils down to the basic rules that control how CF resolves component paths.

So basically, if you have tests in “C:\randomFolder17” on your hard drive, then create a CF mapping called “/whatevs” that points there and default your to “whatevs”. That’s really all there is to it. Pls note, that variable contains a single path. If you’re trying to use the same Testbox installation to service several completely separate folders of tests, than you can call the runner with different values in the URL, or just create more than one runner file, each with a different directory value, and hit the file you wish. There’s nothing magical about the filename “runner.cfm”, it’s just what we tend to use by default.

Thanks Brad. We did not put the testbox with the app to separate concerns. Also, our app has some automatic deployment in our release process and I’d rather not release the testbox code to all our non-development environments or our production environment.

In the CF admin I created a path /unittests (what you call /whatevs) to point to the UnitTests folder (what you call C:\randomFolder17) in the app on my dev box. My cfparam tag in C:\Users\MyUserName\Downloads\commandbox-win-3.5.0\testbox\tests\runner.cfm is now

Unfortunately, the tests in the UnitTests folder in the app do not run in the url . What am I missing?


The recommended way to control your deployment is to install TestBox with Commandbox like so:
install testbox --saveDev
then ignore the entire folder in source control.

When a new developer checks out the code, they run “install”, but on your production deploys, you run “install --production” and all dev dependencies will be ignored.

Unfortunately, the tests in the UnitTests folder in the app do not run

Unfortunately you didn’t provide me with any information regarding how it “did not run” so I can’t really help :slight_smile: I’d start by reporting any error you might have received-- or at least what you see on the page when you hit the runner!

We got the tests running by copying the testbox directory from our path outside wwwroot to our app directory C:\ColdFusion2016\cfusion\wwwroot\MyWebProject as you suggested earlier and putting our unittests folder underneath C:\ColdFusion2016\cfusion\wwwroot\MyWebProject\testbox\tests. We then edited the cfparam tag in C:\ColdFusion2016\cfusion\wwwroot\MyWebProject\testbox\tests\runner.cfm so that it is:


To show all tests in the test-browser , we also needed to edit the root mapping in C:\ColdFusion2016\cfusion\wwwroot\MyWebProject\testbox\test-browser\index.cfm so that it reads

Thanks for all your help Brad.


No problem. To be clear, you didn’t put your actual tests inside the testbox framework folder, did you? I wouldn’t recommend mixing your code with a 3rd party lib. The most common arrangement is:


You can omit the entire testbox folder from your source control repo and use CommandBox to build it on your integration servers. That way, you have no custom code in that folder. Also, the test browser is sort of an alternative to the runner.cfm. I usually use one or the other. The test browser is sort of a cute little way to make it super easy to find and run your tests, once you get it setup, I usually just put all the right paths in the runner.cfm and hit it directly.