cfcUnit on Linux

Adding a helper framework that lets you unit-test your code can speed up development and refactoring no end. With this in mind, I decided to tame a recalcitrant new Coldfusion application by installing cfcUnit on my local Linux box. It was a sufficiently awkward experience that it’s worth sharing the problems I encountered here. I should stress that the safety cfcUnit brings to your coding is definitely worth these minor difficulties, so don’t let them put you off.

1. Requirements

The documentation page for cfcUnit claims it needs both CFMX6.1 and MachII installed on the machine. In fact, the most recent version of cfcUnit (1.1.0 at time of writing) contains a “machii” subdirectory which seems to provide all the download needs (a good job, as the location of this subdirectory is hardwired into the cfcUnit code), and it all seems to work happily on CFMX7.

2. Directory structure

The zipfile contains a top-level cfcunit_1_1_0: the documentation says:

To deploy cfcUnit, simply unpack the zip file into the webroot. That’s it.

In fact, you’ll need to make sure the two subdirectories of cfcunit_1_1_0—both org and cfcunit—are at the web root, so remove that wrapper directory. Component calls within the framework rely on being able to call org.* and cfcunit.* components, and pass them round as typed function parameters. With this in mind, you should also add Coldfusion mappings in the CFIDE for these directories, as it seems some components aren’t found even with the files there.

3. Case sensitivity

Despite being included, machii still caused a further problem. Or was it actually caused by machII? See, cfcunit/index.cfm expects the (included) machII directory, whereas later on a component path beginning cfcunit.machii. is invoked. On a real operating system that understands case sensitivity you’ll need to make a symbolic link between the existing -II directory and the required -ii directory. In the cfcunit directory type:

ln -s machII machii

This should be all that’s needed to get it up and running.

Exit gracefully: other than the minor niggles above, cfcUnit was comparatively easy to download and install. Its documentation is still a bit uneven, so have Mark Drew’s handy assertion chart on a browser tab while you’re writing your tests. Despite its name, cfcUnit can be used to write functional and view-layer tests too, with a corresponding leakage of out of the confines of a rigorous testing structure. Anything you’d do in Coldfusion—ancillary CFHTTP or CFPOP calls, messing with shared scopes, creating Java or COM objects—you can of course do within a cfcUnit test, so it’s possible in theory to write bad tests. The only defence against that has always been self-honesty, though.

Because it’s so easy to write unmaintainable, undebuggable spaghetti-code in Coldfusion—it has all the potential rigour of Java, with all the potential rigour-workarounds of PHP, making it a bit like C++, I suppose—then using cfcUnit tightens up your code no end. It’s just not quite as straightforward to install on a Linux system as you’d hope.