Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 7981f7cc28f45446c57a1281cc9a85343641ecea / . / org.jacoco.doc / docroot / doc / maven.html
blob: d5eff26194b27a2d12a1ae8393726b2d2b782a87 [file] [log] [blame]
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +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 <link rel="stylesheet" href="../coverage/.resources/prettify.css" charset="ISO-8859-1" type="text/css" />
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 - Maven Plug-in</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">Maven Plug-in</span>
18</div>
19<div id="content">
20
21<h1>Maven Plug-in</h1>
22
23<p>
24 The JaCoCo <a href="http://maven.apache.org/">Maven</a> plug-in provides the
25 JaCoCo runtime <a href="#agent">agent</a> to your tests and allows basic
26 <a href="#report">report</a> creation.
27</p>
28
29<p class="hint">
30 If you want to have line number information included in the coverage reports
31 or you want source code highlighting the class files of the test target must
32 be compiled with debug information.
33</p>
34
35
36<h2>Prerequisites</h2>
37
38<p>
39 The JaCoCo Maven plug-in require
40</p>
41
42<ul>
43 <li>Maven 2.1.0 or higher and</li>
44 <li>Java 1.5 or higher (for both, the Maven runtime and the test executor).</li>
45</ul>
46
47<p>
48 The Maven plug-in can be included in your build with the following declaration:
49</p>
50
51<pre class="source lang-xml linenums">
52&lt;plugin&gt;
53 &lt;groupId&gt;org.jacoco&lt;/groupId&gt;
54 &lt;artifactId&gt;jacoco-maven-plugin&lt;/artifactId&gt;
55 &lt;version&gt;@qualified.bundle.version@&lt;/version&gt;
56&lt;/plugin&gt;
57</pre>
58
59
60<h2><a name="agent">Goal <code>prepare-agent</code></a></h2>
61
62<p>
63 This goal prepares a property pointing to the
64 <a href="agent.html">JaCoCo runtime agent</a> that can be passed as a VM
65 argument to the application under test. Depending on the project packaging
66 type a property with the following name is set:
67</p>
68
69<ul>
70 <li><code>tycho.testArgLine</code> for the <code>maven-osgi-test-plugin</code></li>
71 <li><code>argLine</code> for the <code>maven-surefire-plugin</code></li>
72</ul>
73
74<p>
75 Resulting coverage information is collected during execution and by default
76 written to a file when the process terminates.
77</p>
78
79<p>
80 The goal has the following parameters that will be passed to the agent:
81</p>
82
83<table class="coverage">
84 <thead>
85 <tr>
86 <td>Parameter</td>
87 <td>Description</td>
88 <td>Default</td>
89 </tr>
90 </thead>
91 <tbody>
92 <tr>
93 <td><code>destfile</code></td>
94 <td>Path to the output file for execution data.</td>
95 <td><code>${project.build.directory}/jacoco.exec</code></td>
96 </tr>
97 <tr>
98 <td><code>append</code></td>
99 <td>If set to <code>true</code> and the execution data file already
100 exists, coverage data is appended to the existing file. If set to
101 <code>false</code>, an existing execution data file will be replaced.
102 </td>
103 <td><code>true</code></td>
104 </tr>
105 <tr>
106 <td><code>includes</code></td>
107 <td>A list of class names that should be included in execution analysis.
108 The list entries are separated by a colon (<code>:</code>) and
109 may use wildcard characters (<code>*</code> and <code>?</code>).
110 Except for performance optimization or technical corner cases this
111 option is normally not required.
112 </td>
113 <td><code>*</code> (all classes)</td>
114 </tr>
115 <tr>
116 <td><code>excludes</code></td>
117 <td>A list of class names that should be excluded from execution analysis.
118 The list entries are separated by a colon (<code>:</code>) and
119 may use wildcard characters (<code>*</code> and <code>?</code>).
120 Except for performance optimization or technical corner cases this
121 option is normally not required.
122 </td>
123 <td><i>empty</i> (no excluded classes)</td>
124 </tr>
125 <tr>
126 <td><code>exclclassloader</code></td>
127 <td>A list of class loader names, that should be excluded from execution
128 analysis. The list entries are separated by a colon
129 (<code>:</code>) and may use wildcard characters (<code>*</code> and
130 <code>?</code>). This option might be required in case of special
131 frameworks that conflict with JaCoCo code instrumentation, in
132 particular class loaders that do not have access to the Java runtime
133 classes.
134 </td>
135 <td><code>sun.reflect.DelegatingClassLoader</code></td>
136 </tr>
137 <tr>
138 <td><code>sessionid</code></td>
139 <td>A session identifier that is written with the execution data. Without
140 this parameter a random identifier is created by the agent.
141 </td>
142 <td><i>auto-generated</i></td>
143 </tr>
144 <tr>
145 <td><code>dumponexit</code></td>
146 <td>If set to <code>true</code> coverage data will be written on VM
147 shutdown.
148 </td>
149 <td><code>true</code></td>
150 </tr>
151 <tr>
152 <td><code>output</code></td>
153 <td>Output method to use for writing coverage data. Valid options are:
154 <ul>
155 <li><code>file</code>: At VM termination execution data is written to
156 the file specified in the <code>tofile</code> attribute.</li>
157 <li><code>tcpserver</code>: The agent listens for incoming connections
158 on the TCP port specified by the <code>address</code> and
159 <code>port</code> attribute. Execution data is written to this
160 TCP connection.</li>
161 <li><code>tcpclient</code>: At startup the agent connects to the TCP
162 port specified by the <code>address</code> and <code>port</code>
163 attribute. Execution data is written to this TCP connection.</li>
164 </ul>
165 </td>
166 <td><code>file</code></td>
167 </tr>
168 <tr>
169 <td><code>address</code></td>
170 <td>IP address or hostname to bind to when the output method is
171 <code>tcpserver</code> or connect to when the output method is
172 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
173 "<code>*</code>" causes the agent to accept connections on any local
174 address.
175 </td>
176 <td><i>loopback interface</i></td>
177 </tr>
178 <tr>
179 <td><code>port</code></td>
180 <td>Port to bind to when the output method is <code>tcpserver</code> or
181 connect to when the output method is <code>tcpclient</code>. In
182 <code>tcpserver</code> mode the port must be available, which means
183 that if multiple JaCoCo agents should run on the same machine,
184 different ports have to be specified.
185 </td>
186 <td><code>6300</code></td>
187 </tr>
188 </tbody>
189</table>
190
191
192<h2><a name="report">Goal <code>report</code></a></h2>
193
194<p>
195 This goal creates a code coverage report for a single project in multiple
196 formats (HTML, XML, and CSV). It has the following parameters:
197</p>
198
199<table class="coverage">
200 <thead>
201 <tr>
202 <td>Parameter</td>
203 <td>Description</td>
204 <td>Default</td>
205 </tr>
206 </thead>
207 <tbody>
208 <tr>
209 <td><code>outputDirectory</code></td>
210 <td>Output directory for the reports.</td>
211 <td><code>${project.reporting.outputDirectory}/jacoco</code></td>
212 </tr>
213 <tr>
214 <td><code>outputEncoding</code></td>
215 <td>Encoding of the generated reports..</td>
216 <td><code>${project.reporting.outputEncoding}, otherwise UTF-8</td>
217 </tr>
218 <tr>
219 <td><code>sourceEncoding</code></td>
220 <td>Character encoding of the source files.</td>
221 <td><code>${project.build.sourceEncoding}</code>, otherwise UTF-8</td>
222 </tr>
223 <tr>
224 <td><code>dataFile</code></td>
225 <td>File with execution data.</td>
226 <td><code>${project.build.directory}/jacoco.exec</code></td>
227 </tr>
228 </tbody>
229</table>
230
231</div>
232<div class="footer">
233 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
234 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
235</div>
236
237</body>
238</html>