BLOG

The time has come to clear out the RocketBoots garden shed - there's an assortment of useful tools in there that I've been meaning to slap a GPL on and leave out the front for our neighbours to pick up, but somehow I've just never had the time to do it.

So, the first item in our little garage sale is a beauty that has been maturing in the hands of a select few RocketBoots clients for the last two years or so - RocketUnit. RocketUnit is a unit testing framework for ColdFusion. "What?" I hear you say, "Not another one!". Well yes, but this one is a bit different:

• It is small - a single CFC.
• It has one assert() function, not tens, but still gives detailed, meaningful messages when assertions fail.

Together, the above features make RocketUnit pretty approachable and easy to use. A few of our clients have been successfully using RocketUnit to test anything from a single custom tag up to a complex payment gateway.

Here's a head-first guide to getting up and running with RocketUnit:

1. Download RocketUnit from our site.
2. Expand the zip into your web root. This will create two folders, /com and /test. *
3. Browse {your site}/com/rocketboots/rocketunit/rocketunittests/ to confirm that RocketUnit is installed.
4. Browse {your site}/test/com/rocketboots/sample/ to see the sample test case output. Note the verbose explanation when the test fails.
5. Open /test/com/rocketboots/sample/index.cfm to see how the test was invoked.
6. Open /test/com/rocketboots/sample/TestSample.cfc to see what a RocketUnit test case looks like. There are plenty of comments to explain what is going on. Note that all the test cases use either assert() or fail() to record test results.
7. Read the header comments in /com/rocketboots/rocketunit/Test.cfc for a more general usage guide.
8. To make your own test case, copy index.cfm and TestSample.cfc to use as a starting point**. Here's a simple checklist for the tests you might want to create:
   • Normal processing - typical inputs produce expected outputs (for each method if testing a cfc).
   • Boundary processing - if there are loops in the code, what happens if you pass empty or very large arrays, queries or collections as input?
   • Abnormal processing - does the code being tested detect invalid or missing arguments and throw the appropriate exceptions or use the correct defaults?
9. Note that you can create your test cases before you create your code if you like - all that will happen is that you'll get failures or errors coming up in the report. The objective of subsequent development then becomes to make the test cases pass successfully. This is called Test Driven Development and is widely regarded as a Good Thing. That said it's also a good idea to create test cases for legacy code, particularly if you're about to embark on some refactoring fixes and you want to make sure you aren't breaking anything.
10. When you discover a bug in your code, the first thing to do is write a test case that reproduces the bug. Then you fix the bug and check to see the test passes. In this way you make sure that no-one can reintroduce the bug without causing a test to fail.

* I love keeping my code in packages outside the webroot. To make it easy for you to deploy RocketUnit the instructions say to expand it in the webroot, taking advantage of the implicit "/" cf mapping that points to the webroot. Feel free to rearrange the code under CF mappings - as long as com.rocketboots.* and test.com.rocketboots.* are mapped the code will work if you copy the index.cfm files to somewhere you can browse.

** It is standard practice to keep your test cases in a package structure starting with "test", which then shadows the original package structure of the software being tested. However you do not need to follow this practice to use RocketUnit.

If you have any questions about using RocketUnit please post them on the RocketUnit Google Group and I'll answer them as soon as I can. I hope you'll find this little tool as useful as we have.

Cheers,
Robin

What advantages does RocketUnit offer over cfunit or cfcunit?

Hi Matthew, RocketUnit is: 1. Smaller. CFUnit has a few cfcs as per the *Unit standard. CFCunit required the mach-ii framework to run last time I checked, and 2. Has a single assert() method. This takes advantage of the ColdFusion evaluate() function to give lots of information about failed assertion expressions without having to write additional tracing code. Both CFUnit and CFCUnit are based on JUnit. While it is great that we have *Unit implementations for CF, for my own use I thought I could take more advantage of the features of CFML to write something that would be easier to use. This is not an unimportant consideration - despite cfunit and cfcunit being around for years I see very few CF development shops using unit testing in their development, so perhaps ease of use is one of the issues involved.

BTW, here's a tip - add a <meta http-equiv="refresh" content="10" /> tag to your index.cfm, point your browser at it (I use the one in Eclipse) and you'll get a constantly updated snapshot of your unit test results as you develop - a cheap and cheerful alternative to including tests in your Ant build tasks.

I have to confess, I have been using RocketUnit for a while now and it is just perfect! So nice and simple and easy to use, we even have developers using it for unit testing some of our C# webservices!! (ok ok, maybe that is just me)

I've added a listing for this project on RIAForge: http://rocketunit.riaforge.org/

RocketUnit is absolutely sweet; thx for publishing it, Robin. Compared with both CFUnit and CFCUnit it's a no brainer to setup, it's much simpler to use and still delivers the same (over even better) information. Even people who never have worked with unit testing before can actually get it pretty much straight away.

There is a wiki for RocketUnit at http://trac.rocketboots.com/os/wiki/RocketUnit

RE: http://trac.rocketboots.com/os/report/1 You should probably shut this down as it is all spammed out.