<?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" /> | |
<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_session">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. 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"> | |
<span class="nr"> 1</span><project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"> | |
<span class="nr"> 2</span> | |
<span class="nr"> 3</span> <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"> | |
<span class="nr"> 4</span> <classpath> | |
<span class="nr"> 5</span> <pathelement location="<i>path_to_jacoco</i>/lib/jacocoant.jar"/> | |
<span class="nr"> 6</span> </classpath> | |
<span class="nr"> 7</span> </taskdef> | |
<span class="nr"> 8</span> | |
<span class="nr"> 9</span> ... | |
<span class="nr"> 10</span> | |
<span class="nr"> 11</span></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. | |
</p> | |
<p> | |
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> and | |
<code>junit</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"> | |
<span class="nr"> 1</span><jacoco:coverage> | |
<span class="nr"> 2</span> <java classname="org.jacoco.examples.HelloJaCoCo" fork="true"> | |
<span class="nr"> 3</span> <classpath> | |
<span class="nr"> 4</span> <pathelement location="./bin"/> | |
<span class="nr"> 5</span> </classpath> | |
<span class="nr"> 6</span> </java> | |
<span class="nr"> 7</span></jacoco:coverage> | |
<span class="nr"> 8</span> | |
<span class="nr"> 9</span> | |
<span class="nr"> 10</span><jacoco:coverage> | |
<span class="nr"> 11</span> <junit fork="true" forkmode="once"> | |
<span class="nr"> 12</span> <test name="org.jacoco.examples.HelloJaCoCoTest"/> | |
<span class="nr"> 13</span> <classpath> | |
<span class="nr"> 14</span> <pathelement location="./bin"/> | |
<span class="nr"> 15</span> </classpath> | |
<span class="nr"> 16</span> </junit> | |
<span class="nr"> 17</span></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 vertical bar (<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 vertical bar (<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 vertical bar | |
(<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> | |
</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 Java agent | |
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"> | |
<span class="nr"> 1</span><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="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"> | |
<span class="nr"> 1</span><jacoco:merge destfile="merged.exec"> | |
<span class="nr"> 2</span> <fileset dir="executionData" includes="*.exec"/> | |
<span class="nr"> 3</span></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>Location to write the merged execution data.</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"> | |
<span class="nr"> 1</span><jacoco:report> | |
<span class="nr"> 2</span> | |
<span class="nr"> 3</span> <executiondata> | |
<span class="nr"> 4</span> <file file="jacoco.exec"/> | |
<span class="nr"> 5</span> </executiondata> | |
<span class="nr"> 6</span> | |
<span class="nr"> 7</span> <structure name="Example Project"> | |
<span class="nr"> 8</span> <classfiles> | |
<span class="nr"> 9</span> <fileset dir="bin"/> | |
<span class="nr"> 10</span> </classfiles> | |
<span class="nr"> 11</span> <sourcefiles encoding="UTF-8"> | |
<span class="nr"> 12</span> <fileset dir="src"/> | |
<span class="nr"> 13</span> </sourcefiles> | |
<span class="nr"> 14</span> </structure> | |
<span class="nr"> 15</span> | |
<span class="nr"> 16</span> <html destdir="report"/> | |
<span class="nr"> 17</span> | |
<span class="nr"> 18</span></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. The element | |
has an optional attribute <code>encoding</code> to specify the character | |
encoding of the source files. If no encoding is given, the platform default | |
is used. If source files are specified, some report formats include | |
highlighted source code.</li> | |
</ul> | |
<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, the build script of JaCoCo itself | |
contains the following declaration to separate the different bundles in the | |
report (see the <a href="../coverage/index.html">resulting report</a>): | |
</p> | |
<pre class="source lang-xml"> | |
<span class="nr"> 1</span><structure name="JaCoCo"> | |
<span class="nr"> 2</span> <group name="org.jacoco.core"> | |
<span class="nr"> 3</span> <classfiles> | |
<span class="nr"> 4</span> <path refid="bundle-org.jacoco.core"/> | |
<span class="nr"> 5</span> </classfiles> | |
<span class="nr"> 6</span> <sourcefiles> | |
<span class="nr"> 7</span> <fileset dir="${workspace.dir}/org.jacoco.core/src"/> | |
<span class="nr"> 8</span> </sourcefiles> | |
<span class="nr"> 9</span> </group> | |
<span class="nr"> 10</span> <group name="org.jacoco.report"> | |
<span class="nr"> 11</span> <classfiles> | |
<span class="nr"> 12</span> <path refid="bundle-org.jacoco.report"/> | |
<span class="nr"> 13</span> </classfiles> | |
<span class="nr"> 14</span> <sourcefiles> | |
<span class="nr"> 15</span> <fileset dir="${workspace.dir}/org.jacoco.report/src"/> | |
<span class="nr"> 16</span> </sourcefiles> | |
<span class="nr"> 17</span> </group> | |
<span class="nr"> 18</span> | |
<span class="nr"> 19</span> ... | |
<span class="nr"> 20</span> | |
<span class="nr"> 21</span></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>Encoding of the generated HTML pages.</td> | |
<td><code>UTF-8</code></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"> | |
<div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div> | |
<a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors | |
</div> | |
</body> | |
</html> |