Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / b3395ca5397a0618dbc8533a37f052021bbe67d8 / . / org.jacoco.doc / docroot / doc / maven.html
blob: 8920cb5f02f89cf8be61cf67ff73063a0417cead [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
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]66 type by default a property with the following name is set:
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]67</p>
68
69<ul>
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]70 <li><code>tycho.testArgLine</code> for packaging type <code>maven-osgi-test-plugin</code> and</li>
71 <li><code>argLine</code> otherwise.</li>
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]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>
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]80 The goal has the following parameters which control the agent setup:
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]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>
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]93 <td><code>propertyName</code></td>
94 <td>Name of the project property to set.</td>
95 <td><code>tycho.testArgLine</code> for packaging type
96 <code>maven-osgi-test-plugin</code>, <code>argLine</code> otherwise</td>
97 </tr>
98 <tr>
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]99 <td><code>destfile</code></td>
100 <td>Path to the output file for execution data.</td>
101 <td><code>${project.build.directory}/jacoco.exec</code></td>
102 </tr>
103 <tr>
104 <td><code>append</code></td>
105 <td>If set to <code>true</code> and the execution data file already
106 exists, coverage data is appended to the existing file. If set to
107 <code>false</code>, an existing execution data file will be replaced.
108 </td>
109 <td><code>true</code></td>
110 </tr>
111 <tr>
112 <td><code>includes</code></td>
113 <td>A list of class names that should be included in execution analysis.
114 The list entries are separated by a colon (<code>:</code>) and
115 may use wildcard characters (<code>*</code> and <code>?</code>).
116 Except for performance optimization or technical corner cases this
117 option is normally not required.
118 </td>
119 <td><code>*</code> (all classes)</td>
120 </tr>
121 <tr>
122 <td><code>excludes</code></td>
123 <td>A list of class names that should be excluded from execution analysis.
124 The list entries are separated by a colon (<code>:</code>) and
125 may use wildcard characters (<code>*</code> and <code>?</code>).
126 Except for performance optimization or technical corner cases this
127 option is normally not required.
128 </td>
129 <td><i>empty</i> (no excluded classes)</td>
130 </tr>
131 <tr>
132 <td><code>exclclassloader</code></td>
133 <td>A list of class loader names, that should be excluded from execution
134 analysis. The list entries are separated by a colon
135 (<code>:</code>) and may use wildcard characters (<code>*</code> and
136 <code>?</code>). This option might be required in case of special
137 frameworks that conflict with JaCoCo code instrumentation, in
138 particular class loaders that do not have access to the Java runtime
139 classes.
140 </td>
141 <td><code>sun.reflect.DelegatingClassLoader</code></td>
142 </tr>
143 <tr>
144 <td><code>sessionid</code></td>
145 <td>A session identifier that is written with the execution data. Without
146 this parameter a random identifier is created by the agent.
147 </td>
148 <td><i>auto-generated</i></td>
149 </tr>
150 <tr>
151 <td><code>dumponexit</code></td>
152 <td>If set to <code>true</code> coverage data will be written on VM
153 shutdown.
154 </td>
155 <td><code>true</code></td>
156 </tr>
157 <tr>
158 <td><code>output</code></td>
159 <td>Output method to use for writing coverage data. Valid options are:
160 <ul>
161 <li><code>file</code>: At VM termination execution data is written to
Evgeny Mandrikov0d5cda12011-06-24 20:33:43 +0000[diff] [blame]162 the file specified in the <code>destfile</code> attribute.</li>
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]163 <li><code>tcpserver</code>: The agent listens for incoming connections
164 on the TCP port specified by the <code>address</code> and
165 <code>port</code> attribute. Execution data is written to this
166 TCP connection.</li>
167 <li><code>tcpclient</code>: At startup the agent connects to the TCP
168 port specified by the <code>address</code> and <code>port</code>
169 attribute. Execution data is written to this TCP connection.</li>
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]170 <li><code>mbean</code>: The agent registers an JMX MBean under the
171 name <code>org.jacoco:type=Runtime</code>.</li>
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]172 </ul>
173 </td>
174 <td><code>file</code></td>
175 </tr>
176 <tr>
177 <td><code>address</code></td>
178 <td>IP address or hostname to bind to when the output method is
179 <code>tcpserver</code> or connect to when the output method is
180 <code>tcpclient</code>. In <code>tcpserver</code> mode the value
181 "<code>*</code>" causes the agent to accept connections on any local
182 address.
183 </td>
184 <td><i>loopback interface</i></td>
185 </tr>
186 <tr>
187 <td><code>port</code></td>
188 <td>Port to bind to when the output method is <code>tcpserver</code> or
189 connect to when the output method is <code>tcpclient</code>. In
190 <code>tcpserver</code> mode the port must be available, which means
191 that if multiple JaCoCo agents should run on the same machine,
192 different ports have to be specified.
193 </td>
194 <td><code>6300</code></td>
195 </tr>
196 </tbody>
197</table>
198
199
200<h2><a name="report">Goal <code>report</code></a></h2>
201
202<p>
203 This goal creates a code coverage report for a single project in multiple
204 formats (HTML, XML, and CSV). It has the following parameters:
205</p>
206
207<table class="coverage">
208 <thead>
209 <tr>
210 <td>Parameter</td>
211 <td>Description</td>
212 <td>Default</td>
213 </tr>
214 </thead>
215 <tbody>
216 <tr>
217 <td><code>outputDirectory</code></td>
218 <td>Output directory for the reports.</td>
219 <td><code>${project.reporting.outputDirectory}/jacoco</code></td>
220 </tr>
221 <tr>
222 <td><code>outputEncoding</code></td>
223 <td>Encoding of the generated reports..</td>
Marc R. Hoffmannc0658682011-06-20 06:01:37 +0000[diff] [blame]224 <td><code>${project.reporting.outputEncoding}</code>, otherwise UTF-8</td>
Marc R. Hoffmann7981f7c2011-06-18 08:21:40 +0000[diff] [blame]225 </tr>
226 <tr>
227 <td><code>sourceEncoding</code></td>
228 <td>Character encoding of the source files.</td>
229 <td><code>${project.build.sourceEncoding}</code>, otherwise UTF-8</td>
230 </tr>
231 <tr>
232 <td><code>dataFile</code></td>
233 <td>File with execution data.</td>
234 <td><code>${project.build.directory}/jacoco.exec</code></td>
235 </tr>
236 </tbody>
237</table>
238
239</div>
240<div class="footer">
241 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
242 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
243</div>
244
245</body>
246</html>