Running CFUnit in CFEclipse quick guide

As you might of heard CFUnit is now integrated into the beta build of CFEclipse. To bring you up-to-speed about CFUnit(incase you didn't know); CFUnit is a unit testing framework for ColdFusion, modelled after the popular JUnit framework. By building test units while creating your app you can ensure that your methods (cffunctions) and components overall behave as expected. If you are totally new to CFUnit you might want to check out the references at the end of this post.

So who is this guide for. Well nearly anyone who wants to get started with CFUnit within CFEclipse. For reference I am working on Eclipse 3.2.1 with CFEclipse 1.3 Beta RC2 1.2.9.7 and im gonna assume you've got both on your sytem. This guide doesn't really go into all the benefits of CFUnit (though by the end of this you should be able to seem them) so if you want more details afterwards check out the points of reference at the end.

With Eclipse and CFEclipse running we are gonna need to download CFUnit (v2.0 Beta 3 or later) and we can get that from Sourceforge. To install couldn't be easier. Inside the .zip file you just downloaded is a folder called "net" put this on the root of your web-server (later on you can map this, for now lets keep this easy). You can test your installation by hitting http://localhost/net/sourceforge/cfunit/CFUnitExample/mytest.cfml

Next open Eclipse and go to Preferences > CFEclipse > CFUnit and for the fa├žade url enter localhost.net.sourceforge.cfunit.framework. If you are running on test environment from port 8500 then enter localhost:8500.net.sourceforge.cfunit.framework. See fig.1

fig.1

Now that CFUnit is set up we need to create a new project. For this demo i'm creating a new project called "CFUnit_example" which will be a folder off my root (http://localhost/CFUnit_example). We also need to open up the CFUnit view. Go to Window > Show View > Other > CFUnit, this will open a new tab on the (usually on the bottom of the screen). Personally I have the tab set up as a fast view. To do this click on the CFUnit icon in the view's title bar and select Fast View from the menu that appears. The CFUnit view is closed, and its icon appears in the shortcut toolbar. (see fig. 2)

Fastview

Clicking the CFUnit icon alternately opens and closes the view. To restore the view in its previous place in the perspective, right-click on the Fast View icon and select Fast View.

We are now set to create our component (cfc). For the record i'm stealing borrowing most of the content from Robert's CFUnit primer for the next part of this guide and applying it to CFEclipse.

1. The Component. MyCFC.cfc
This is going to be your CFC, whether it be DAO or business object for now it's going to be a simple component that add and subtract two local vars and another method just returns a true value.

The above component is a little different from the primer. I've added a third method, returnTrue(). This is to only to demonstrate another TestCase. More on this later, I don't want to throw everything at you straight away.

2. Test directory.
Create a new sub directory called "test" in your projects. All our tests will be run from this directory. The only stipulation on this folder is that it be accessible by ColdFusion. By keeping the tests within a folder within the project they are better grouped together.

3. The unit test. MyCFCTest.cfc
The following component is what we will be running later on to test MyCFC.cfc.

MyCFCTest.cfc is a little different from Robs primer version to accommodate the extra method, "returnTrue()", that I added to MyCFC.cfc. All CFUnit tests must extend the "TestCase" CFC from the CFUnit framework. This CFC tests the "add","sub", and "returnTrue()" methods of our "MyCFC" component. All these tests do is run the method to be tested, and then asserts that the value returned was equal to what we expected. If it is not equal, then the test fails. The assertEquals() method is a part of the TestCase class which we are extending. In total there are 6 TestCase's

  • assertTrue(message, condition): Asserts that the condition is true. If it isn't, the test fails and displays the given message.
  • assertFalse(message, condition): Asserts that the condition is false. If it isn't, the test fails and displays the given message.
  • assertEquals(message, expected, actual): Asserts that two objects are equal. If they are not, the test fails and displays the given message.
  • assertSame(message, expected, actual): Asserts that two objects refer to the same object in memory. If they do not, the test fails and displays the given message.
  • assertOutputs(template, expected, message): Asserts that a template (*.cfm file) or CF Module contains the expected output. If it doesn't, the test fails and displays the given message.
  • fail(message): This will cause the test to fail and display the given message.

4. Running the test.
Believe it or not we've one all the coding, all that is left is to test our component. To make life easier for yourself (for this next part) you might want to take the CFUnit off fast view? Right-click on the Fast View icon and select Fast View. To find your tests the view incorporates a file search similar to Macs Spotlight. Just click on browse and start typing the name of your test unit. In our case type m-y-c-f-c-t-e-s-t. See fig. 3

find screen

Select the test unit (MyCFCTest.cfc) then click run test and see the results. See fig. 4

final test

If you want to see how the errors look then go to "returnTrue()" in MyCFC.cfc and set the return value to FALSE and re-run the tests.

And once again that's it. This is a basic guide, and just something to get your feet wet with. Hopefully you can see why test units will be beneficial to your development cycle and with this integrated into CFEclipse how easy it will be to maintain them.

Before I end this with references I want to say a big thank you to Robert Blackburn (the man behind CFUnit), a lot of the content in this tutorial is his work and I merely cut n' pasted it together. I cannot stress enough to check out the points of reference below as the links cover more of CFUnit than this post can or does. If you have any questions then please check out the CFUnit Forums

Points of reference: check these out.... they're not here for filler :o)