Getting started with CFTestingKit

Introduction

CFTestingKit is a testing framework for ColdFusion MX and BlueDragon Server 6.1 providing to developers several components to write and run test cases.

In this tutorial, we will see how to leverage the features of the framework and make sure your code works whenever you fix bugs or implement new features.

Writting a test case

A test case is a group of small tests that exercise a particular feature or component of your application. Each test is implemented as a function of a module extending the TestCase component.

Lets say we want to test some of the mathematic functions of ColdFusion. We copy the CFTestingKit folder into the document root directory of a ColdFusion instance and we create a folder named SampleTestCase in the same root directory.

Insert this source code in a blank document and save it into the SampleTestCase folder as MathTest.cfc.

<cfcomponent displayname="MathTest" extends="CFTestingKit.TestCase">
    <cfset variables.f1 = 0 />
    <cfset variables.f2 = 0 />
    
    <cffunction name="setUp">
        <cfset variables.f1 = 6 />
        <cfset variables.f2 = 3 />
    </cffunction>
    
    <cffunction name="testAddition">
        <cfset this.should((variables.f1 + variables.f2) eq 9) />
    </cffunction>
    
    <cffunction name="testSubstraction">
        <cfset this.shouldBeEqual((variables.f1 - variables.f2), 3) />
    </cffunction>

    <cffunction name="testDivisionByZero">
        <cfset this.shouldRaise("(variables.f1 / 0)",
                  "ColdFusion should throw an error but the framework catch
                  the error. Note that if you are using BlueDragon, it doesn't
                  raise an exception and this test failed.") />
    </cffunction>
</cfcomponent>

setUp is a function you can override to setup your environment and you can trash it by overriding the tearDown function. setUp is called before executing a test and tearDown is called after the execution of the test. Furthermore, setUp and tearDown are called before and after executing each single test.

Each test function name has test as a prefix. You must use this convention to get your tests recognised when preparing the test build¹ (more on this in the next section).

The framework has several methods to test an expression or a condition.

should generates a failure when condition evaluates to false.
shouldnt generates a failure when a condition evaluates to true.
shouldBeEqual generates a failure when the result of the left expression is not equal to the value of the right expression.
shouldRaise generates a failure when expression does not raise an exception.
shouldntRaise generates a failure when expression does raise an exception.

Running a test case

A test case only contains the test conditions and can't be run by itself; we have to build a test suite. Fortunately the TestCase component provides a function to create the test suite from itself.

Insert this source code in a blank document and save it into the SampleTestCase folder as index.cfm.

<cfset myTestSuite = CreateObject("component", "SampleTestCase.MathTest").buildSuite() />
<cfset result = myTestSuite.run() />

<cfoutput>
<h3>#myTestSuite.name()#</h3>
#result.print()#
</cfoutput>

The first line creates a test suite by invoking the buildSuite() on a newly instantiated test case.

The second line run the test and put the result into a test result variable, which is in fact an instance of the TestResult component.

The code enclosed into the cfoutput tag displays the name of the test suite and prints the result in a human readable format.

Reading the result

The print() function returns some interesting information about your test case. It tells you the overall rating, how many tests were ran and how many successes, failures and errors were returned.

At first sight, a failure and an error might seem like two words for the same thing, but in fact, they have their own meaning in a testing framework.

A failure is returned when an expression didn't pass a test while it was expected to succeed.
An error is returned when the framework caught an unexpected failure generated by ColdFusion.

1. This rule doesn't apply if you want to write your own test builds.