| <?xml version="1.0" encoding="UTF-8" ?> |
| <!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=UTF-8" /> |
| <link rel="stylesheet" href=".resources/doc.css" charset="UTF-8" type="text/css" /> |
| <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="UTF-8" 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. For |
| <a href="offline.html">offline instrumentation</a> the task |
| <a href="#instrument"><code>instrument</code></a> can be used to prepare class |
| files. |
| </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/build/build.xml">build script</a> compiles Java sources, |
| runs an simple Java programm and creates a coverage report. The complete |
| example is located in the <code>./doc/examples/build</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. |
| </p> |
| |
| <p class="hint"> |
| 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. If you don't declare a separate |
| namespace the <code>jacoco</code> prefix must be removed from the following |
| examples. |
| </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>inclbootstrapclasses</code></td> |
| <td>Specifies whether also classes from the bootstrap classloader should |
| be instrumented. Use this feature with caution, it needs heavy |
| includes/excludes tuning. |
| </td> |
| <td><code>false</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>none</code>: Do not produce any output.</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> |
| <tr> |
| <td><code>classdumpdir</code></td> |
| <td>Location relative to the working directory where all class files seen |
| by the agent are dumped to. This can be useful for debugging purposes |
| or in case of dynamically created classes for example when scripting |
| engines are used. |
| </td> |
| <td><i>no dumps</i></td> |
| </tr> |
| <tr> |
| <td><code>jmx</code></td> |
| <td>If set to <code>true</code> the agent exposes |
| <a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via |
| JMX under the name <code>org.jacoco:type=Runtime</code>. |
| </td> |
| <td><code>false</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>retryCount</code></td> |
| <td>Number of retries which the goal will attempt to establish a |
| connection. This can be used to wait until the target JVM is |
| successfully launched.</td> |
| <td><code>10</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, archive files (jar, war, ear |
| etc. or Pack200) 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. |
| Source files can be specified as individual files or as source directories.</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 class="hint"> |
| <b>Important:</b> Source file resources must always be specified relative to |
| the respective source folder. If directory resources are given, they must |
| directly point to source folders. Otherwise source lookup will not succeed. |
| </p> |
| |
| <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. Locale country and variant can be separated with an underscore |
| (de_CH).</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> |
| |
| <h3>Element <code>check</code></h3> |
| |
| <p> |
| This report type does not actually create a report. It checks coverage |
| counters and reports violations of configured rules. Every rule is applied to |
| elements of a given type (class, package, bundle, etc.) and has a list of |
| limits which are checked for every element. The following example checks that |
| for every package the line coverage is at least 80% and no class is missed: |
| </p> |
| |
| <pre class="source lang-xml linenums"> |
| <check> |
| <rule element="PACKAGE"> |
| <limit counter="LINE" value="COVEREDRATIO" minimum="0.80"/> |
| <limit counter="CLASS" value="MISSEDCOUNT" maximum="0"/> |
| </rule> |
| </check> |
| </pre> |
| |
| <p> |
| The <code>check</code> element 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>rules</code></td> |
| <td>List of rules to check.</td> |
| <td><i>none</i></td> |
| </tr> |
| <tr> |
| <td><code>failonviolation</code></td> |
| <td>Specifies whether build should fail in case of rule violations.</td> |
| <td><code>true</code></td> |
| </tr> |
| <tr> |
| <td><code>violationsproperty</code></td> |
| <td>The name of an Ant property which is filled with the violation |
| messages.</td> |
| <td><i>none</i></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p> |
| Within the <code>check</code> element any number of <code>rule</code> elements |
| can be nested: |
| </p> |
| |
| <table class="coverage"> |
| <thead> |
| <tr> |
| <td>Attribute</td> |
| <td>Description</td> |
| <td>Default</td> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code>element</code></td> |
| <td>The elements this rule applies to. Possible values are |
| <code>BUNLDE</code>, <code>PACKAGE</code>, <code>CLASS</code>, |
| <code>SOURCEFILE</code> and <code>METHOD</code>.</td> |
| <td><code>BUNLDE</code></td> |
| </tr> |
| <tr> |
| <td><code>includes</code></td> |
| <td>A list of element names that should be checked. The list entries are |
| separated by a colon (:) and may use wildcard characters (* and ?).</td> |
| <td><code>*</code></td> |
| </tr> |
| <tr> |
| <td><code>excludes</code></td> |
| <td>A list of element names that should not be checked. The list entries |
| are separated by a colon (:) and may use wildcard characters (* and ?).</td> |
| <td><i>empty (no excludes)</i></td> |
| </tr> |
| <tr> |
| <td><code>limits</code></td> |
| <td>List of limits to check.</td> |
| <td><i>none</i></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p> |
| Within the <code>rule</code> element any number of <code>limit</code> elements |
| can be nested: |
| </p> |
| |
| <table class="coverage"> |
| <thead> |
| <tr> |
| <td>Attribute</td> |
| <td>Description</td> |
| <td>Default</td> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code>counter</code></td> |
| <td>The <a href="counters.html">counter</a> which should be checked. |
| Possible options are <code>INSTRUCTION</code>, <code>LINE</code>, |
| <code>BRANCH</code>, <code>COMPLEXITY</code>, <code>METHOD</code> and |
| <code>CLASS</code>.</td> |
| <td><code>INSTRUCTION</code></td> |
| </tr> |
| <tr> |
| <td><code>value</code></td> |
| <td>The counter value that should be checked. Possible options are |
| <code>TOTALCOUNT</code>, <code>MISSEDCOUNT</code>, |
| <code>COVEREDCOUNT</code>, <code>MISSEDRATIO</code> and |
| <code>COVEREDRATIO</code>.</td> |
| <td><code>COVEREDRATIO</code></td> |
| </tr> |
| <tr> |
| <td><code>minimum</code></td> |
| <td>Expected minmimum value. If the minimum refers to a ratio the range is |
| from 0.0 to 1.0 where the number of decimal places will also determine |
| the precision in error messages.</td> |
| <td><i>none</i></td> |
| </tr> |
| <tr> |
| <td><code>maximum</code></td> |
| <td>Expected maximum value.</td> |
| <td><i>none</i></td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h2><a name="instrument">Task <code>instrument</code></a></h2> |
| |
| <p class="hint"> |
| <b>Warning:</b> The preferred way for code coverage analysis with JaCoCo is |
| on-the-fly instrumentation. Offline instrumentation has several drawbacks and |
| should only be used if a specific scenario explicitly requires this mode. |
| Please consult <a href="offline.html">documentation</a> about offline |
| instrumentation before using this mode. |
| </p> |
| |
| <p> |
| This task is used for <a href="offline.html">offline instrumentation</a> of |
| class files. The task takes a set of files and writes instrumented |
| versions to a specified location. The task takes any file type as input. Java |
| class files are instrumented. Archives (jar, war, ear etc. or Pack200) are |
| searched recursively for class files which then get instrumented. All other |
| files are copied without modification. |
| </p> |
| |
| <pre class="source lang-xml linenums"> |
| <jacoco:instrument destdir="target/classes-instr"> |
| <fileset dir="target/classes" includes="**/*.class"/> |
| </jacoco:instrument> |
| </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>destdir</code></td> |
| <td>Directory location to write the instrumented files to.</td> |
| <td><i>none (required)</i></td> |
| </tr> |
| <tr> |
| <td><code>removesignatures</code></td> |
| <td>If set to <code>true</code> all signature related information is |
| stripped from JARs. This is typically necessary as instrumentation |
| breaks the signatures of the original class files.</td> |
| <td><code>true</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> |