How to Use CFUnit-Ant

CFUnit-Ant is an extention to the Apache Ant Java-based build tool. CFUnit-Ant can be used anyway the core Ant tool can, but this article will illustrate how to configure CFEclipse to automatically execute CFUnit-Ant builds upon saving a CFML resource.

Two things must be installed to follow the below instructions.

CFEclipse (which requires Eclipse) - Follow the instructions on the CFEclipse site
CFUnit-Ant JAR - Just download it from the CFUnit project web site to anywhere on your local machine.

For each project you will need to create a build files (or more then one of you like). These are XML files which are used to pass instructions to Ant on what to tasks to execute. To include CFUnit-Ant tasks, you simply need define the task using the "taskdef" ant command, as follows:

build.xml

<?xml version="1.0"?>

<project name="CFUnit" default="main" basedir=".">
	<taskdef name="CFUnit" classname="net.sourceforge.cfunit.ant.CFUnit"/>
	
	<property name="domain" value="http://localhost/" />
	
	<target name="main">
		<CFUnit testcase="${domain}CFUnitExample/test/MyCFCTest.cfc" verbose="true" />
	</target>
</project>

In this example, Ant will execute the "MyCFCTest" test case, which is just a normal test case CFC (see the CFUnit primer for more information on test cases).

Once the build file is created, add it as a "builder" to the project. To do this:

Right click the project and click "properties" (or select "Project" > "Properties" in the tool bar)
Select "Builders" along the left of the properties window, and then click the "New" button
Select "Ant Build", and click "OK"
Give the builder a name in the "Name:" field.
In the "Buildfile" field, enter the location of your build XML file using the "Browse Workspace..." button
Go to the "Targets" Tab, select "Set Targets" button beside the "Auto Build:" section. You can either just click OK (to accept the default target) or select an alternative target.
Select the "Classpath" tab, and click the "Add External JARs..." button (may need to click the "User Entry" icon first to enable the button) *
Browse to the location you downloaded the CFUnit-Ant JAR too, and click the "Open" button *
Select the "Build Options" tab, and check off "Specify working set of relevant resources"
Click the "Specify Resources..." button, and select the resources you would like this builder to be associated with. You can either specify specific files, or entire directories, or both.

* - If you place the CFUnit-Ant files to your system's java classpath, these steps will not be required.

Once finished, anytime any of the selected resources are modified, the builder will automatically be run. The results will reported in the "Console" panel. By default, if there is a failure, an alert will pop up (that can be disabled).

Extras

CFUnit-Ant also reports the test cases it runs by URL in the console. If there is a failure, you can copy/paste that URL into a browser to view the results through a browser. You can optionally add "&html=yes" to that URL to format the results in HTML.

For larger projects, you can have multiple targets in your build XML file that run different test cases, and set up multiple Builders for each target - Using the "Targets" tab to specify which target(s) each should run. Each builder can have different resources bound to them. Here is an example:

build.xml

<?xml version="1.0"?>

<project name="CFUnit" default="all" basedir=".">
	<taskdef name="CFUnit" classname="net.sourceforge.cfunit.ant.CFUnit"/>
	
	<property name="domain" value="http://localhost/" />
	
	<target name="testgroup1">
		<CFUnit testcase="${domain}myproject/TestMyCFC1.cfc" verbose="true" />
		<CFUnit testcase="${domain}myproject/TestMyCFC2.cfc" verbose="true" />
	</target>
	
	<target name="testgroup2">
		<CFUnit testcase="${domain}myproject/TestMyCFC3.cfc" verbose="true" />
		<CFUnit testcase="${domain}myproject/TestMyCFC4.cfc" verbose="true" />
	</target>
	
	<target name="testgroup3">
		<CFUnit testcase="${domain}myproject/TestMyCFC5.cfc" verbose="true" />
		<CFUnit testcase="${domain}myproject/TestMyCFC6.cfc" verbose="true" />
	</target>
	
	<target name="all" depends="testgroup1,testgroup2,testgroup3" />
</project>