| 1 |
<?xml version="1.0" encoding="UTF-8" ?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 6 |
<link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> |
| 7 |
<link rel="stylesheet" href="../coverage/jacoco-resources/prettify.css" charset="UTF-8" type="text/css" /> |
| 8 |
<link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> |
| 9 |
<script type="text/javascript" src="../coverage/jacoco-resources/prettify.js"></script> |
| 10 |
<title>JaCoCo - Ant Tasks</title> |
| 11 |
</head> |
| 12 |
<body onload="prettyPrint()"> |
| 13 |
|
| 14 |
<div class="breadcrumb"> |
| 15 |
<a href="../index.html" class="el_report">JaCoCo</a> > |
| 16 |
<a href="index.html" class="el_group">Documentation</a> > |
| 17 |
<span class="el_source">Ant Tasks</span> |
| 18 |
</div> |
| 19 |
<div id="content"> |
| 20 |
|
| 21 |
<h1>Ant Tasks</h1> |
| 22 |
|
| 23 |
<p> |
| 24 |
JaCoCo comes with Ant tasks to launch Java programs with execution recording |
| 25 |
and for creating coverage reports from the recorded data. Execution data can |
| 26 |
be collected and managed with the tasks |
| 27 |
<a href="#coverage"><code>coverage</code></a>, |
| 28 |
<a href="#agent"><code>agent</code></a>, |
| 29 |
<a href="#dump"><code>dump</code></a> and |
| 30 |
<a href="#merge"><code>merge</code></a>. Reports in different formats are |
| 31 |
created with the <a href="#report"><code>report</code></a> task. For |
| 32 |
<a href="offline.html">offline instrumentation</a> the task |
| 33 |
<a href="#instrument"><code>instrument</code></a> can be used to prepare class |
| 34 |
files. |
| 35 |
</p> |
| 36 |
|
| 37 |
<p class="hint"> |
| 38 |
If you want to have line number information included in the coverage reports |
| 39 |
or you want source code highlighting the class files of the test target must |
| 40 |
be compiled with debug information. |
| 41 |
</p> |
| 42 |
|
| 43 |
<h2>Example</h2> |
| 44 |
|
| 45 |
<p> |
| 46 |
The JaCoCo distribution contains a simple example how code coverage can be |
| 47 |
added to a Ant based build. The |
| 48 |
<a href="examples/build/build.xml">build script</a> compiles Java sources, |
| 49 |
runs an simple Java program and creates a coverage report. The complete |
| 50 |
example is located in the <code>./doc/examples/build</code> folder of the |
| 51 |
distribution. |
| 52 |
</p> |
| 53 |
|
| 54 |
|
| 55 |
<h2>Prerequisites</h2> |
| 56 |
|
| 57 |
<p> |
| 58 |
The JaCoCo Ant tasks require |
| 59 |
</p> |
| 60 |
|
| 61 |
<ul> |
| 62 |
<li>Ant 1.7.0 or higher and</li> |
| 63 |
<li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li> |
| 64 |
</ul> |
| 65 |
|
| 66 |
|
| 67 |
<p>All tasks are defined in <code>jacocoant.jar</code> (which is part of the |
| 68 |
distribution) and can be included in your Ant scripts with the usual |
| 69 |
<code>taskdef</code> declaration: |
| 70 |
</p> |
| 71 |
|
| 72 |
<pre class="source lang-xml linenums"> |
| 73 |
<project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"> |
| 74 |
|
| 75 |
<taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"> |
| 76 |
<classpath path="<i>path_to_jacoco</i>/lib/jacocoant.jar"/> |
| 77 |
</taskdef> |
| 78 |
|
| 79 |
... |
| 80 |
|
| 81 |
</project> |
| 82 |
</pre> |
| 83 |
|
| 84 |
<p> |
| 85 |
Alternatively you might also place the <code>jacocoant.jar</code> in your |
| 86 |
Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI |
| 87 |
<code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them |
| 88 |
automatically without the <code>taskdef</code> declaration above. |
| 89 |
</p> |
| 90 |
|
| 91 |
<p class="hint"> |
| 92 |
Declaring an XML namespace for JaCoCo tasks is optional but always recommended |
| 93 |
if you mix tasks from different libraries. All subsequent examples use the |
| 94 |
<code>jacoco</code> prefix declared above. If you don't declare a separate |
| 95 |
namespace the <code>jacoco</code> prefix must be removed from the following |
| 96 |
examples. |
| 97 |
</p> |
| 98 |
|
| 99 |
<h2><a name="coverage">Task <code>coverage</code></a></h2> |
| 100 |
|
| 101 |
<p> |
| 102 |
The standard Ant tasks to launch Java programs are <code>java</code>, <code>junit</code> and |
| 103 |
<code>testng</code>. To add code coverage recording to these tasks they can |
| 104 |
simply be wrapped with the <code>coverage</code> task as shown in the |
| 105 |
following examples: |
| 106 |
</p> |
| 107 |
|
| 108 |
<pre class="source lang-xml linenums"> |
| 109 |
<jacoco:coverage> |
| 110 |
<java classname="org.jacoco.examples.HelloJaCoCo" fork="true"> |
| 111 |
<classpath> |
| 112 |
<pathelement location="./bin"/> |
| 113 |
</classpath> |
| 114 |
</java> |
| 115 |
</jacoco:coverage> |
| 116 |
|
| 117 |
|
| 118 |
<jacoco:coverage> |
| 119 |
<junit fork="true" forkmode="once"> |
| 120 |
<test name="org.jacoco.examples.HelloJaCoCoTest"/> |
| 121 |
<classpath> |
| 122 |
<pathelement location="./bin"/> |
| 123 |
</classpath> |
| 124 |
</junit> |
| 125 |
</jacoco:coverage> |
| 126 |
</pre> |
| 127 |
|
| 128 |
<p> |
| 129 |
Resulting coverage information is collected during execution and written |
| 130 |
to a file when the process terminates. Note the <code>fork</code> attribute |
| 131 |
above in the wrapped <code>java</code> task. |
| 132 |
</p> |
| 133 |
|
| 134 |
<p class="hint"> |
| 135 |
The nested task always has to declare <code>fork="true"</code>, otherwise the |
| 136 |
<code>coverage</code> task can't record coverage information and will fail. |
| 137 |
In addition the <code>junit</code> task should declare |
| 138 |
<code>forkmode="once"</code> to avoid starting a new JVM for every single test |
| 139 |
case and decreasing execution performance dramatically (unless this is |
| 140 |
required by the nature of the test cases). Note that |
| 141 |
<code>forkmode="perTest"</code> or <code>forkmode="perBatch"</code> should not |
| 142 |
be combined with <code>append="false"</code> as the execution data file is |
| 143 |
overwritten with the execution of every test. |
| 144 |
</p> |
| 145 |
|
| 146 |
<p> |
| 147 |
The coverage task must wrap exactly one task. While it typically works without |
| 148 |
any configuration, the behavior can be adjusted with some optional attributes: |
| 149 |
</p> |
| 150 |
|
| 151 |
<table class="coverage"> |
| 152 |
<thead> |
| 153 |
<tr> |
| 154 |
<td>Attribute</td> |
| 155 |
<td>Description</td> |
| 156 |
<td>Default</td> |
| 157 |
</tr> |
| 158 |
</thead> |
| 159 |
<tbody> |
| 160 |
<tr> |
| 161 |
<td><code>enabled</code></td> |
| 162 |
<td>If set to <code>true</code> coverage data will be collected for the contained task.</td> |
| 163 |
<td><code>true</code></td> |
| 164 |
</tr> |
| 165 |
<tr> |
| 166 |
<td><code>destfile</code></td> |
| 167 |
<td>Path to the output file for execution data.</td> |
| 168 |
<td><code>jacoco.exec</code></td> |
| 169 |
</tr> |
| 170 |
<tr> |
| 171 |
<td><code>append</code></td> |
| 172 |
<td>If set to <code>true</code> and the execution data file already |
| 173 |
exists, coverage data is appended to the existing file. If set to |
| 174 |
<code>false</code>, an existing execution data file will be replaced. |
| 175 |
</td> |
| 176 |
<td><code>true</code></td> |
| 177 |
</tr> |
| 178 |
<tr> |
| 179 |
<td><code>includes</code></td> |
| 180 |
<td>A list of class names that should be included in execution analysis. |
| 181 |
The list entries are separated by a colon (<code>:</code>) and |
| 182 |
may use wildcard characters (<code>*</code> and <code>?</code>). |
| 183 |
Except for performance optimization or technical corner cases this |
| 184 |
option is normally not required. |
| 185 |
</td> |
| 186 |
<td><code>*</code> (all classes)</td> |
| 187 |
</tr> |
| 188 |
<tr> |
| 189 |
<td><code>excludes</code></td> |
| 190 |
<td>A list of class names that should be excluded from execution analysis. |
| 191 |
The list entries are separated by a colon (<code>:</code>) and |
| 192 |
may use wildcard characters (<code>*</code> and <code>?</code>). |
| 193 |
Except for performance optimization or technical corner cases this |
| 194 |
option is normally not required. If you want to exclude classes from |
| 195 |
the report please configure the <code>report</code> task accordingly. |
| 196 |
</td> |
| 197 |
<td><i>empty</i> (no excluded classes)</td> |
| 198 |
</tr> |
| 199 |
<tr> |
| 200 |
<td><code>exclclassloader</code></td> |
| 201 |
<td>A list of class loader names, that should be excluded from execution |
| 202 |
analysis. The list entries are separated by a colon |
| 203 |
(<code>:</code>) and may use wildcard characters (<code>*</code> and |
| 204 |
<code>?</code>). This option might be required in case of special |
| 205 |
frameworks that conflict with JaCoCo code instrumentation, in |
| 206 |
particular class loaders that do not have access to the Java runtime |
| 207 |
classes. |
| 208 |
</td> |
| 209 |
<td><code>sun.reflect.DelegatingClassLoader</code></td> |
| 210 |
</tr> |
| 211 |
<tr> |
| 212 |
<td><code>inclbootstrapclasses</code></td> |
| 213 |
<td>Specifies whether also classes from the bootstrap classloader should |
| 214 |
be instrumented. Use this feature with caution, it needs heavy |
| 215 |
includes/excludes tuning. |
| 216 |
</td> |
| 217 |
<td><code>false</code></td> |
| 218 |
</tr> |
| 219 |
<tr> |
| 220 |
<td><code>inclnolocationclasses</code></td> |
| 221 |
<td>Specifies whether also classes without a source location should be |
| 222 |
instrumented. Normally such classes are generated at runtime e.g. by |
| 223 |
mocking frameworks and are therefore excluded by default. |
| 224 |
</td> |
| 225 |
<td><code>false</code></td> |
| 226 |
</tr> |
| 227 |
<tr> |
| 228 |
<td><code>sessionid</code></td> |
| 229 |
<td>A session identifier that is written with the execution data. Without |
| 230 |
this parameter a random identifier is created by the agent. |
| 231 |
</td> |
| 232 |
<td><i>auto-generated</i></td> |
| 233 |
</tr> |
| 234 |
<tr> |
| 235 |
<td><code>dumponexit</code></td> |
| 236 |
<td>If set to <code>true</code> coverage data will be written on VM |
| 237 |
shutdown. |
| 238 |
</td> |
| 239 |
<td><code>true</code></td> |
| 240 |
</tr> |
| 241 |
<tr> |
| 242 |
<td><code>output</code></td> |
| 243 |
<td>Output method to use for writing coverage data. Valid options are: |
| 244 |
<ul> |
| 245 |
<li><code>file</code>: At VM termination execution data is written to |
| 246 |
the file specified in the <code>destfile</code> attribute.</li> |
| 247 |
<li><code>tcpserver</code>: The agent listens for incoming connections |
| 248 |
on the TCP port specified by the <code>address</code> and |
| 249 |
<code>port</code> attribute. Execution data is written to this |
| 250 |
TCP connection.</li> |
| 251 |
<li><code>tcpclient</code>: At startup the agent connects to the TCP |
| 252 |
port specified by the <code>address</code> and <code>port</code> |
| 253 |
attribute. Execution data is written to this TCP connection.</li> |
| 254 |
<li><code>none</code>: Do not produce any output.</li> |
| 255 |
</ul> |
| 256 |
</td> |
| 257 |
<td><code>file</code></td> |
| 258 |
</tr> |
| 259 |
<tr> |
| 260 |
<td><code>address</code></td> |
| 261 |
<td>IP address or hostname to bind to when the output method is |
| 262 |
<code>tcpserver</code> or connect to when the output method is |
| 263 |
<code>tcpclient</code>. In <code>tcpserver</code> mode the value |
| 264 |
"<code>*</code>" causes the agent to accept connections on any local |
| 265 |
address. |
| 266 |
</td> |
| 267 |
<td><i>loopback interface</i></td> |
| 268 |
</tr> |
| 269 |
<tr> |
| 270 |
<td><code>port</code></td> |
| 271 |
<td>Port to bind to when the output method is <code>tcpserver</code> or |
| 272 |
connect to when the output method is <code>tcpclient</code>. In |
| 273 |
<code>tcpserver</code> mode the port must be available, which means |
| 274 |
that if multiple JaCoCo agents should run on the same machine, |
| 275 |
different ports have to be specified. |
| 276 |
</td> |
| 277 |
<td><code>6300</code></td> |
| 278 |
</tr> |
| 279 |
<tr> |
| 280 |
<td><code>classdumpdir</code></td> |
| 281 |
<td>Location relative to the working directory where all class files seen |
| 282 |
by the agent are dumped to. This can be useful for debugging purposes |
| 283 |
or in case of dynamically created classes for example when scripting |
| 284 |
engines are used. |
| 285 |
</td> |
| 286 |
<td><i>no dumps</i></td> |
| 287 |
</tr> |
| 288 |
<tr> |
| 289 |
<td><code>jmx</code></td> |
| 290 |
<td>If set to <code>true</code> the agent exposes |
| 291 |
<a href="./api/org/jacoco/agent/rt/IAgent.html">functionality</a> via |
| 292 |
JMX under the name <code>org.jacoco:type=Runtime</code>. |
| 293 |
</td> |
| 294 |
<td><code>false</code></td> |
| 295 |
</tr> |
| 296 |
</tbody> |
| 297 |
</table> |
| 298 |
|
| 299 |
|
| 300 |
<h2><a name="agent">Task <code>agent</code></a></h2> |
| 301 |
|
| 302 |
<p> |
| 303 |
If the <code>coverage</code> task is not suitable for your launch target, you |
| 304 |
might alternatively use the <code>agent</code> task to create the |
| 305 |
<a href="agent.html">Java agent</a> parameter. The following example defines a |
| 306 |
Ant property with the name <code>agentvmparam</code> that can be directly used |
| 307 |
as a Java VM parameter: |
| 308 |
</p> |
| 309 |
|
| 310 |
<pre class="source lang-xml linenums"> |
| 311 |
<jacoco:agent property="agentvmparam"/> |
| 312 |
</pre> |
| 313 |
|
| 314 |
<p> |
| 315 |
This task has the same attributes as the <code>coverage</code> task plus an |
| 316 |
additional property to specify the target property name: |
| 317 |
</p> |
| 318 |
|
| 319 |
<table class="coverage"> |
| 320 |
<thead> |
| 321 |
<tr> |
| 322 |
<td>Attribute</td> |
| 323 |
<td>Description</td> |
| 324 |
<td>Default</td> |
| 325 |
</tr> |
| 326 |
</thead> |
| 327 |
<tbody> |
| 328 |
<tr> |
| 329 |
<td><code>enabled</code></td> |
| 330 |
<td>When this variable is set to <code>false</code> the value of <code>property</code> will be set to an empty string, effectively |
| 331 |
disabling coverage instrumentation for any tasks that used the value.</td> |
| 332 |
<td><code>true</code></td> |
| 333 |
</tr> |
| 334 |
<tr> |
| 335 |
<td><code>property</code></td> |
| 336 |
<td>Name of the Ant property to set.</td> |
| 337 |
<td><i>none (required)</i></td> |
| 338 |
</tr> |
| 339 |
<tr> |
| 340 |
<td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td> |
| 341 |
</tr> |
| 342 |
</tbody> |
| 343 |
</table> |
| 344 |
|
| 345 |
|
| 346 |
<h2><a name="dump">Task <code>dump</code></a></h2> |
| 347 |
|
| 348 |
<p> |
| 349 |
This task allows to remotely collect execution data from another JVM without |
| 350 |
stopping it. For example: |
| 351 |
</p> |
| 352 |
|
| 353 |
<pre class="source lang-xml linenums"> |
| 354 |
<jacoco:dump address="server.example.com" reset="true" destfile="remote.exec"/> |
| 355 |
</pre> |
| 356 |
|
| 357 |
<p> |
| 358 |
Remote dumps are usefull for long running Java processes like application |
| 359 |
servers. |
| 360 |
</p> |
| 361 |
|
| 362 |
<p class="hint"> |
| 363 |
The target JVM needs to have a <a href="agent.html">JaCoCo agent</a> |
| 364 |
configured with <code>output</code> mode <code>tcpserver</code>. See |
| 365 |
<a href="#coverage"><code>coverage</code></a> and |
| 366 |
<a href="#agent"><code>agent</code></a> tasks above. |
| 367 |
</p> |
| 368 |
|
| 369 |
<p> |
| 370 |
The <code>dump</code> task has the following attributes: |
| 371 |
</p> |
| 372 |
|
| 373 |
<table class="coverage"> |
| 374 |
<thead> |
| 375 |
<tr> |
| 376 |
<td>Attribute</td> |
| 377 |
<td>Description</td> |
| 378 |
<td>Default</td> |
| 379 |
</tr> |
| 380 |
</thead> |
| 381 |
<tbody> |
| 382 |
<tr> |
| 383 |
<td><code>address</code></td> |
| 384 |
<td>Target IP address or DNS name.</td> |
| 385 |
<td><code>localhost</code></td> |
| 386 |
</tr> |
| 387 |
<tr> |
| 388 |
<td><code>port</code></td> |
| 389 |
<td>Target TCP port.</td> |
| 390 |
<td><code>6300</code></td> |
| 391 |
</tr> |
| 392 |
<tr> |
| 393 |
<td><code>retryCount</code></td> |
| 394 |
<td>Number of retries which the goal will attempt to establish a |
| 395 |
connection. This can be used to wait until the target JVM is |
| 396 |
successfully launched.</td> |
| 397 |
<td><code>10</code></td> |
| 398 |
</tr> |
| 399 |
<tr> |
| 400 |
<td><code>dump</code></td> |
| 401 |
<td>Flag whether execution data should be dumped.</td> |
| 402 |
<td><code>true</code></td> |
| 403 |
</tr> |
| 404 |
<tr> |
| 405 |
<td><code>reset</code></td> |
| 406 |
<td>Flag whether execution data should be reset in the target agent after |
| 407 |
the dump.</td> |
| 408 |
<td><code>false</code></td> |
| 409 |
</tr> |
| 410 |
<tr> |
| 411 |
<td><code>destfile</code></td> |
| 412 |
<td>File location to write the collected execution data to.</td> |
| 413 |
<td><i>none (required if dump=true)</i></td> |
| 414 |
</tr> |
| 415 |
<tr> |
| 416 |
<td><code>append</code></td> |
| 417 |
<td>If set to <code>true</code> and the execution data file already |
| 418 |
exists, coverage data is appended to the existing file. If set to |
| 419 |
<code>false</code>, an existing execution data file will be replaced. |
| 420 |
</td> |
| 421 |
<td><code>true</code></td> |
| 422 |
</tr> |
| 423 |
</tbody> |
| 424 |
</table> |
| 425 |
|
| 426 |
|
| 427 |
<h2><a name="merge">Task <code>merge</code></a></h2> |
| 428 |
|
| 429 |
<p> |
| 430 |
This task can be used to merge the execution data from multiple test runs |
| 431 |
into a single data store. |
| 432 |
</p> |
| 433 |
|
| 434 |
<pre class="source lang-xml linenums"> |
| 435 |
<jacoco:merge destfile="merged.exec"> |
| 436 |
<fileset dir="executionData" includes="*.exec"/> |
| 437 |
</jacoco:merge> |
| 438 |
</pre> |
| 439 |
|
| 440 |
<p> |
| 441 |
The task definition can contain any number of resource collection types and |
| 442 |
has the following mandatory attribute: |
| 443 |
</p> |
| 444 |
|
| 445 |
<table class="coverage"> |
| 446 |
<thead> |
| 447 |
<tr> |
| 448 |
<td>Attribute</td> |
| 449 |
<td>Description</td> |
| 450 |
<td>Default</td> |
| 451 |
</tr> |
| 452 |
</thead> |
| 453 |
<tbody> |
| 454 |
<tr> |
| 455 |
<td><code>destfile</code></td> |
| 456 |
<td>File location to write the merged execution data to.</td> |
| 457 |
<td><i>none (required)</i></td> |
| 458 |
</tr> |
| 459 |
</tbody> |
| 460 |
</table> |
| 461 |
|
| 462 |
|
| 463 |
<h2><a name="report">Task <code>report</code></a></h2> |
| 464 |
|
| 465 |
<p> |
| 466 |
Finally different reports can be created with the <code>report</code> task. |
| 467 |
A report task declaration consists of different sections, two specify the |
| 468 |
input data, additional ones specify the output formats: |
| 469 |
</p> |
| 470 |
|
| 471 |
<pre class="source lang-xml linenums"> |
| 472 |
<jacoco:report> |
| 473 |
|
| 474 |
<executiondata> |
| 475 |
<file file="jacoco.exec"/> |
| 476 |
</executiondata> |
| 477 |
|
| 478 |
<structure name="Example Project"> |
| 479 |
<classfiles> |
| 480 |
<fileset dir="classes"/> |
| 481 |
</classfiles> |
| 482 |
<sourcefiles encoding="UTF-8"> |
| 483 |
<fileset dir="src"/> |
| 484 |
</sourcefiles> |
| 485 |
</structure> |
| 486 |
|
| 487 |
<html destdir="report"/> |
| 488 |
|
| 489 |
</jacoco:report> |
| 490 |
</pre> |
| 491 |
|
| 492 |
<p> |
| 493 |
As you can see from the example above the <code>report</code> task is based |
| 494 |
on several nested elements: |
| 495 |
</p> |
| 496 |
|
| 497 |
<h3>Element <code>executiondata</code></h3> |
| 498 |
|
| 499 |
<p> |
| 500 |
Within this element Ant resources and resource collections can be specified, |
| 501 |
that represent JaCoCo execution data files. If more than one execution data |
| 502 |
file is specified, execution data is combined. A particular piece of code is |
| 503 |
considered executed when it is marked as such in any of the input files. |
| 504 |
</p> |
| 505 |
|
| 506 |
<h3>Element <code>structure</code></h3> |
| 507 |
|
| 508 |
<p> |
| 509 |
This element defines the report structure. It might contain the following |
| 510 |
nested elements: |
| 511 |
</p> |
| 512 |
|
| 513 |
<ul> |
| 514 |
<li><code>classfiles</code>: Container element for Ant resources and resource |
| 515 |
collections that can specify Java class files, archive files (jar, war, ear |
| 516 |
etc. or Pack200) or folders containing class files. Archives and folders are |
| 517 |
searched recursively for class files.</li> |
| 518 |
<li><code>sourcefiles</code>: Optional container element for Ant resources and |
| 519 |
resource collections that specify corresponding source files. If source |
| 520 |
files are specified, some report formats include highlighted source code. |
| 521 |
Source files can be specified as individual files or as source directories.</li> |
| 522 |
</ul> |
| 523 |
|
| 524 |
<p> |
| 525 |
The <code>sourcefiles</code> element has these optional attributes: |
| 526 |
</p> |
| 527 |
|
| 528 |
<table class="coverage"> |
| 529 |
<thead> |
| 530 |
<tr> |
| 531 |
<td>Attribute</td> |
| 532 |
<td>Description</td> |
| 533 |
<td>Default</td> |
| 534 |
</tr> |
| 535 |
</thead> |
| 536 |
<tbody> |
| 537 |
<tr> |
| 538 |
<td><code>encoding</code></td> |
| 539 |
<td>Character encoding of the source files.</td> |
| 540 |
<td>Platform default encoding</td> |
| 541 |
</tr> |
| 542 |
<tr> |
| 543 |
<td><code>tabwidth</code></td> |
| 544 |
<td>Number of whitespace characters that represent a tab character.</td> |
| 545 |
<td>4 characters</td> |
| 546 |
</tr> |
| 547 |
</tbody> |
| 548 |
</table> |
| 549 |
|
| 550 |
<p class="hint"> |
| 551 |
<b>Important:</b> Source file resources must always be specified relative to |
| 552 |
the respective source folder. If directory resources are given, they must |
| 553 |
directly point to source folders. Otherwise source lookup will not succeed. |
| 554 |
</p> |
| 555 |
|
| 556 |
<p> |
| 557 |
Note that the <code>classfiles</code> and <code>sourcefiles</code> elements |
| 558 |
accept any |
| 559 |
<a href="http://ant.apache.org/manual/Types/resources.html#collection">Ant |
| 560 |
resource collection</a>. Therefore also filtering the class file set is |
| 561 |
possible and allows to narrow the scope of the report, for example: |
| 562 |
</p> |
| 563 |
|
| 564 |
<pre class="source lang-xml linenums"> |
| 565 |
<classfiles> |
| 566 |
<fileset dir="classes"> |
| 567 |
<include name="org/jacoco/examples/important/**/*.class"/> |
| 568 |
</fileset> |
| 569 |
</classfiles> |
| 570 |
</pre> |
| 571 |
|
| 572 |
<p class="hint"> |
| 573 |
<b>Performance Warning:</b> Although it is technically possible and sometimes |
| 574 |
convenient to use Ant's <code>zipfileset</code> to specify class or source |
| 575 |
files, this resource type has poor performance characteristics and comes with |
| 576 |
an huge memory overhead especially for large scale projects. |
| 577 |
</p> |
| 578 |
|
| 579 |
<p> |
| 580 |
The structure can be refined with a hierarchy of <code>group</code> elements. |
| 581 |
This way the coverage report can reflect different modules of a software |
| 582 |
project. For each group element the corresponding class and source files can |
| 583 |
be specified separately. For example: |
| 584 |
</p> |
| 585 |
|
| 586 |
<pre class="source lang-xml linenums"> |
| 587 |
<structure name="Example Project"> |
| 588 |
<group name="Server"> |
| 589 |
<classfiles> |
| 590 |
<fileset dir="${workspace.dir}/org.jacoco.example.server/classes"/> |
| 591 |
</classfiles> |
| 592 |
<sourcefiles> |
| 593 |
<fileset dir="${workspace.dir}/org.jacoco.example.server/src"/> |
| 594 |
</sourcefiles> |
| 595 |
</group> |
| 596 |
<group name="Client"> |
| 597 |
<classfiles> |
| 598 |
<fileset dir="${workspace.dir}/org.jacoco.example.client/classes"/> |
| 599 |
</classfiles> |
| 600 |
<sourcefiles> |
| 601 |
<fileset dir="${workspace.dir}/org.jacoco.example.client/src"/> |
| 602 |
</sourcefiles> |
| 603 |
</group> |
| 604 |
|
| 605 |
... |
| 606 |
|
| 607 |
</structure> |
| 608 |
</pre> |
| 609 |
|
| 610 |
<p> |
| 611 |
Both <code>structure</code> and <code>group</code> elements have the following |
| 612 |
mandatory attribute: |
| 613 |
</p> |
| 614 |
|
| 615 |
<table class="coverage"> |
| 616 |
<thead> |
| 617 |
<tr> |
| 618 |
<td>Attribute</td> |
| 619 |
<td>Description</td> |
| 620 |
<td>Default</td> |
| 621 |
</tr> |
| 622 |
</thead> |
| 623 |
<tbody> |
| 624 |
<tr> |
| 625 |
<td><code>name</code></td> |
| 626 |
<td>Name of the structure or group.</td> |
| 627 |
<td><i>none (required)</i></td> |
| 628 |
</tr> |
| 629 |
</tbody> |
| 630 |
</table> |
| 631 |
|
| 632 |
<h3>Element <code>html</code></h3> |
| 633 |
|
| 634 |
<p> |
| 635 |
Create a multi-page report in HTML format. The report can either be written as |
| 636 |
multiple files into a directory or compressed into a single ZIP file. |
| 637 |
</p> |
| 638 |
|
| 639 |
<table class="coverage"> |
| 640 |
<thead> |
| 641 |
<tr> |
| 642 |
<td>Attribute</td> |
| 643 |
<td>Description</td> |
| 644 |
<td>Default</td> |
| 645 |
</tr> |
| 646 |
</thead> |
| 647 |
<tbody> |
| 648 |
<tr> |
| 649 |
<td><code>destdir</code></td> |
| 650 |
<td>Directory to create the report in. Either this property or |
| 651 |
<code>destfile</code> has to be supplied.</td> |
| 652 |
<td><i>none (required)</i></td> |
| 653 |
</tr> |
| 654 |
<tr> |
| 655 |
<td><code>destfile</code></td> |
| 656 |
<td>Zip file to create the report in. Either this property or |
| 657 |
<code>destdir</code> has to be supplied.</td> |
| 658 |
<td><i>none (required)</i></td> |
| 659 |
</tr> |
| 660 |
<tr> |
| 661 |
<td><code>footer</code></td> |
| 662 |
<td>Footer text for each report page.</td> |
| 663 |
<td><i>no footer</i></td> |
| 664 |
</tr> |
| 665 |
<tr> |
| 666 |
<td><code>encoding</code></td> |
| 667 |
<td>Character encoding of generated HTML pages.</td> |
| 668 |
<td><code>UTF-8</code></td> |
| 669 |
</tr> |
| 670 |
<tr> |
| 671 |
<td><code>locale</code></td> |
| 672 |
<td>Locale specified as ISO code (en, fr, jp, ...) used for number |
| 673 |
formatting. Locale country and variant can be separated with an underscore |
| 674 |
(de_CH).</td> |
| 675 |
<td><i>platform locale</i></td> |
| 676 |
</tr> |
| 677 |
</tbody> |
| 678 |
</table> |
| 679 |
|
| 680 |
<h3>Element <code>xml</code></h3> |
| 681 |
|
| 682 |
<p> |
| 683 |
Create a single-file report in XML format. |
| 684 |
</p> |
| 685 |
|
| 686 |
<table class="coverage"> |
| 687 |
<thead> |
| 688 |
<tr> |
| 689 |
<td>Attribute</td> |
| 690 |
<td>Description</td> |
| 691 |
<td>Default</td> |
| 692 |
</tr> |
| 693 |
</thead> |
| 694 |
<tbody> |
| 695 |
<tr> |
| 696 |
<td><code>destfile</code></td> |
| 697 |
<td>Location to write the report file to.</td> |
| 698 |
<td><i>none (required)</i></td> |
| 699 |
</tr> |
| 700 |
<tr> |
| 701 |
<td><code>encoding</code></td> |
| 702 |
<td>Encoding of the generated XML document.</td> |
| 703 |
<td><code>UTF-8</code></td> |
| 704 |
</tr> |
| 705 |
</tbody> |
| 706 |
</table> |
| 707 |
|
| 708 |
<h3>Element <code>csv</code></h3> |
| 709 |
|
| 710 |
<p> |
| 711 |
Create single-file report in CSV format. |
| 712 |
</p> |
| 713 |
|
| 714 |
<table class="coverage"> |
| 715 |
<thead> |
| 716 |
<tr> |
| 717 |
<td>Attribute</td> |
| 718 |
<td>Description</td> |
| 719 |
<td>Default</td> |
| 720 |
</tr> |
| 721 |
</thead> |
| 722 |
<tbody> |
| 723 |
<tr> |
| 724 |
<td><code>destfile</code></td> |
| 725 |
<td>Location to write the report file to.</td> |
| 726 |
<td><i>none (required)</i></td> |
| 727 |
</tr> |
| 728 |
<tr> |
| 729 |
<td><code>encoding</code></td> |
| 730 |
<td>Encoding of the generated CSV document.</td> |
| 731 |
<td><code>UTF-8</code></td> |
| 732 |
</tr> |
| 733 |
</tbody> |
| 734 |
</table> |
| 735 |
|
| 736 |
<h3>Element <code>check</code></h3> |
| 737 |
|
| 738 |
<p> |
| 739 |
This report type does not actually create a report. It checks coverage |
| 740 |
counters and reports violations of configured rules. Every rule is applied to |
| 741 |
elements of a given type (class, package, bundle, etc.) and has a list of |
| 742 |
limits which are checked for every element. The following example checks that |
| 743 |
for every package the line coverage is at least 80% and no class is missed: |
| 744 |
</p> |
| 745 |
|
| 746 |
<pre class="source lang-xml linenums"> |
| 747 |
<check> |
| 748 |
<rule element="PACKAGE"> |
| 749 |
<limit counter="LINE" value="COVEREDRATIO" minimum="80%"/> |
| 750 |
<limit counter="CLASS" value="MISSEDCOUNT" maximum="0"/> |
| 751 |
</rule> |
| 752 |
</check> |
| 753 |
</pre> |
| 754 |
|
| 755 |
<p> |
| 756 |
The <code>check</code> element has the following attributes: |
| 757 |
</p> |
| 758 |
|
| 759 |
<table class="coverage"> |
| 760 |
<thead> |
| 761 |
<tr> |
| 762 |
<td>Attribute</td> |
| 763 |
<td>Description</td> |
| 764 |
<td>Default</td> |
| 765 |
</tr> |
| 766 |
</thead> |
| 767 |
<tbody> |
| 768 |
<tr> |
| 769 |
<td><code>rules</code></td> |
| 770 |
<td>List of rules to check.</td> |
| 771 |
<td><i>none</i></td> |
| 772 |
</tr> |
| 773 |
<tr> |
| 774 |
<td><code>failonviolation</code></td> |
| 775 |
<td>Specifies whether build should fail in case of rule violations.</td> |
| 776 |
<td><code>true</code></td> |
| 777 |
</tr> |
| 778 |
<tr> |
| 779 |
<td><code>violationsproperty</code></td> |
| 780 |
<td>The name of an Ant property which is filled with the violation |
| 781 |
messages.</td> |
| 782 |
<td><i>none</i></td> |
| 783 |
</tr> |
| 784 |
</tbody> |
| 785 |
</table> |
| 786 |
|
| 787 |
<p> |
| 788 |
Within the <code>check</code> element any number of <code>rule</code> elements |
| 789 |
can be nested: |
| 790 |
</p> |
| 791 |
|
| 792 |
<table class="coverage"> |
| 793 |
<thead> |
| 794 |
<tr> |
| 795 |
<td>Attribute</td> |
| 796 |
<td>Description</td> |
| 797 |
<td>Default</td> |
| 798 |
</tr> |
| 799 |
</thead> |
| 800 |
<tbody> |
| 801 |
<tr> |
| 802 |
<td><code>element</code></td> |
| 803 |
<td>The elements this rule applies to. Possible values are |
| 804 |
<code>BUNDLE</code>, <code>PACKAGE</code>, <code>CLASS</code>, |
| 805 |
<code>SOURCEFILE</code> and <code>METHOD</code>.</td> |
| 806 |
<td><code>BUNDLE</code></td> |
| 807 |
</tr> |
| 808 |
<tr> |
| 809 |
<td><code>includes</code></td> |
| 810 |
<td>A list of element names that should be checked. The list entries are |
| 811 |
separated by a colon (:) and may use wildcard characters (* and ?).</td> |
| 812 |
<td><code>*</code></td> |
| 813 |
</tr> |
| 814 |
<tr> |
| 815 |
<td><code>excludes</code></td> |
| 816 |
<td>A list of element names that should not be checked. The list entries |
| 817 |
are separated by a colon (:) and may use wildcard characters (* and ?).</td> |
| 818 |
<td><i>empty (no excludes)</i></td> |
| 819 |
</tr> |
| 820 |
<tr> |
| 821 |
<td><code>limits</code></td> |
| 822 |
<td>List of limits to check.</td> |
| 823 |
<td><i>none</i></td> |
| 824 |
</tr> |
| 825 |
</tbody> |
| 826 |
</table> |
| 827 |
|
| 828 |
<p> |
| 829 |
Within the <code>rule</code> element any number of <code>limit</code> elements |
| 830 |
can be nested: |
| 831 |
</p> |
| 832 |
|
| 833 |
<table class="coverage"> |
| 834 |
<thead> |
| 835 |
<tr> |
| 836 |
<td>Attribute</td> |
| 837 |
<td>Description</td> |
| 838 |
<td>Default</td> |
| 839 |
</tr> |
| 840 |
</thead> |
| 841 |
<tbody> |
| 842 |
<tr> |
| 843 |
<td><code>counter</code></td> |
| 844 |
<td>The <a href="counters.html">counter</a> which should be checked. |
| 845 |
Possible options are <code>INSTRUCTION</code>, <code>LINE</code>, |
| 846 |
<code>BRANCH</code>, <code>COMPLEXITY</code>, <code>METHOD</code> and |
| 847 |
<code>CLASS</code>.</td> |
| 848 |
<td><code>INSTRUCTION</code></td> |
| 849 |
</tr> |
| 850 |
<tr> |
| 851 |
<td><code>value</code></td> |
| 852 |
<td>The counter value that should be checked. Possible options are |
| 853 |
<code>TOTALCOUNT</code>, <code>MISSEDCOUNT</code>, |
| 854 |
<code>COVEREDCOUNT</code>, <code>MISSEDRATIO</code> and |
| 855 |
<code>COVEREDRATIO</code>.</td> |
| 856 |
<td><code>COVEREDRATIO</code></td> |
| 857 |
</tr> |
| 858 |
<tr> |
| 859 |
<td><code>minimum</code></td> |
| 860 |
<td>Expected minimum value. If the minimum refers to a ratio it must be |
| 861 |
in the range from 0.0 to 1.0 where the number of decimal places will |
| 862 |
also determine the precision in error messages. A limit ratio may |
| 863 |
optionally be declared as a percentage where 0.80 and 80% represent |
| 864 |
the same value.</td> |
| 865 |
<td><i>none</i></td> |
| 866 |
</tr> |
| 867 |
<tr> |
| 868 |
<td><code>maximum</code></td> |
| 869 |
<td>Expected maximum value, see <code>minimum</code> for details.</td> |
| 870 |
<td><i>none</i></td> |
| 871 |
</tr> |
| 872 |
</tbody> |
| 873 |
</table> |
| 874 |
|
| 875 |
<h2><a name="instrument">Task <code>instrument</code></a></h2> |
| 876 |
|
| 877 |
<p class="hint"> |
| 878 |
<b>Warning:</b> The preferred way for code coverage analysis with JaCoCo is |
| 879 |
on-the-fly instrumentation. Offline instrumentation has several drawbacks and |
| 880 |
should only be used if a specific scenario explicitly requires this mode. |
| 881 |
Please consult <a href="offline.html">documentation</a> about offline |
| 882 |
instrumentation before using this mode. |
| 883 |
</p> |
| 884 |
|
| 885 |
<p> |
| 886 |
This task is used for <a href="offline.html">offline instrumentation</a> of |
| 887 |
class files. The task takes a set of files and writes instrumented |
| 888 |
versions to a specified location. The task takes any file type as input. Java |
| 889 |
class files are instrumented. Archives (jar, war, ear etc. or Pack200) are |
| 890 |
searched recursively for class files which then get instrumented. All other |
| 891 |
files are copied without modification. |
| 892 |
</p> |
| 893 |
|
| 894 |
<pre class="source lang-xml linenums"> |
| 895 |
<jacoco:instrument destdir="target/classes-instr"> |
| 896 |
<fileset dir="target/classes" includes="**/*.class"/> |
| 897 |
</jacoco:instrument> |
| 898 |
</pre> |
| 899 |
|
| 900 |
<p> |
| 901 |
The task definition can contain any number of resource collection types and |
| 902 |
has the following mandatory attribute: |
| 903 |
</p> |
| 904 |
|
| 905 |
<table class="coverage"> |
| 906 |
<thead> |
| 907 |
<tr> |
| 908 |
<td>Attribute</td> |
| 909 |
<td>Description</td> |
| 910 |
<td>Default</td> |
| 911 |
</tr> |
| 912 |
</thead> |
| 913 |
<tbody> |
| 914 |
<tr> |
| 915 |
<td><code>destdir</code></td> |
| 916 |
<td>Directory location to write the instrumented files to.</td> |
| 917 |
<td><i>none (required)</i></td> |
| 918 |
</tr> |
| 919 |
<tr> |
| 920 |
<td><code>removesignatures</code></td> |
| 921 |
<td>If set to <code>true</code> all signature related information is |
| 922 |
stripped from JARs. This is typically necessary as instrumentation |
| 923 |
breaks the signatures of the original class files.</td> |
| 924 |
<td><code>true</code></td> |
| 925 |
</tr> |
| 926 |
</tbody> |
| 927 |
</table> |
| 928 |
|
| 929 |
</div> |
| 930 |
<div class="footer"> |
| 931 |
<span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> |
| 932 |
<a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors |
| 933 |
</div> |
| 934 |
|
| 935 |
</body> |
| 936 |
</html> |