MXUnit: Unit Testing for Coldfusion

One of the things I got into recently is the whole idea of test-driven development (TDD). This concept puts testing at the core of development, at the start of the coding cycle and not after you finish coding. It's definitely worth your while to read up on the good points of working this way, but to give you a few notable benefits of this approach:

  • By writing testing code first, that automatically fails, you can then proceed to improve and/or fix the code/class that it is testing, which then enforces refactoring of new code to meet the standards required. 

This tool works for pretty much all of the open-CFML engines, such as openbd and Railo, and this testing tool im talking about is MXUnit. 

 

Setting up MXUnit
You download the bundle from here and drop the mxunit folder into your web-root. It's as simple as that. Any applications you have in your CF webroot would be able to access mxunit. If you use Eclipse, you can follow the instructions here to set up it's very own plugin.

 

Adding tests to your project
Okay, so let's say you have an existing project (although its best to start scratch if you want to be a true TDD programmer).  You would add a tests folder in your application, and this is where you will add the individual Test Cases, and Test Suites. 

Using Kent Beck's TDD methodology we:

 

 

  1. Write the test first
  2. Watch the test fail
  3. Write the component
  4. Watch the test pass
so our first test -case, which we may store in a file called testUserManager.cfc. > 



<cfcomponent displayname="testUserManager" extends="mxunit.framework.TestCase">


 


 <cffunction name="setUp" access="public" returntype="void">


 <cfset usermgrComp = createObject("component", "chickentrader.cfc.doronkatz.chickentrader.UserManager") />


 


 <cfset user = CreateObject("component", "chickentrader.cfc.doronkatz.chickentrader.ObjectFactory").createUser()/>


 <cfset user.setActive("0")/>


 <cfset user.setEmail("doronsetup@doron#now()#")/>


 <cfset user.setPassword("testSetupPassword")/>


 <cfset user.setLanguage("E")/>


 <cfset user.setlastVisit("#DateFormat(now(),"yyyy-mm-dd")#")/>


 <cfset user.setRegDate("#DateFormat(now(),"yyyy-mm-dd")#")/> 


 <cfset user.setFirstName("Doron")/>


 <cfset user.setLastName("SetupTest")/>


 <cfset user.setCityName("Larnaca")/> 


 <cfset actual = usermgrComp.storeUser(user)/> 


  --->


 </cffunction>

As you can see above, the startup() method when declared like that is used to temporarily create/setup data in the database, which will be used throughout this test, before being torn down later in this test case. So anything in this method is temporary. What I have done here is merely create a new object (since I enjoy using oop in my CFCs, and add properties to it. The actual gets assigned usermgrComp.storeUser(user) which essentially cascades to a component that actually does the qu erying, and returns back the status of whether it passed or not.  Note, we can use <cfset dump(user)>  which is a much better debugging method than cfdump, and introduc ed in MXUnit.

</div>


 


<cffunction name="testGetUserByID" access="public" returntype="void">


<cfset usermgrComp = createObject("component", "chickentrader.cfc.doronkatz.chickentrader.UserManager")/>


<cfset getAllUsers = usermgrComp.getUsers()/>


<cfset aUsersID = getAllUsers.user[1].id />


<cfset actual = usermgrComp.getUserById(aUsersID)/>


<cfset assertTrue(actual.user.id neq 0, "To ensure we have something returned back")>


</cffunction>

Our first test case (we always start function names wi th 'test', and return void) creates a component and calls a method, we get values back. The important bit is towards the end where we have :

<cfset assertTrue....>

This is the assertion that we want to use to assert whether the value returned is equal to what we expect. We can use all sorts of assertions, and there are a few built-in ones that MXUnit provide to test true, pass, fail, same.



 <cffunction name="tearDown" access="public" returntype="void"> 


<cfset usermgrComp = createObject("component", "chickentrader.cfc.doronkatz.chickentrader.UserManager")/>


<cfset Users = usermgrComp.getUsers()/>


<cfset numUsers = arrayLen(Users.user)/>


<cfset aUser = Users.user[numUsers] />


<cfset actual = usermgrComp.deleteUser(aUser)/>


</cffunction>

The last function is TearDown(), which is the partner of StartUp(), and tears down the data we created, in StartUp(), so that we dont end up filling our database with useless junk. This is the cleanest way of ensuring we can run tests without having to unnecessarily populate our database.

Now that we have talked about the TestCase, a Test Suite is composed of many test cases, so we create the test suite. We don't have to create a test suite if we just want to test a few minor things, but as best practice, I would start off by creating a suite and adding new test cases as we move on forward into our project. So I create a file called appTestSuite.cfm:



 


<cfparam name="URL.output" default="html">


<cfscript>


 testSuite = createObject("component","mxunit.framework.TestSuite").TestSuite();


//Load User object to test


testSuite.addAll("chickentrader.tests.testUserManager");


 results = testSuite.run();


</cfscript>


<cfoutput>#results.getResultsOutput(URL.output)#</cfoutput>  


<p><hr /></p>


<p>Using CFDUMP against <code>mxunit.TestResult.getResults()</code> method</p>


<cfdump var="#results.getResults()#" label="MXUnit Sample Test Results" />

As you can see we load the testUserManager test case we created earlier, here, and output the results. So we use this file as the entry point (unless you are using the plugin through eclipse) to view the results of your tests. When you see the results, you can see each test case, with a colouring to determine whether it passed, through either green or red. 

So this is the crash-course introduction to testing on coldfusion. Hopefully simple and quick enough, but you should visit the MXUnit website for more examples of how it is used.

 

 

Filed under: Coldfusion OpenCF
 

Open BlueDragon + Railo + ColdFusion on Tomcat | Matt's excellent article

As a corollary to Sean's post about running Railo, OpenBD, and ColdFusion on JRun, I thought I'd outline my preferred development environment these days, which is to run all the necessary CFML engines on Apache Tomcat. Note that this approach will work equally well on Jetty, JBoss, GlassFish, or more or less any servlet container or JEE server you choose.

Great minds think alike because coincidentally enough, Dave Shuck also has just published two blog posts (part 1, part 2) about setting up a similar environment. I figure I'll throw mine out there as well because the more information available the better.

So why not use JRun? Well, aside from the fact that JRun is getting very long in the tooth at this point, personally (and you'll probably hear me say this in a couple of conference presentations this year), I think the ColdFusion model stands Java on its head a bit, particularly when you do a standalone install of ColdFusion. Yes, it makes it easy to install and configure ColdFusion, but in my opinion it also shields people from how Java web applications actually work, so I've become a big fan of treating ColdFusion like what it is: a Java web application.

This to me makes far more sense than letting ColdFusion and JRun dictate your Java environment. And I think you'll see in this blog post that "installing" CFML engines on Tomcat is actually easier than installing ColdFusion. The only even remotely tricky part is installing Tomcat (and in most cases it isn't tricky at all), so let's tackle that first.

As an aside, if you just want to try Open BlueDragon and don't want to bother with the Tomcat installation, just download the Ready2Run Jetty + OpenBD distribution, start Jetty, and you're done!

Installing Tomcat

I'm assuming you already have Java installed, and I recommend Java 1.6 updater 10 or later (updater 11 is the latest) since previous versions had a bug that makes CFC instantiation horrendously slow. So, if the following looks complicated, it's really only because I'm outlining how to get the Java settings correct if you need to worry about it. Chances you won't need to do most of these steps, and once Tomcat's running the CFML piece of this puzzle is dead simple.

First, download Tomcat. As of this blog post the latest version is 6.0.18, and you'll want the "Core" binary distribution. After the download completes, unzip the file you downloaded. Now comes the tricky install process. Oh wait, I forgot--there is no install process! All you have to do is start Tomcat after you unzip it. If you have your Java environment set up correctly Tomcat should find Java fine and fire right up.

To start Tomcat, open a terminal (or DOS window if you must ...) and navigate to your Tomcat directory, then the bin directory. For example if you unzipped Tomcat to /home/yourname/apache-tomcat-6.0.18, you would navigate to /home/yourname/apache-tomcat-6.0.18/bin. (Note that all of this runs perfectly well on Windows, and though I would never recommend using Windows for anything, you do not have to use Linux to get any of this to work.)

Once you're in the bin directory, run the startup.sh script (./startup.sh) and you'll see some output similar to this:

Using CATALINA_BASE:   /home/mwoodward/apache-tomcat-6.0.18

Using CATALINA_HOME:   /home/mwoodward/apache-tomcat-6.0.18

Using CATALINA_TMPDIR: /home/mwoodward/apache-tomcat-6.0.18/temp

Using JRE_HOME:       /usr/share/java/jdk1.6.0_11

As long as you see something similar everything's likely fine. If you see errors, the most likely culprit is that Tomcat can't find Java. You can either set a JAVA_HOME environment variable, or you can explicitly tell Tomcat where to find Java by adding the JAVA_HOME location to the catalina.sh script in the bin directory. Open catalina.sh in your favorite text editor, and after the big block of comments at the top of the file (denoted with # signs), add the following line:

JAVA_HOME=/path/to/your/jdk

Note that this should be the path to your JDK's home directory, not to a directory such as lib, etc. inside the directory. In my case I have Java in /usr/share/java/jdk1.6.0_11 so that's the value I use for JAVA_HOME. Save catalina.sh and run startup.sh again and everything should work now.

Check to make sure Tomcat is running by browing to http://localhost:8080 You should a page confirming that Tomcat is configured correctly.


Installing Open BlueDragon

Once Tomcat is running, since Open BlueDragon is a standard Java WAR (web application archive) file, "installing" OpenBD on Tomcat really just means copying a file to Tomcat's webapps directory so the WAR file is deployed. A WAR file is actually the same format as a JAR file (which is essentially a ZIP file ...), but it has an XML file that tells servlet containers how to deploy the application.

Here are the installation steps for OpenBD:



  1. Download the Open BlueDragon WAR ("J2EE Standard WAR") file from http://openbluedragon.org/download.cfm

  2. Copy the WAR file (which unless you change it is called openbd.war) to /path/to/tomcat/webapps

  3. Wait a few seconds for Tomcat to auto-deploy the WAR file, and browse to http://localhost:8080/openbd to see a test page:

    4. That's it! You now have Open BlueDragon running on Tomcat. Tomcat will deploy the WAR into a context path with the same name as the WAR file, which in this case is openbd, hence the URL http://localhost:8080/openbd If you want to deploy another instance with a different context path name, just change the name of the WAR file as you copy it (e.g. cp opendb.war /path/to/tomcat/webapps/mynewcontextpath.war) and you'll have another instance with a different context path.

    As for where to put your CFML files, just put them in /path/to/tomcat/webapps/openbd (or whatever you called your context path), and of course all URLs for this instance will include the context path in them. I won't be covering how to run Tomcat on port 80 or hook things into Apache in this blog post, but I'll cover that in a future post.

    Installing Railo

    To install Railo you follow the exact same steps as above with Open BlueDragon:



    1. Download the Railo WAR from http://railo.ch/en/index.cfm?treeID=224 -- you want the WAR file under "Railo Custom" at the bottom of the page

    2. Copy the WAR file to /path/to/tomcat/webapps. In this case since the file name includes the version number, I did a cp railo-3.0.2.001.war /path/to/tomcat/webapps/railo.war, which will make the context path "railo"

    3. Wait a few seconds for Tomcat to auto-deploy the WAR file, and browse to http://localhost:8080/railo to see a test page:

      4. As with OpenBD above, just put your CFML files in /path/to/tomcat/webapps/railo to run them on Railo in the railo context path.

      Installing ColdFusion

      ColdFusion is a bit of a different beast since Adobe doesn't distribute a standard WAR file, but luckily you easily can generate one by running the installer. The steps below are when you run the installer on Linux but the same principles apply on other operating systems. Let's generate a WAR file for ColdFusion.



      1. If you don't have it handy, download the developer edition of ColdFusion from http://www.adobe.com/support/coldfusion/downloads.html

      2. Run the installer (note on Linux you need to run the installer as root)

      3. Accept the license agreement (which is really fun to page through on the console installer--I think if you hit enter 28 times that will get you to the "Do you accept?" prompt ;-)

      4. Select Developer Edition (or use a serial number if you prefer)

      5. KEY STEP: Choose an installation type of "J2EE Configuration (WAR file)"

      6. Select the stuff you don't want to include in the installation. I typically uncheck all four choices (docs, LiveCycle, search services, and start on init) when I generate a WAR

      7. Choose the installation directory or accept the default

      8. Enter the admin password

      9. Choose to enabled or disable RDS. I find it's handy to have RDS on development instances so you can use the Eclipse tools to interact with the datasources.

      10. Enter the RDS password

      11. Confirm the installation selections and continue

      12. Wait a minute or so for the WAR to be generated

        13. At the end of this process you have a CF 8 WAR file sitting in your install directory (which by default on Linux is /opt/coldfusion8). Now the installation is more or less as above with OpenBD and Railo since we have a standard WAR file we can deploy on Tomcat:



        1. Copy the cfusion.war file into /path/to/tomcat/webapps As indicated above, this will mean your context path will be "cfusion" unless you rename the WAR file while copying it.

        2. Wait a few seconds for Tomcat to auto-deploy the WAR file

        3. Browse to http://localhost:8080/cfusion to complete the installation process for the WAR.

          4. Note that you only have to go through the 12-step program above to generate the WAR once, unless you want to change the installation options. So when you need another instance of ColdFusion on Tomcat, just copy the WAR file over again and give it a different name (and hence a different context path) from any other instances.

          If this matters to you, please be aware that for some reason ColdFusion isn't officially supported on Tomcat. Why is a bit of a mystery since Tomcat is the servlet container used in JBoss, and in my experience ColdFusion runs just fine on Tomcat. I only bring it up if you're in an environment where official support matters.

          Why Do This?

          You now have Tomcat running and can easily develop and test on Open BlueDragon, Railo, or Adobe ColdFusion. To me that's reason enough to use a development setup such as this. Also based on my experience helping people get this type of environment set up, it really does start to open up people's eyes to what's really going on under the hood with ColdFusion. Yes, if you do the multi-instance installation of ColdFusion you do get some server management features you don't get otherwise, but based on how I'm using ColdFusion these days, I simply don't need those features, particularly on development.

          What I do need, on the other hand, is the ability to develop on both ColdFusion 8 and (increasingly) Open BlueDragon, so rather than trying to shoehorn OpenBD into the ColdFusion/JRun environment, I prefer to use a standard Java servlet container such as Tomcat and put all the CFML engines and instances I need on Tomcat.

          Next Steps

          You're probably already wondering how to get things to run "for real," meaning eliminating the port number and context path for your users. This can be done several different ways, so I'll cover some options in future blog posts. In the mean time, check out Dave's blog posts (links above) for some info on setting things up with Apache and mod_jk, which is one way to go. You can also change the port Tomcat runs on, or proxy from Apache out to Tomcat for CFML sites, so there's no shortage of ways to set up more or less any configuration you want.

via mattwoodward.com

Matt has provided excellent instructions on how to install on Tomcat openbd and Railo as well as Adobe's CF, all within the same developer build

Filed under: Coldfusion Web development
11