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.

Available assertions in cfcUnit

The documentation for cfcUnit is a little light. One of the first things I tried after going through the Getting Started with cfcUnit page on the cfcUnit site was doing an assertEquals. When I ran my test I got the error "Variable ASSERTEQUALS is undefined". So where's the list of available assertions? I couldn't find it so I went to the code. In org/cfcunit/framework/Assert.cfc I found the following available assertions:

• assertArrayContainsNumber
• assertArrayContainsString
• assertComplexValue
• assertComponent
• assertContainsString
• assertEqualsArray
• assertEqualsBoolean
• assertEqualsNumber
• assertEqualsQuery
• assertEqualsString
• assertEqualsStruct
• assertFalse
• assertNotNull
• assertNotNullComponent
• assertNotRegexMatch
• assertNotSameComponent
• assertNotSameStruct
• assertNull
• assertNullComponent
• assertObject
• assertRegexMatch
• assertSameComponent
• assertSameStruct
• assertSimpleValue
• assertTrue

Not an assertion, but fail can also be used to fail a test case.

Update: After coming up with this list I found this site that contains the assertions, many with descriptions. Why I didn't find it earlier??

Good times with Cold Fusion

My current position has me enhancing a number of applications, many of them written in Cold Fusion. I'll be honest, I'm very new to CF and wasn't all that excited about learning it until I discovered some cool frameworks like cfcUnit and ColdSpring. It makes sense there would be these types of frameworks since CF is built on top of Java, it just took me a while to discover them! I hope to do some posts on my experiences with these frameworks.