This document attempts to provide an overview of the installation and use of the ColdUnit automated unit testing framework.

Installation

Place the contents of the src directory into your ColdFusion server's CustomTags directory in a directory called coldunit. Edit the file coldunitVariables.cfm. The rootMappingPhysicalPath and rootMappingLogicalPath variables should be set to the physical and logical paths (see the Mappings section in ColdFusion administrator) of a mapping on your system that sits above the area where you want to place the application you want to test. Set fileSeparator to be the file separator character appropriate for your system (\ for Windows, / for Unix). Copy the code in the tests directory somewhere where your ColdFusion server can serve the CFML. Load the file allTests.cfm in the tests directory in a web browser. You should see something like:

Congratulations, you have successfully installed ColdUnit! Yes, we really should write more tests for the framework itself.

Usage Examples

Now say you are in a directory containing ColdFusion that you will want to test. Call this directory www-root. Below www-root, create a directory called tests. I will give two examples:

1. writing simple tests for a custom tag
2. writing a test for code that changes the database

Writing a simple test for a custom tag

Say we want to write a custom tag that capitalizes the first letter of every word in a string. In the tests subdirectory, create a directory called testCapitalize. Within testCapitalize, create a file called testCapitalizesSimplePhraseCorrectly.cfm with the following contents:

In order to run our test, go back to the www-root directory and create a file called allTests.cfm with the following contents:

Now we will write capitalize.cfm. One way to do it is the following:

Point your browser at allTests.cfm in the www-root directory, and you should see something very similar (the number of seconds won't be the same) to the following:

Oops. I made a mistake, one I often make. It turns out the second argument of the built-in function, Right, is the number of characters to be taken from the right side of the first argument, not the starting point of the substring to be returned. I can fix the code like this:

Now let's rerun my test and see if I did indeed fix the bug.

Looks good! But wait, we forgot a test, didn't we? We haven't really done any boundary condition testing. Let's write another test for capitalization of one-letter words. Place the following in the file testCapitalizeSingleCharWord.cfm in the testCapitalize directory:

If we rerun allTests.cfm, we get the following result:

Looks like we did miss a test. What we see above is the typical ColdUnit output when an "Error" occurs. An error is defined as an exception that is not of the type cfunit.failure (which is generated by the framework whenever an assert fails). Notice that the TAGCONTEXT subelement of the EXCEPTION struct tells you exactly where the error occurred in your code. Also, I have collapsed the elements 3 through 7 of the TAGCONTEXT array for readability.

To fix the bug, we add the following code to capitalize.cfm and rerun the tests:

After rerunning the tests, we get:

You've now seen the three basic kinds of test results: success, (assertion) failure and error (the result of an exception being thrown).

Writing a test for a custom tag that alters the database

There are two main benefits of using allTests.cfm to run your tests.

1. It will search recursively through all directories under the root attribute (in the example above root=".", i.e. the current directory) and find all tests. It considers a .cfm file a test if its filename begins with "test", ends in ".cfm", and if the file exists in a directory whose name begins with "test". This allows you to build hierarchical test suites easily, allowing you to run all of your tests, or only a given subset under a particular directory.
2. More relevant to this section: the test runner used by allTests.cfm will surround the execution of each test in a transaction, and will rollback that transaction after each test. This way, any code that inserts/updates/deletes from tables in your database can safely be tested without altering the database.

This part is under construction.