Test Driven Development with ColdFusion Part III : Integrate your tests into CFEclipse using CFUnit-Ant

Jan 25, 2006

by Robert Blackburn

In the previous two articles (Part I: An Introduction to Unit Testing and Part II: Building Unit Tests with CFUnit), we discussed the advantages of Test Driven Development (TDD) and unit testing your ColdFusion code, and how you can do it with CFUnit. In the third and final article in this series, we will look into how to make unit testing easier by integrating it into CFEclipse.

When I first started designing CFUnit, I had a vision in mind. When working with Java in Eclipse, you can run your unit test from right within the interface and a nice little panel shows you the results. Wouldn't it be great if you could do that for ColdFusion too? Well -- if the article title didn't tip you off -- you can!

What is CFEclipse and CFUnit-Ant?

Eclipse (http://www.eclipse.org/) is a popular open source development IDE. As a ColdFusion developer, it may take some time to adjust to how this tool works, but in my opinion it is well worth the effort. CFEclipse (http://www.cfeclipse.org/) is an Eclipse plug-in for ColdFusion, and is a highly recommended tool, whether you use CFUnit-Ant or not.

CFUnit-Ant is an extension to the Apache Ant Java-based build tool (http://ant.apache.org/), and, like the normal Ant tool, can be run from within Eclipse. To install CFUnit-Ant, simply download the CFUnit-Ant JAR file (http://cfunit.sourceforge.net/) from the CFUnit site to anywhere on your local machine. That's it; you are now ready to start using CFUnit-Ant.

Creating a Build File

Ant uses build files to define the tasks to execute. These files are written in XML, and are human-readable. Ant can perform many tasks, ranging from compiling Java code to zipping files for archiving. Here is an example of the build file I use for CFUnit:

<?xml version="1.0"?>
<project name="CFUnit" basedir="." >
<property name="srcdir" value="src" />
<property name="destdir" value="build" />
<property name="version" value="1"/>
<target name="build" description="Packages CFUnit">
<zip zipfile="${destdir}/CFUnit_${version}.zip">
<zipfileset dir="${srcdir}" />
</zip>
</target>
</project>

The first line is the standard xml declaration. The second line is a <project> tag, which contains the name of the project and the base directory to use when calculating paths. This is followed by three <property> tags. These define variables I would like to use in this build file. Each of these indicates a property name and its value.

After the properties is a <target> tag. Targets simply group tasks together, and each build file can have multiple targets. When you execute a build file, you will be able to specify one or more targets to execute. For this simple example, we only have one target, named "build".

The build target only has one task, "zip". This will create a zip file named "CFUnit_1.zip" containing the contents of the "src" folder, and place it into the "build" folder. Notice how I used ${} to insert dynamic properties. This is Ant's way of noting a variable, and it's similar to how ColdFusion uses the pound(#) characters around variables.

I now have a build file that will zip the contents of the src directory for me. This is not only convenient, but it reduces the potential for human error. This may seem like too simple a task to automate with a build file. But trust me; after I slipped up by releasing a version of CFUnit that was not zipped with the correct base directory, I quickly implemented an Ant build file and have used it faithfully every since.

This build file is just a basic example designed to familiarize you with Ant so that you can get started with CFUnit-Ant. For more details, visit the Apache Ant project site ( http://ant.apache.org/).

Adding CFUnit-Ant Tasks to the Build File

Now that we have seen what a generic Ant build file looks like, how do we add CFUnit-Ant? Let's look at an example:

<?xml version="1.0"?>
<project name="MyApplication" default="test" basedir="." >
<taskdef name="CFUnit" classname="net.sourceforge.cfunit.ant.CFUnit"/>
<property name="approot" value="http://localhost/MyApp" />
<target name="test">
<CFUnit testcase="${approot}/test/TestDistanceCalc.cfc" verbose="true" />
</target>
</project>

This build file starts off in much the same way the first one did. However, there is a new tag here, <taskdef>. This tag allows you to define a special task. This line defines our CFUnit tag and should just be copied and pasted each time. On the next line we have one property named "approot," which is the root URL for our application. There is then a target named "test" with one task in it, <CFUnit>. The CFUnit task takes two attributes, testcase and verbose. The testcase is just the location of the test case you would like to execute. Verbose will enable more detailed error and failure messages.

You do not need to install Ant to use CFUnit-Ant because Eclipse comes with Ant built in. (We will cover how to configure Eclipse in the next section). But if you did go through the trouble of installing Ant, you can execute this build file through a command prompt. To do this, go to the directory the file is in(C:\>cd yourfolder) and simply execute the ant command (C:\yourfolder>ant).

Unless you are building the world's simplest application, your application will undoubtedly have more then one test case. This is done by adding multiple CFUnit tasks to the build file. Here is another example:

<?xml version="1.0"?>
<project name="MyApplication" default="test" basedir="." >
<taskdef name="CFUnit" classname="net.sourceforge.cfunit.ant.CFUnit"/>
<property name="approot" value="http://localhost/MyApp" />
<target name="test">
<parallel timeout="30000">
<CFUnit testcase="${approot}/test/TestDistanceCalc.cfc" verbose="true" />
<CFUnit testcase="${approot}/test/TestIndex.cfc" verbose="true" />
</parallel>
</target>
</project>

Notice how this time I nested the CFUnit tasks inside <parallel> tags? This will allow each test to run in parallel, thus executing all of my tests more quickly.

Running the Build File from CFEclipse

We have now successfully created our project's build file. But that is only half the battle; we also need to execute it. As mentioned before, you can execute these using Ant through the windows command prompt, but that is not the ideal work flow, especially for a CF developer. Therefore, we will look at how we can configure CFEclipse to automatically run the Ant build file (which will run our CFunit tests).

Automatically Running Tests

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

Right click the project and click "properties" (or select "Project" > "Properties" in the toolbar).
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 use the "Browse Workspace..." button to enter the location of the XML build file you created.
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. (You may need to click the "User Entry" icon first to enable the button).
Browse to where you downloaded the CFUnit-Ant JAR, 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 CFML files you would like this builder to be associated with. You can either specify specific files, or entire directories, or both.

This may look like a lot of steps, but once you have done it once or twice you will quickly see what each step's purpose is and hopefully learn enough to experiment with these settings.

Now open one of the files you associated your build file with, make a superficial change to it, and save. You should see the "console" pane show up within CFEclipse (If it does not show up automatically, click "window" -> "show view" -> "other", then select "basic" -> "console" -> "OK"). The console will first list the tests it is running, and then, after a second or two, the results of the tests.

If there is an error or failure, some information will be displayed about the failure. But only so much information can fit into the console. There is an easy trick for getting more details about any error or failure. The console will list URLs to all the tests it runs. Simply copy the URL to the test that failed and open it in a browser. The message you see in the browser will be identical to what you saw in the Eclipse console, but if you place "&html=1" at the end of the URL, it will display the information in HTML and may include more details, like a stack trace.

That's it; you are now ready to begin TDD with ColdFusion. Each time you modify one of the files you configured, a builder for Eclipse will automatically run the tests for you and report the results.

Summary

In this series we discussed the advantages of TDD and unit testing, how you can do it with CFUnit, and how to integrate your tests into CFEclipse. My hope is this will put you in good standing to begin unit testing in ColdFusion, and maybe to become comfortable enough with it to begin experimenting with your own techniques. To end this series, I will leave you with a short list of resources that may help you expand you knowledge of unit testing in ColdFusion:

CFUnit Home Page (http://cfunit.sourceforge.net)
CFUnit Mailing List (http://www.houseoffusion.com/cf_lists/threads.cfm/51)
JUnit Home Page (http://www.junit.org)
Kent Beck's Testing Framework (http://www.xprogramming.com/testfram.htm)

Robert Blackburn is a developer and team leader of the Internet Application Development team at American Power Conversion Corporation (http://www.apcc.com). He has been using ColdFusion since 1999, and has revived and manages the CFUnit open source project (http://cfunit.sourceforge.net). He currently has a blog at http://www.rbdev.net/devblog for his occasional ramblings.