View Source

h2. MXUnitAntTask - Version: 1.0.7


h3. Description

Runs MXUnit tests and saves the output to the directory specified by the outputdir parameter.

This version uses HTTP to connect to the MXUnit test runner running on a CFML serv (Adobe ColdFusion, Railo, Blue Dragon).

This supports the following HTTP authentication mechanisms - BASIC, DIGEST, and NTLM.

The default testrunner (/mxunit/runner/HttpAntRunner.cfc) accepts either individual test cases or directories of tests to run. This runner returns only JUnitReport formated XML. These XML files{_}may_ optionally be used by the JUnitReport Ant task to generate nice HTML reports. Example usage:

{code}<junitreport todir="${junit.out.dir.html}">
<fileset dir="${output.dir}">
<include name="*.xml"/>
</fileset>
<report format="frames" todir="${junit.out.dir.html}" styledir="${style.dir}"/>
</junitreport>
{code}
Note that the mxunit-ant.jar must be in Ant's class path. This can be done by specifying the taskdef tag like this:

{code}<taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask" classpath="${mxunit.jar}" />
{code}
and then coding the rest of the MXunit Ant task ...

{code}<mxunittask server="localhost"
port="8500"
defaultrunner="/mxunit/runner/HttpAntRunner.cfc"
outputdir="${output.dir}"
verbose="true" haltonerror="true"> ...
{code}
In theory, one should be able to run multiple tests across multiple domains, as long as those tests are accessible via Http.

h3. Parameters

| *Attribute* | *Description* | *Required* | *Default* |
| protocol | The HTTP protocol to use. Valid values are 'http' or 'https' | no | http |
| server | The Http server name where MXUnit is located. | Yes | |
| port | The port the Http server is listening on. | No | 80 |
| outputdir | A directory in which to save JUnit XML test results. | No | |
| haltonerror | Instructs the task to stop executing when an _ERROR_ is detected. \\
This occurs _after_ all the tests in the DIRECTORY or TESTCASE task have been run. | No | false |
| haltonfailure | Instructs the task to stop executing when a _FAILURE_ is detected. \\
This occurs _after_ all the tests in the DIRECTORY or TESTCASE task have been run. | No | false |
| errorproperty | The name of a property to set in the event of an error. | No | |
| failureproperty | The name of a property to set in the event of a failure (errors are considered failures as well). | No | |
| defaultrunner | The testrunner responsible for accepting requests. \\ {tip:title="As of v1.0.5"}You can append arbitrary URL parameters (for custom runners) to the {{defaultrunner}} {tip} Example:{code}defaultrunner="/foo/bar/my_runner.cfc?param1=123&param2=abc"{code} \\ | No | /mxunit/runner/HttpAntRunner.cfc |
| verbose | Flag to indicate to output additional information. | No | false |
| testResultsSummary | Name of the properties file the task creates. This file is a Java Properties file that records a summary of all the tests the task has executed and is saved to the location specified in the $\{outputdir\} attribute. This can be useful in automated deployments, for example, if you wish inspect the results of all the tests run prior to deployment. This offers a deeper level of granularity than the haltonerror or haltonfailure offers. \\
The task generates the following properties that can be read by Ant using the following syntax: \\
<br><property file="$\{outputdir}/testresults.properties" /><br>testresults.properties looks something like:#Sat Mar 01 22:20:25 EST 2008 \\
success.ratio=.99 \\
total.failures=2 \\
failure.ratio=.01 \\
total.errors=0 \\
error.ratio=.00 \\
total.time=8016 \\
total.runs=151 \\
error.ratio is the number of errors to the total number of tests runs. \\
failure.ratio is the number of failures to the total number of tests runs. \\
success.ratio is the total number of tests run to the total number of errors and failures combined. \\ | No | testresults.properties |

h3. Parameters specified as nested elements


h3. directory

<directory ... >s are used to specify groups of tests to run.

| *Attribute* | *Description* | *Required* | *Default* |
| path | Directory of tests to run. | Yes | |
| componentPath | A prefix to the components being tested. This is a performance attribute. If specified, directory tests will run faster. Otherwise, the framework will discover the componentPath using built in Adobe ColdFusion functions. \\
Example: componentPath="mxunit.tests.framework". \\
MXUnit will correctly prepend this to all the tests in the specified directory. | No \\ |

*Optionallity is deprecated. Future release will require this attribute to be specified.* \| \|
| runner | The ColdFusion component runner responsible for running the tests, | No | /mxunit/runner/HttpAntRunner.cfc |
| remoteMethod | The remote method in the ColdFusion component that will be called. | No | run |
| packageName | The name used by the JUnitReport task to print the main and child packages in the test result report. | No | mxunit.testresult |
| recurse | Flag to indicate to run all tests in sub directories. | No | false |
| excludes | Comma-delimitted list of files not to include in the test suite. | No | none |
----
h3. testcase

A <testcase> allows you to specify one or more individual test cases to run.
| *Attribute* | *Description* | *Required* | *Default* |
| name | The fully qualified ColdFusion component name (com.foo.bar.MyCFC) | Yes | |
| runner | The ColdFusion component runner responsible for running the tests, | No | /mxunit/runner/HttpAntRunner.cfc" |
| remoteMethod | The remote method in the ColdFusion component that will be called. | No | run |
| packageName | The name used by the JUnitReport task to print the main and child packages in the test result report. | No | mxunit.testresult |
----
h3. Examples

This example illustrates a minimal amount of code required to run one directory of tests. Note that this example does not save any results. This may be useful for automated deployments.

{code}<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="MXUnitTask" basedir="." default="runtests">

<target name="runtests" description="Run a dir of tests recursively">

<taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask" classpath="${mxunit.jar}" />
<mxunittask server="localhost" >
<directory path="C:\CFusionMX7\wwwroot\mxunit\tests\framework" recurse="true" componentPath="mxunit.tests.framework" />
</mxunittask>

</target>
</project>
{code}This example runs both directories of and individual tests, saves the output to $\{output.dir}, generates a JUnit report, and opens a web browser with the JUnit report.

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

<property name="mxunit.jar" value="../ant/lib/mxunit-ant.jar" />
<property name="junit.out.dir.xml" value="testresults" />
<property name="junit.out.dir.html" value="testresults/html" />
<property name="output.dir" value="tmp" />
<property name="style.dir" value="../ant/xsl/" />



<target name="main" depends="browse" />


<target name="runtests" description="Make output directories and run the MXUnit task">
<mkdir dir="${junit.out.dir.html}" />
<mkdir dir="${output.dir}" />
<taskdef name="mxunittask" classname="org.mxunit.ant.MXUnitAntTask" classpath="${mxunit.jar}" />

<mxunittask server="localhost" port="8500"
defaultrunner="/mxunit/runner/HttpAntRunner.cfc"
protocol="http"
outputdir="${output.dir}"
authmethod="basic"
username="foo"
password="bar"
verbose="true">

<testcase name="mxunit.tests.framework.AssertTest" packageName="mxunit.asserttests" />
<testcase name="mxunit.tests.framework.AssertDecoratorTest" packageName="mxunit.assertdecoratortests" />

<directory runner="/mxunit/runner/HttpAntRunner.cfc"
remoteMethod="run"
path="C:\CFusionMX7\wwwroot\mxunit\tests\framework"
packageName="mxunit.framework"
recurse="false"
componentPath="mxunit.tests.framework"
excludes="none" />

<!-- This has a bad componentPath and should fail -->
<directory runner="/mxunit/runner/HttpAntRunner.cfc"
remoteMethod="run"
path="C:\CFusionMX7\wwwroot\mxunit\tests\framework"
packageName="mxunit.bad.framework"
recurse="false"
componentPath="mxunit.foo.bar"
excludes="none" />

<directory runner="/mxunit/runner/HttpAntRunner.cfc"
remoteMethod="run"
path="C:\CFusionMX7\wwwroot\mxunit\samples"
packageName="mxunit.tests.samples"
recurse="false"
excludes="" />


</mxunittask>
</target>




<target name="junitreport" depends="runtests" description="Create a report for the rest result">
<mkdir dir="${junit.out.dir.html}"/>
<junitreport todir="${junit.out.dir.html}">
<fileset dir="${output.dir}">
<include name="*.xml"/>
</fileset>
<report format="frames" todir="${junit.out.dir.html}" styledir="${style.dir}"/>
</junitreport>
<delete dir="${output.dir}" />
</target>


<!-- To fire up a browser with the test results. May not work on your machine -->

<target name="browse" depends="junitreport">
<exec executable="C:\Program Files\Internet Explorer\iexplore.exe">
<arg value="C:\CFusionMX7\wwwroot\mxunit\tests\testresults\html\index.html"/>
</exec>
</target>



</project>

{code}