| <?xml version="1.0" encoding="ISO-8859-1" ?> | |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> | |
| <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" /> | |
| <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="ISO-8859-1" type="text/css" /> | |
| <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" /> | |
| <script type="text/javascript" src="../coverage/.resources/prettify.js"></script> | |
| <title>JaCoCo - Ant Tasks</title> | |
| </head> | |
| <body onload="prettyPrint()"> | |
| <div class="breadcrumb"> | |
| <a href="../index.html" class="el_report">JaCoCo</a> > | |
| <a href="index.html" class="el_group">Documentation</a> > | |
| <span class="el_source">Ant Tasks</span> | |
| </div> | |
| <div id="content"> | |
| <h1>Ant Tasks</h1> | |
| <p> | |
| JaCoCo comes with Ant tasks to launch Java programs with execution recording | |
| and for creating coverage reports from the recorded data. Execution data can | |
| be collected and managed with the tasks | |
| <a href="#coverage"><code>coverage</code></a>, | |
| <a href="#agent"><code>agent</code></a>, | |
| <a href="#dump"><code>dump</code></a> and | |
| <a href="#merge"><code>merge</code></a>. Reports in different formats are | |
| creates with the <a href="#report"><code>report</code></a> task. | |
| </p> | |
| <p class="hint"> | |
| If you want to have line number information included in the coverage reports | |
| or you want source code highlighting the class files of the test target must | |
| be compiled with debug information. | |
| </p> | |
| <h2>Example</h2> | |
| <p> | |
| The JaCoCo distribution contains a simple example how code coverage can be | |
| added to a Ant based build. The | |
| <a href="examples/ant/build.xml">build script</a> compiles Java sources, runs | |
| the test program and creates a coverage report. The complete example is | |
| located in the <code>./doc/examples/ant</code> folder of the distribution. | |
| </p> | |
| <h2>Prerequisites</h2> | |
| <p> | |
| The JaCoCo Ant tasks require | |
| </p> | |
| <ul> | |
| <li>Ant 1.7.0 or higher and</li> | |
| <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li> | |
| </ul> | |
| <p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the | |
| distribution) and can be included in your Ant scripts with the usual | |
| <code>taskdef</code> declaration: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"> | |
| <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"> | |
| <classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/> | |
| </taskdef> | |
| ... | |
| </project> | |
| </pre> | |
| <p> | |
| Alternatively you might also place the <code>jacocoant.jar</code> in your | |
| Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI | |
| <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them | |
| automatically without the <code>taskdef</code> declaration above. Declaring a | |
| XML namespace for JaCoCo tasks is optional but always recommended if you mix | |
| tasks from different libraries. All subsequent examples use the | |
| <code>jacoco</code> prefix declared above. | |
| </p> | |
| <h2><a name="coverage">Task <code>coverage</code></a></h2> | |
| <p> | |
| The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and | |
| <code>testng</code>. To add code coverage recording to these tasks they can | |
| simply be wrapped with the <code>coverage</code> task as shown in the | |
| following examples: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <jacoco:coverage> | |
| <java classname="org.jacoco.examples.HelloJaCoCo" fork="true"> | |
| <classpath> | |
| <pathelement location="./bin"/> | |
| </classpath> | |
| </java> | |
| </jacoco:coverage> | |
| <jacoco:coverage> | |
| <junit fork="true" forkmode="once"> | |
| <test name="org.jacoco.examples.HelloJaCoCoTest"/> | |
| <classpath> | |
| <pathelement location="./bin"/> | |
| </classpath> | |
| </junit> | |
| </jacoco:coverage> | |
| </pre> | |
| <p> | |
| Resulting coverage information is collected during execution and written | |
| to a file when the process terminates. Note the <code>fork</code> attribute | |
| above in the wrapped <code>java</code> task. | |
| </p> | |
| <p class="hint"> | |
| The nested task always has to declare <code>fork="true"</code>, otherwise the | |
| <code>coverage</code> task can't record coverage information and will fail. | |
| In addition the <code>junit</code> task should declare | |
| <code>forkmode="once"</code> to avoid starting a new JVM for every single test | |
| case and decreasing execution performance dramatically (unless this is | |
| required by the nature of the test cases). | |
| </p> | |
| <p> | |
| The coverage task must wrap exactly one task. While it typically works without | |
| any configuration, the behavior can be adjusted with some optional attributes: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>enabled</code></td> | |
| <td>If set to <code>true</code> coverage data will be collected for the contained task.</td> | |
| <td><code>true</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>Path to the output file for execution data.</td> | |
| <td><code>jacoco.exec</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>append</code></td> | |
| <td>If set to <code>true</code> and the execution data file already | |
| exists, coverage data is appended to the existing file. If set to | |
| <code>false</code>, an existing execution data file will be replaced. | |
| </td> | |
| <td><code>true</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>includes</code></td> | |
| <td>A list of class names that should be included in execution analysis. | |
| The list entries are separated by a colon (<code>:</code>) and | |
| may use wildcard characters (<code>*</code> and <code>?</code>). | |
| Except for performance optimization or technical corner cases this | |
| option is normally not required. | |
| </td> | |
| <td><code>*</code> (all classes)</td> | |
| </tr> | |
| <tr> | |
| <td><code>excludes</code></td> | |
| <td>A list of class names that should be excluded from execution analysis. | |
| The list entries are separated by a colon (<code>:</code>) and | |
| may use wildcard characters (<code>*</code> and <code>?</code>). | |
| Except for performance optimization or technical corner cases this | |
| option is normally not required. | |
| </td> | |
| <td><i>empty</i> (no excluded classes)</td> | |
| </tr> | |
| <tr> | |
| <td><code>exclclassloader</code></td> | |
| <td>A list of class loader names, that should be excluded from execution | |
| analysis. The list entries are separated by a colon | |
| (<code>:</code>) and may use wildcard characters (<code>*</code> and | |
| <code>?</code>). This option might be required in case of special | |
| frameworks that conflict with JaCoCo code instrumentation, in | |
| particular class loaders that do not have access to the Java runtime | |
| classes. | |
| </td> | |
| <td><code>sun.reflect.DelegatingClassLoader</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>sessionid</code></td> | |
| <td>A session identifier that is written with the execution data. Without | |
| this parameter a random identifier is created by the agent. | |
| </td> | |
| <td><i>auto-generated</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>dumponexit</code></td> | |
| <td>If set to <code>true</code> coverage data will be written on VM | |
| shutdown. | |
| </td> | |
| <td><code>true</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>output</code></td> | |
| <td>Output method to use for writing coverage data. Valid options are: | |
| <ul> | |
| <li><code>file</code>: At VM termination execution data is written to | |
| the file specified in the <code>destfile</code> attribute.</li> | |
| <li><code>tcpserver</code>: The agent listens for incoming connections | |
| on the TCP port specified by the <code>address</code> and | |
| <code>port</code> attribute. Execution data is written to this | |
| TCP connection.</li> | |
| <li><code>tcpclient</code>: At startup the agent connects to the TCP | |
| port specified by the <code>address</code> and <code>port</code> | |
| attribute. Execution data is written to this TCP connection.</li> | |
| <li><code>mbean</code>: The agent registers an JMX MBean under the | |
| name <code>org.jacoco:type=Runtime</code>.</li> | |
| </ul> | |
| </td> | |
| <td><code>file</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>address</code></td> | |
| <td>IP address or hostname to bind to when the output method is | |
| <code>tcpserver</code> or connect to when the output method is | |
| <code>tcpclient</code>. In <code>tcpserver</code> mode the value | |
| "<code>*</code>" causes the agent to accept connections on any local | |
| address. | |
| </td> | |
| <td><i>loopback interface</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>port</code></td> | |
| <td>Port to bind to when the output method is <code>tcpserver</code> or | |
| connect to when the output method is <code>tcpclient</code>. In | |
| <code>tcpserver</code> mode the port must be available, which means | |
| that if multiple JaCoCo agents should run on the same machine, | |
| different ports have to be specified. | |
| </td> | |
| <td><code>6300</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2><a name="agent">Task <code>agent</code></a></h2> | |
| <p> | |
| If the <code>coverage</code> task is not suitable for your launch target, you | |
| might alternatively use the <code>agent</code> task to create the | |
| <a href="agent.html">Java agent</a> parameter. The following example defines a | |
| Ant property with the name <code>agentvmparam</code> that can be directly used | |
| as a Java VM parameter: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <jacoco:agent property="agentvmparam"/> | |
| </pre> | |
| <p> | |
| This task has the same attributes as the <code>coverage</code> task plus an | |
| additional property to specify the target property name: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>enabled</code></td> | |
| <td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively | |
| disabling coverage instrumentation for any tasks that used the value.</td> | |
| <td><code>true</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>property</code></td> | |
| <td>Name of the Ant property to set.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| <tr> | |
| <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2><a name="dump">Task <code>dump</code></a></h2> | |
| <p> | |
| This task allows to remotely collect execution data from another JVM without | |
| stopping it. For example: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/> | |
| </pre> | |
| <p> | |
| Remote dumps are usefull for long running Java processes like application | |
| servers. | |
| </p> | |
| <p class="hint"> | |
| The target JVM needs to have a <a href="agent.html">JaCoCo agent</a> | |
| configured with <code>output</code> mode <code>tcpserver</code>. See | |
| <a href="#coverage"><code>coverage</code></a> and | |
| <a href="#agent"><code>agent</code></a> tasks above. | |
| </p> | |
| <p> | |
| The <code>dump</code> task has the following attributes: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>address</code></td> | |
| <td>Target IP address or DNS name.</td> | |
| <td><code>localhost</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>port</code></td> | |
| <td>Target TCP port.</td> | |
| <td><code>6300</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>dump</code></td> | |
| <td>Flag whether execution data should be dumped.</td> | |
| <td><code>true</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>reset</code></td> | |
| <td>Flag whether execution data should be reset in the target agent after | |
| the dump.</td> | |
| <td><code>false</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>File location to write the collected execution data to.</td> | |
| <td><i>none (required if dump=true)</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>append</code></td> | |
| <td>If set to <code>true</code> and the execution data file already | |
| exists, coverage data is appended to the existing file. If set to | |
| <code>false</code>, an existing execution data file will be replaced. | |
| </td> | |
| <td><code>true</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2><a name="merge">Task <code>merge</code></a></h2> | |
| <p> | |
| This task can be used to merge the execution data from multiple test runs | |
| into a single data store. | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <jacoco:merge destfile="merged.exec"> | |
| <fileset dir="executionData" includes="*.exec"/> | |
| </jacoco:merge> | |
| </pre> | |
| <p> | |
| The task definition can contain any number of resource collection types and | |
| has the following mandatory attribute: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>File location to write the merged execution data to.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h2><a name="report">Task <code>report</code></a></h2> | |
| <p> | |
| Finally different reports can be created with the <code>report</code> task. | |
| A report task declaration consists of different sections, two specify the | |
| input data, additional ones specify the output formats: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <jacoco:report> | |
| <executiondata> | |
| <file file="jacoco.exec"/> | |
| </executiondata> | |
| <structure name="Example Project"> | |
| <classfiles> | |
| <fileset dir="classes"/> | |
| </classfiles> | |
| <sourcefiles encoding="UTF-8"> | |
| <fileset dir="src"/> | |
| </sourcefiles> | |
| </structure> | |
| <html destdir="report"/> | |
| </jacoco:report> | |
| </pre> | |
| <p> | |
| As you can see from the example above the <code>report</code> task is based | |
| on several nested elements: | |
| </p> | |
| <h3>Element <code>executiondata</code></h3> | |
| <p> | |
| Within this element Ant resources and resource collections can be specified, | |
| that represent JaCoCo execution data files. If more than one execution data | |
| file is specified, execution data is combined. A particular piece of code is | |
| considered executed when it is marked as such in any of the input files. | |
| </p> | |
| <h3>Element <code>structure</code></h3> | |
| <p> | |
| This element defines the report structure. It might contain the following | |
| nested elements: | |
| </p> | |
| <ul> | |
| <li><code>classfiles</code>: Container element for Ant resources and resource | |
| collections that can specify Java class files, ZIP archive files (jar, war, | |
| ear etc.) or folders containing class files. Archives and folders are | |
| searched recursively for class files.</li> | |
| <li><code>sourcefiles</code>: Optional container element for Ant resources and | |
| resource collections that specify corresponding source files. If source | |
| files are specified, some report formats include highlighted source code.</li> | |
| </ul> | |
| <p> | |
| The <code>sourcefiles</code> element has these optional attributes: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>encoding</code></td> | |
| <td>Character encoding of the source files.</td> | |
| <td>Platform default encoding</td> | |
| </tr> | |
| <tr> | |
| <td><code>tabwidth</code></td> | |
| <td>Number of whitespace characters that represent a tab character.</td> | |
| <td>4 characters</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p> | |
| Note that the <code>classfiles</code> and <code>sourcefiles</code> elements | |
| accept any | |
| <a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant | |
| resource collection</a>. Therefore also filtering the class file set is | |
| possible and allows to narrow the scope of the report, for example: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <classfiles> | |
| <fileset dir="classes"> | |
| <include name="org/jacoco/examples/important/**/*.class"/> | |
| </fileset> | |
| </classfiles> | |
| </pre> | |
| <p class="hint"> | |
| <b>Performance Warning:</b> Although it is technically possible and sometimes | |
| convenient to use Ant's <code>zipfileset</code> to specify class or source | |
| files, this resource type has poor performance characteristics and comes with | |
| an huge memory overhead especially for large scale projects. | |
| </p> | |
| <p> | |
| The structure can be refined with a hierarchy of <code>group</code> elements. | |
| This way the coverage report can reflect different modules of a software | |
| project. For each group element the corresponding class and source files can | |
| be specified separately. For example: | |
| </p> | |
| <pre class="source lang-xml linenums"> | |
| <structure name="Example Project"> | |
| <group name="Server"> | |
| <classfiles> | |
| <fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/> | |
| </classfiles> | |
| <sourcefiles> | |
| <fileset dir="${workspace.dir}/org.jacoco.example.server/src"/> | |
| </sourcefiles> | |
| </group> | |
| <group name="Client"> | |
| <classfiles> | |
| <fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/> | |
| </classfiles> | |
| <sourcefiles> | |
| <fileset dir="${workspace.dir}/org.jacoco.example.client/src"/> | |
| </sourcefiles> | |
| </group> | |
| ... | |
| </structure> | |
| </pre> | |
| <p> | |
| Both <code>structure</code> and <code>group</code> elements have the following | |
| mandatory attribute: | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>name</code></td> | |
| <td>Name of the structure or group.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h3>Element <code>html</code></h3> | |
| <p> | |
| Create a multi-page report in HTML format. The report can either be written as | |
| multiple files into a directory or compressed into a single ZIP file. | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>destdir</code></td> | |
| <td>Directory to create the report in. Either this property or | |
| <code>destfile</code> has to be supplied.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>Zip file to create the report in. Either this property or | |
| <code>destdir</code> has to be supplied.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>footer</code></td> | |
| <td>Footer text for each report page.</td> | |
| <td><i>no footer</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>encoding</code></td> | |
| <td>Character encoding of generated HTML pages.</td> | |
| <td><code>UTF-8</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>locale</code></td> | |
| <td>Locale specified as ISO code (en, fr, jp, ...) used for number formating.</td> | |
| <td><i>platform locale</i></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h3>Element <code>xml</code></h3> | |
| <p> | |
| Create a single-file report in XML format. | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>Location to write the report file to.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>encoding</code></td> | |
| <td>Encoding of the generated XML document.</td> | |
| <td><code>UTF-8</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <h3>Element <code>csv</code></h3> | |
| <p> | |
| Create single-file report in CSV format. | |
| </p> | |
| <table class="coverage"> | |
| <thead> | |
| <tr> | |
| <td>Attribute</td> | |
| <td>Description</td> | |
| <td>Default</td> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>destfile</code></td> | |
| <td>Location to write the report file to.</td> | |
| <td><i>none (required)</i></td> | |
| </tr> | |
| <tr> | |
| <td><code>encoding</code></td> | |
| <td>Encoding of the generated CSV document.</td> | |
| <td><code>UTF-8</code></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <div class="footer"> | |
| <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span> | |
| <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors | |
| </div> | |
| </body> | |
| </html> |