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