JMeter Ant Task

This is an Ant task for automating running JMeter test plans. The task executes one or more JMeter test plans, and logs the results to a file.

To use the task, you must have JMeter installed. You must also include ant-jmeter.jar in your Ant classpath. Adding the jar to $ANT_HOME/lib will make this happen automatically.

Start by defining the task to make it available to your build script:

<taskdef
    name="jmeter"
    classname="org.programmerplanet.ant.taskdefs.jmeter.JMeterTask"/>

Set the jmeterhome parameter to your JMeter install location, and the resultlog parameter to the name of a file to log the test results to.

You can either specify a single test plan using the testplan parameter, or multiple test plans using the testplans nested element. The testplans element is a standard Ant FileSet element.

<jmeter
    jmeterhome="c:\jakarta-jmeter-1.8.1"
    testplan="${basedir}/loadtests/JMeterLoadTest.jmx"
    resultlog="${basedir}/loadtests/JMeterResults.jtl"/>

<jmeter
    jmeterhome="c:\jakarta-jmeter-1.8.1"
    resultlog="${basedir}/loadtests/JMeterResults.jtl">
	<testplans dir="${basedir}/loadtests" includes="*.jmx"/>
</jmeter>

Optional JMeter arguments supported include specifying an alternate jmeter properties file (jmeterproperties), running remote servers specified in jmeter properties file (runremote), and running the tests through a proxy or firewall (proxyhost, proxyport, proxyuser, proxypass).

You can override JMeter properties (instead of modifying jmeter.properties) like this:

<jmeter
    jmeterhome="c:\jakarta-jmeter-1.8.1"
    testplan="${basedir}/loadtests/JMeterLoadTest.jmx"
    resultlog="${basedir}/loadtests/JMeterResults.jtl">
	<property name="request.threads" value="1"/>
	<property name="request.loop" value="10"/>
</jmeter>

You may also specify additional JVM arguments to the JVM launched to run JMeter. Here is an example of how to specify JVM arguments:

<jmeter
    jmeterhome="c:\jakarta-jmeter-1.8.1"
    testplan="${basedir}/loadtests/JMeterLoadTest.jmx"
    resultlog="${basedir}/loadtests/JMeterResults.jtl">
	<jvmarg value="-Xincgc"/>
	<jvmarg value="-Xmx128m"/>
	<jvmarg value="-Dproperty=value"/>
</jmeter>

I've also included an XSLT file, jmeter-results-report.xsl, for generating a summary report from the result log file. The summary report is very similar to the default report created by the junitreport task. You can use the xslt task to create the report:

<xslt
    in="${basedir}/loadtests/JMeterResults.jtl"
    out="${basedir}/loadtests/JMeterResults.html"
    style="${basedir}/loadtests/jmeter-results-report.xsl"/>

If you would like failure detail messages in the report output, you must configure JMeter to output that information to the result log. To do this, set the following property in your jmeter.properties file before running the test plans:

jmeter.save.saveservice.assertion_results=all

Note: As of JMeter 1.9RC2(?), the default results output format is now csv. It must be changed to xml in order to use the xslt task to create the html report:

jmeter.save.saveservice.output_format=xml

The report will look something like this:

There is also another XSLT file that was contributed which generates an enhanced report that includes expandable details. jmeter-results-detail-report.zip contains the XSLT file and images. Note: I have not tested it on all browsers.

Changes:
1/21/2004 - added support for additional jmeter arguments (proxyuser, proxypass), and new support for specifying jmeter properties (like the jmeter -J argument) using the <property> tag
10/4/2003 - added support for additional jmeter arguments (jmeterproperties, runremote, proxyhost, proxyport), and included updated jmeter-results-detail-report.xsl with contributed fixes to work in more browsers.
7/29/2003 - added support for jvm arguments (jvmarg).
3/3/2003 - original version

jfifield@programmerplanet.org
Last updated: 10/4/2003