Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 16cb9197615c9aa310846c55bd1fc6d93cedd2eb / . / org.jacoco.doc / docroot / doc / ant.html
blob: 63311965d8261957a532ecbe12d547776310db84 [file] [log] [blame]
Marc R. Hoffmannf7d17522009-08-07 11:21:23 +0000[diff] [blame]1<?xml version="1.0" encoding="ISO-8859-1" ?>
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=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
7 <title>JaCoCo - Ant Tasks</title>
8</head>
9<body>
10
11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Ant Tasks</span>
15</div>
16
17<h1>Ant Tasks</h1>
18
19<p>
20 JaCoCo comes with Ant tasks to launch Java programs with execution recording
21 and for creating coverage reports from the recorded data. All tasks are
22 defined in <code>jacocoant.jar</code> and can be included in your Ant scripts
23 with the usual <code>taskdef</code> declaration:
24</p>
25
26<pre class="source">
27<span class="nr"> 1</span>&lt;project name="Example" xmlns:jacoco="antlib:org.jacoco.ant"&gt;
28<span class="nr"> 2</span>
29<span class="nr"> 3</span> &lt;taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml"&gt;
30<span class="nr"> 4</span> &lt;classpath&gt;
31<span class="nr"> 5</span> &lt;file file="<i>path_to_jacoco</i>/lib/jacocoant.jar"/&gt;
32<span class="nr"> 6</span> &lt;/classpath&gt;
33<span class="nr"> 7</span> &lt;/taskdef&gt;
34<span class="nr"> 8</span>
35<span class="nr"> 9</span> ...
36<span class="nr"> 10</span>
37<span class="nr"> 11</span>&lt;/project&gt;
38</pre>
39
40<p>
41 Declaring a XML namespace for JaCoCo tasks is optional but always recommended
42 if you mix tasks from different libraries. All subsequent examples use the
43 <code>jacoco</code> prefix declared above.
44</p>
45
46
47<h2>Task <code>coverage</code></h2>
48
49<p>
50 The standard Ant tasks to launch Java programs are <code>java</code> and
51 <code>junit</code>. To add code coverage recording to these tasks they can
52 simply be wrapped with the <code>coverage</code> task as shown in the
53 following examples:
54</p>
55
56<pre class="source">
57<span class="nr"> 1</span>&lt;jacoco:coverage>
58<span class="nr"> 2</span> &lt;java classname="org.jacoco.examples.HelloJaCoCo" fork="true"&gt;
59<span class="nr"> 3</span> &lt;classpath&gt;
60<span class="nr"> 4</span> &lt;pathelement location="./bin"/&gt;
61<span class="nr"> 5</span> &lt;/classpath&gt;
62<span class="nr"> 6</span> &lt;/java&gt;
63<span class="nr"> 7</span>&lt;/jacoco:coverage&gt;
64<span class="nr"> 8</span>
65<span class="nr"> 9</span>
66<span class="nr"> 10</span>&lt;jacoco:coverage>
67<span class="nr"> 11</span> &lt;junit fork="true" forkmode="once"&gt;
68<span class="nr"> 12</span> &lt;test name="org.jacoco.examples.HelloJaCoCoTest"/&gt;
69<span class="nr"> 13</span> &lt;classpath&gt;
70<span class="nr"> 14</span> &lt;pathelement location="./bin"/&gt;
71<span class="nr"> 15</span> &lt;/classpath&gt;
72<span class="nr"> 16</span> &lt;/junit&gt;
73<span class="nr"> 17</span>&lt;/jacoco:coverage>
74</pre>
75
76<p>
77 As a result coverage information is collected during execution and written
78 to a file when the process terminates. Note the <code>fork</code> attribute in
79 wrapped <code>java</code> task.
80</p>
81
82<p class="hint">
83 The nested task always has to declare <code>fork="true"</code>, otherwise the
84 <code>coverage</code> task can't record coverage information and will fail.
85 In addition the <code>junit</code> task should declare
86 <code>forkmode="once"</code> to avoid starting a new JVM for every single test
87 case and decreasing execution performance dramatically (unless this is
88 required by the nature of the test cases).
89</p>
90
91<p>
92 The coverage task must wrap exactly one task. While it typically works without
93 any configuration, the behavior can be adjusted with some optional attributes:
94</p>
95
96<table class="coverage">
97 <thead>
98 <tr>
99 <td>Attribute</td>
100 <td>Description</td>
101 <td>Default</td>
102 </tr>
103 </thead>
104 <tbody>
105 <tr>
106 <td><code>file</code></td>
107 <td>Path to the output file for execution data.</td>
108 <td><code>jacoco.exec</code></td>
109 </tr>
110 <tr>
111 <td><code>merge</code></td>
112 <td>If set to <code>true</code> and the execution data file already
113 exists, coverage data is merged to the existing file. If set to
114 <code>false</code>, an existing execution data file will be replaced.
115 </td>
116 <td><code>true</code></td>
117 </tr>
118 <tr>
119 <td><code>exclclassloader</code></td>
120 <td>A whitespace separated list of class loader names, that should be
121 excluded from execution analysis. The list entries may use wildcard
122 characters. This option might be required in case of special
123 frameworks that conflict with JaCoCo code instrumentation, e.g. class
124 loaders that do not have access to the Java runtime classes.
125 </td>
126 <td><code>sun.reflect.DelegatingClassLoader</code></td>
127 </tr>
128 </tbody>
129</table>
130
131
132<h2>Task <code>agent</code></h2>
133
134<h2>Task <code>report</code></h2>
135
136
137<div class="footer">
138 <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
139 <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
140</div>
141
142</body>
143</html>