Getting cfcUnit working

It's really uncomfortable now to modify or write new code without being able to unit test it. So I became very excited when I saw there is a xUnit test framework for ColdFusion called cfcUnit. I immediately went to work installing it. This wasn't quite as easy as I hoped, although most of this was my own fault (which I explain below). This post will detail how I got it installed and working.

First, a little about my environment. I'm running Windows XP and a developer version of the Cold Fusion 9 app server. I fortunately have admin rights to my box so I have full access to the wwwroot directory.

1. The cfcUnit Download page states that it only requires ColdFusion MX 6.1 to run. But on the Getting Started Documentation page it states cfcUnit is dependent on the Mach-II application framework.


2. Download MachII and unzip it into wwwroot. The version I downloaded is 1.8.0. After unzipping, the top-level directory should be MachII.


3. I wanted to verify my MachII installation was successful. Sure, I could've just tried cfcUnit but on the Mach-II installation wiki page it mentioned there is a skeleton sample application that can be used to test the installation. It turns out this isn't necessary at all and was the cause of most of my problems. MachII worked straight away, just like they state on the website, but I had a couple of issues with the skeleton application.


• Download the application from the Mach-II installation wiki page and unzip into the wwwroot directory. Note the zip file contains a duplicate skeleton hierarchy (i.e. skeleton/skeleton). To get this to work make sure you remove one layer of this, i.e. the Application.cfc file should be directly under wwwroot/skeleton.


• I couldn't find any documentation on how to use the application on the Mach-II website but there's a README file in the distribution. This says to test the application access this url: http://path_to_server/skeleton/index.cfm?event=showHome (i.e. http://localhost:8500/skeleton/index.cfm?event=showHome). But when I tried this I received the following error message: Could not find the included template /CHANGEME/views/exception.cfm.


• To fix this error, modify the skeleton/config/mach-ii.xml file. Change the value of the applicationRoot property from "/CHANGEME" to "/skeleton".


• I tried to go to the above URL again. It failed again, but this time with a different error message from Mach-II, so this must mean I'm making progress! The error was: Event-handler for event 'showHome' in module '' is not defined.


• There are 2 choices to fix this. The simplest one is to just go to /skeleton, rather than /skeleton/index.cfm?event=showHome. If you've done things right you'll get a "Skeleton Installation Success!" message. The second fix is to add an event handler for the showHome event. This is fairly simple - edit the skeleton/config/mach-ii.xml file again and search for the EVENT-HANDLERS section. Duplicate the code for the home event-handler and change the event name from "home" to "showHome". Now using the original skeleton URL should also work.


4. Now it's time to install cfcUnit. Download the zip file from the SourceForge site and unzip it into your wwwroot directory. Note, the zipfile has an extra directory layer like the skeleton application - you should have the cfcunit and org sub-directories directly in your wwwroot directory.


5. To test, go to http://path_to_server/cfcunit/. You should be shown a dialog box asking you to enter a test to run, as shown on the cfcUnit Getting Started page. Enter "org.cfcunit.tests.AllTests" and click on "Run Test". You should see all the tests succeed.

To summarize, it really was quite straight-forward to get cfcUnit working. Except for the extra directory layer in the cfcunit distribution, installing MachII and cfcUnit went as expected. I would skip installing the skeleton application.