Download to get rid of those pesky bugs.             MXUnit Unit Testing framework for ColdFusion developers                               Download       Details       Home       Support       Blog

Using the MXUnit Ant Task to generate JUnit Reports

In this tutorial, you will learn how to create an Ant build file that executes MXUnit tests and generates JUnit reports

First off, you should be familiar with Ant. If not, visit the site, download Ant and play around with it to develop a basic understanding of projects and tasks.

Ok, now that you're an expert let's kick it. We'll use the MXUnit tests that we use to build the framework. These are located in the MXUnit Framework download in /mxunit/tests. We will use the minimal required options in order to run the Ant task. All optional task attributes can be found here.

This tutorial assumes installation of MXUnit directly in the webroot; e.g., /mxunit/

These are the basic steps to create the build that runs tests and generates a report

  1. Create ant Ant build project
  2. Define the MXUnit Ant Task
  3. Tell MXUnit Which Tests You Want to Run
  4. Define The JUnit Report Task
  5. Run it ...
  6. View the report

 

1. Create an Ant build project

Type the folling into a text file and save it as /mxunit/tutorial/ant/build.xml.

<?xml version="1.0" encoding="ISO-8859-1"?> 
<project name="MXUnitTask" basedir="." default="main">
</project>

If you run just this in Ant you should see the following:

This is what we expect to see. The build fails because there is no target main defined. We will define this task next.

2. Define The MXUnit Ant Task
Add the following into the build.xml file: 
<?xml version="1.0" encoding="ISO-8859-1"?> 

<project name="MXUnitTask" basedir="." default="main">
  <mkdir dir="testresults" />
  
  <target name="main" depends="runtests" description="Main target for running the tests." />
  
  <target name="runtests" description="Make output directories and run the MXUnit task">
  <taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask"  classpath="../../ant/lib/mxunit-ant.jar" />
  <mxunittask server="localhost" port="8500"
                outputdir="testresults" 
                verbose="true">
  </mxunittask>
</target>
</project>
This instructs Ant to use the MXUnit Ant Task located in /mxunit/ant/lib/mxunit-ant.jar. It then tells the MXUnit Ant Task to use the localhost as the target server and the HTTP port 8500. You should change these values to point to any installation of the MXUnit Framework. The outputdir is the location to where the test results will be saved. The verbose attribute instructs the task to print additional information to stdout.

If you run this, you should see the following:

This is good. We have made contact with the MXUnit Ant Task. The build fails with a java.lang.NullPointerException because the task expects some tests to run and none were provided.

3. Tell MXUnit Which Tests You Want to Run
 
Add the following to the build.xml file: 
<?xml version="1.0" encoding="ISO-8859-1"?>

<project name="MXUnitTask" basedir="." default="main">

  <mkdir dir="testresults" />
  
  <target name="main" depends="runtests" description="Main target for running the tests." />
  
  <target name="runtests" description="Make output directories and run the MXUnit task">
  <taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask"  classpath="../../ant/lib/mxunit-ant.jar" />
  <mxunittask server="localhost" port="8500"
                 outputdir="testresults"
                 verbose="true">
      <directory path="C:\ColdFusion8\wwwroot\mxunit\tests\framework" recurse="false" />
  </mxunittask>
</target>
</project>
We inserted the directory element to instruct the MXUnit Ant Task to run all the tests in the directory specified by the path attribute. Note, make sure your path attribute points to the location of the /mxunit/tests/framework directory. When you run this, the HttpAntRunner.cfc is called by the task. This runner executes the tests using the mxunit framework and save the results as JUnitXml to the location specified by the outputdir attribute.

When run, you should see the following:


You should now have 2 files in /mxunit/tutorial/ant/testresults/tmp/ called mxunitdirectorytestsuite_1.xml and testresults.properties. The first one will be used by JUnit in the next step to generate a report. The second one can be used to summarize all the test results run, as you can have multiple directory elements in the task.

4. Define The JUnit Report Task
Type the following into the build.xml: 
<?xml version="1.0" encoding="ISO-8859-1"?>

<project name="MXUnitTask" basedir="." default="main">

  <mkdir dir="testresults" />

  <target name="main" depends="runtests,junitreport" description="Main target for running the tests." />

  <target name="runtests" description="Make output directories and run the MXUnit task">
  <taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask"  classpath="../../ant/lib/mxunit-ant.jar" />
  <mxunittask server="localhost" port="8500"
                 outputdir="testresults"
                 verbose="true">
      <directory path="C:\ColdFusion8\wwwroot\mxunit\tests\framework" recurse="false" />
  </mxunittask>
</target>



<target name="junitreport" description="Create a report for the rest result">
 <mkdir dir="junithtml"/>
 <junitreport todir="junithtml">
  <fileset dir="testresults">
     <include name="*.xml"/>
   </fileset>
   <report format="frames" todir="junithtml" styledir="../../ant/xsl"/>
  </junitreport>
</target>

</project>

We've a couple of new things here:
1. Created a new target for Ant (junitreport). This target is responsible for generating the JUnit-style report.
2. Instructed the main target to call the runtests target first, then the junitreport task after that.

The junitreport task is looking for the XML files we created with the runtests task. Hence, we use the fileset element to tell JUnit where to go to find the XML test results.

You'll also notice that we point to the /mxunit/ant/xsl directory for the formatting information. This is optional, and you may use any stylesheet you wish or the default one in Ant's JUnit Report Task path.

5. Run it ... you should see this:



6. View the report

You can now browse /mxunit/tutorial/ant/junithtml/ and open index.html in your web browser. You should see the following:

An live interactive version of this report is available here.

You can take this process further by adding additional directory elements that contain tests. You may also execute individual test cases using the testcase element. Details on the MXUnit Ant Task can be found here.

2008 MXUnit.org