| <?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" /> | |
| <title>JaCoCo - Ant Tasks</title> | |
| </head> | |
| <body> | |
| <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> | |
| <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"> | |
| <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>Task <code>coverage</code></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"> | |
| <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>file</code></td> | |
| <td>Path to the output file for execution data.</td> | |
| <td><code>jacoco.exec</code></td> | |
| </tr> | |
| <tr> | |
| <td><code>merge</code></td> | |
| <td>If set to <code>true</code> and the execution data file already | |
| exists, coverage data is merged 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>Task <code>agent</code></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"> | |
| <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>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>Task <code>report</code></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"> | |
| <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, JAR files or directories | |
| containing 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"> | |
| <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> | |
| <h3>Element <code>html</code></h3> | |
| <p> | |
| Create a multi-page report in HTML format. | |
| </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.</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 class="footer"> | |
| <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div> | |
| <a href="license.html">Copyright</a> © 2009 Mountainminds GmbH & Co. KG and Contributors | |
| </div> | |
| </body> | |
| </html> |