| Marc R. Hoffmann | f7d1752 | 2009-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> >
|
| 13 | <a href="index.html" class="el_group">Documentation</a> >
|
| 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
|
| Marc R. Hoffmann | b8a7746 | 2009-08-21 14:53:50 +0000 | [diff] [blame] | 21 | and for creating coverage reports from the recorded data. The JaCoCo Ant tasks
|
| 22 | require
|
| 23 | </p>
|
| 24 |
|
| 25 | <ul>
|
| 26 | <li>Ant 1.7.0 or higher and</li>
|
| 27 | <li>Java 1.5 or higher (for both, the Ant runner and the test executor).</li>
|
| 28 | </ul>
|
| 29 |
|
| 30 |
|
| 31 | <p>All tasks are
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 32 | defined in <code>jacocoant.jar</code> and can be included in your Ant scripts
|
| 33 | with the usual <code>taskdef</code> declaration:
|
| 34 | </p>
|
| 35 |
|
| 36 | <pre class="source">
|
| 37 | <span class="nr"> 1</span><project name="Example" xmlns:jacoco="antlib:org.jacoco.ant">
|
| 38 | <span class="nr"> 2</span>
|
| 39 | <span class="nr"> 3</span> <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml">
|
| 40 | <span class="nr"> 4</span> <classpath>
|
| Marc R. Hoffmann | db93077 | 2009-08-20 17:17:37 +0000 | [diff] [blame] | 41 | <span class="nr"> 5</span> <pathelement location="<i>path_to_jacoco</i>/lib/jacocoant.jar"/>
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 42 | <span class="nr"> 6</span> </classpath>
|
| 43 | <span class="nr"> 7</span> </taskdef>
|
| 44 | <span class="nr"> 8</span>
|
| 45 | <span class="nr"> 9</span> ...
|
| 46 | <span class="nr"> 10</span>
|
| 47 | <span class="nr"> 11</span></project>
|
| 48 | </pre>
|
| 49 |
|
| 50 | <p>
|
| Marc R. Hoffmann | db3e7d0 | 2009-08-12 10:57:39 +0000 | [diff] [blame] | 51 | Alternatively you might also place the <code>jacocoant.jar</code> in your
|
| 52 | Ant <code><i>ANT_HOME</i>/lib</code> folder. If you use the name space URI
|
| 53 | <code>antlib:org.jacoco.ant</code> for JaCoCo tasks Ant will find them
|
| 54 | automatically without the <code>taskdef</code> declaration above.
|
| 55 | </p>
|
| 56 |
|
| 57 | <p>
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 58 | Declaring a XML namespace for JaCoCo tasks is optional but always recommended
|
| 59 | if you mix tasks from different libraries. All subsequent examples use the
|
| 60 | <code>jacoco</code> prefix declared above.
|
| 61 | </p>
|
| 62 |
|
| 63 |
|
| 64 | <h2>Task <code>coverage</code></h2>
|
| 65 |
|
| 66 | <p>
|
| 67 | The standard Ant tasks to launch Java programs are <code>java</code> and
|
| 68 | <code>junit</code>. To add code coverage recording to these tasks they can
|
| 69 | simply be wrapped with the <code>coverage</code> task as shown in the
|
| 70 | following examples:
|
| 71 | </p>
|
| 72 |
|
| 73 | <pre class="source">
|
| 74 | <span class="nr"> 1</span><jacoco:coverage>
|
| 75 | <span class="nr"> 2</span> <java classname="org.jacoco.examples.HelloJaCoCo" fork="true">
|
| 76 | <span class="nr"> 3</span> <classpath>
|
| 77 | <span class="nr"> 4</span> <pathelement location="./bin"/>
|
| 78 | <span class="nr"> 5</span> </classpath>
|
| 79 | <span class="nr"> 6</span> </java>
|
| 80 | <span class="nr"> 7</span></jacoco:coverage>
|
| 81 | <span class="nr"> 8</span>
|
| 82 | <span class="nr"> 9</span>
|
| 83 | <span class="nr"> 10</span><jacoco:coverage>
|
| 84 | <span class="nr"> 11</span> <junit fork="true" forkmode="once">
|
| 85 | <span class="nr"> 12</span> <test name="org.jacoco.examples.HelloJaCoCoTest"/>
|
| 86 | <span class="nr"> 13</span> <classpath>
|
| 87 | <span class="nr"> 14</span> <pathelement location="./bin"/>
|
| 88 | <span class="nr"> 15</span> </classpath>
|
| 89 | <span class="nr"> 16</span> </junit>
|
| 90 | <span class="nr"> 17</span></jacoco:coverage>
|
| 91 | </pre>
|
| 92 |
|
| 93 | <p>
|
| 94 | As a result coverage information is collected during execution and written
|
| 95 | to a file when the process terminates. Note the <code>fork</code> attribute in
|
| 96 | wrapped <code>java</code> task.
|
| 97 | </p>
|
| 98 |
|
| 99 | <p class="hint">
|
| 100 | The nested task always has to declare <code>fork="true"</code>, otherwise the
|
| 101 | <code>coverage</code> task can't record coverage information and will fail.
|
| 102 | In addition the <code>junit</code> task should declare
|
| 103 | <code>forkmode="once"</code> to avoid starting a new JVM for every single test
|
| 104 | case and decreasing execution performance dramatically (unless this is
|
| 105 | required by the nature of the test cases).
|
| 106 | </p>
|
| 107 |
|
| 108 | <p>
|
| 109 | The coverage task must wrap exactly one task. While it typically works without
|
| 110 | any configuration, the behavior can be adjusted with some optional attributes:
|
| 111 | </p>
|
| 112 |
|
| 113 | <table class="coverage">
|
| 114 | <thead>
|
| 115 | <tr>
|
| 116 | <td>Attribute</td>
|
| 117 | <td>Description</td>
|
| 118 | <td>Default</td>
|
| 119 | </tr>
|
| 120 | </thead>
|
| 121 | <tbody>
|
| 122 | <tr>
|
| 123 | <td><code>file</code></td>
|
| 124 | <td>Path to the output file for execution data.</td>
|
| 125 | <td><code>jacoco.exec</code></td>
|
| 126 | </tr>
|
| 127 | <tr>
|
| 128 | <td><code>merge</code></td>
|
| 129 | <td>If set to <code>true</code> and the execution data file already
|
| 130 | exists, coverage data is merged to the existing file. If set to
|
| 131 | <code>false</code>, an existing execution data file will be replaced.
|
| 132 | </td>
|
| 133 | <td><code>true</code></td>
|
| 134 | </tr>
|
| 135 | <tr>
|
| 136 | <td><code>exclclassloader</code></td>
|
| Marc R. Hoffmann | 2a6b5bf | 2009-08-11 12:54:36 +0000 | [diff] [blame] | 137 | <td>A list of class loader names, that should be excluded from execution
|
| 138 | analysis. The list entries are separated by a vertical bar
|
| 139 | (<code>|</code>) and may use wildcard characters (<code>*</code> and
|
| 140 | <code>?</code>). This option might be required in case of special
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 141 | frameworks that conflict with JaCoCo code instrumentation, e.g. class
|
| 142 | loaders that do not have access to the Java runtime classes.
|
| 143 | </td>
|
| 144 | <td><code>sun.reflect.DelegatingClassLoader</code></td>
|
| 145 | </tr>
|
| 146 | </tbody>
|
| 147 | </table>
|
| 148 |
|
| 149 |
|
| 150 | <h2>Task <code>agent</code></h2>
|
| 151 |
|
| Marc R. Hoffmann | d519add | 2009-08-11 11:09:29 +0000 | [diff] [blame] | 152 | <p>
|
| 153 | If the <code>coverage</code> task is not suitable for your launch target, you
|
| 154 | might alternatively use the <code>agent</code> task to create the Java agent
|
| 155 | parameter. The following example defines a Ant property with the name
|
| 156 | <code>agentvmparam</code> that can be directly used as Java VM parameter:
|
| 157 | </p>
|
| 158 |
|
| 159 | <pre class="source">
|
| 160 | <span class="nr"> 1</span><jacoco:agent property="agentvmparam"/>
|
| 161 | </pre>
|
| 162 |
|
| 163 | <p>
|
| 164 | This task has the same attributes as the <code>coverage</code> task plus an
|
| 165 | additional property to specify the target property name:
|
| 166 | </p>
|
| 167 |
|
| 168 | <table class="coverage">
|
| 169 | <thead>
|
| 170 | <tr>
|
| 171 | <td>Attribute</td>
|
| 172 | <td>Description</td>
|
| 173 | <td>Default</td>
|
| 174 | </tr>
|
| 175 | </thead>
|
| 176 | <tbody>
|
| 177 | <tr>
|
| 178 | <td><code>property</code></td>
|
| 179 | <td>Name of the Ant property to set.</td>
|
| 180 | <td><i>none (required)</i></td>
|
| 181 | </tr>
|
| Marc R. Hoffmann | 2bb6fca | 2009-08-13 14:04:21 +0000 | [diff] [blame] | 182 | <tr>
|
| 183 | <td colspan="3"><i>All attributes of the <code>coverage</code> task.</i></td>
|
| 184 | </tr>
|
| Marc R. Hoffmann | d519add | 2009-08-11 11:09:29 +0000 | [diff] [blame] | 185 | </tbody>
|
| 186 | </table>
|
| 187 |
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 188 | <h2>Task <code>report</code></h2>
|
| 189 |
|
| Marc R. Hoffmann | 2bb6fca | 2009-08-13 14:04:21 +0000 | [diff] [blame] | 190 | <p>
|
| 191 | Finally different reports can be created with the <code>report</code> task.
|
| 192 | A report task declaration consists of different sections, two specify the
|
| 193 | input data, additional ones specify the output formats:
|
| 194 | </p>
|
| 195 |
|
| 196 | <pre class="source">
|
| 197 | <span class="nr"> 1</span><jacoco:report>
|
| 198 | <span class="nr"> 2</span>
|
| 199 | <span class="nr"> 3</span> <executiondata>
|
| 200 | <span class="nr"> 4</span> <file file="jacoco.exec"/>
|
| 201 | <span class="nr"> 5</span> </executiondata>
|
| 202 | <span class="nr"> 6</span>
|
| 203 | <span class="nr"> 7</span> <structure name="Example Project">
|
| 204 | <span class="nr"> 8</span> <classfiles>
|
| 205 | <span class="nr"> 9</span> <fileset dir="bin"/>
|
| 206 | <span class="nr"> 10</span> </classfiles>
|
| 207 | <span class="nr"> 11</span> <sourcefiles encoding="UTF-8">
|
| 208 | <span class="nr"> 12</span> <fileset dir="src"/>
|
| 209 | <span class="nr"> 13</span> </sourcefiles>
|
| 210 | <span class="nr"> 14</span> </structure>
|
| 211 | <span class="nr"> 15</span>
|
| 212 | <span class="nr"> 16</span> <html destdir="report"/>
|
| 213 | <span class="nr"> 17</span>
|
| 214 | <span class="nr"> 18</span></jacoco:report>
|
| 215 | </pre>
|
| 216 |
|
| 217 | <p>
|
| 218 | As you can see from the example above the <code>report</code> task is based
|
| 219 | on several nested elements:
|
| 220 | </p>
|
| 221 |
|
| 222 | <h3>Element <code>executiondata</code></h3>
|
| 223 |
|
| 224 | <p>
|
| 225 | Within this element Ant resources and resource collections can be specified,
|
| 226 | that represent JaCoCo execution data files. If more than one execution data
|
| 227 | file is specified, execution data is combined. A particular piece of code is
|
| 228 | considered as executed, when it is marked as executed in any of the input
|
| 229 | files.
|
| 230 | </p>
|
| 231 |
|
| 232 | <h3>Element <code>structure</code></h3>
|
| 233 |
|
| 234 | <p>
|
| 235 | This element defines structure of the report. It might contain the following
|
| 236 | nested elements:
|
| 237 | </p>
|
| 238 |
|
| 239 | <ul>
|
| 240 | <li><code>classfiles</code>: Container element for Ant resources and resource
|
| 241 | collections that can specify Java class files, JAR files or directories
|
| 242 | containing class files.</li>
|
| 243 | <li><code>sourcefiles</code>: Optional container element for Ant resources and
|
| 244 | resource collections that specify corresponding source files. The element
|
| 245 | has an optional attribute <code>encoding</code> to specify the character
|
| 246 | encoding of the source files. If no encoding is given, the platform default
|
| 247 | is used. If source files are specified, some report formats include
|
| 248 | highlighted versions of the source code.</li>
|
| 249 | </ul>
|
| 250 |
|
| 251 | <p>
|
| 252 | The structure can be refined with a hierarchy of <code>group</code> elements.
|
| 253 | This way the coverage report can reflect different modules of an software
|
| 254 | project. For each group element the corresponding class and source files can
|
| 255 | be specified separately. For example the build script of JaCoCo itself
|
| 256 | contains the following declaration to separate the different bundles in the
|
| 257 | report (see the <a href="../coverage/index.html">resulting report</a>):
|
| 258 | </p>
|
| 259 |
|
| 260 | <pre class="source">
|
| 261 | <span class="nr"> 1</span><structure name="JaCoCo">
|
| 262 | <span class="nr"> 2</span> <group name="org.jacoco.core">
|
| 263 | <span class="nr"> 3</span> <classfiles>
|
| 264 | <span class="nr"> 4</span> <path refid="bundle-org.jacoco.core"/>
|
| 265 | <span class="nr"> 5</span> </classfiles>
|
| 266 | <span class="nr"> 6</span> <sourcefiles>
|
| 267 | <span class="nr"> 7</span> <fileset dir="${workspace.dir}/org.jacoco.core/src"/>
|
| 268 | <span class="nr"> 8</span> </sourcefiles>
|
| 269 | <span class="nr"> 9</span> </group>
|
| 270 | <span class="nr"> 10</span> <group name="org.jacoco.report">
|
| 271 | <span class="nr"> 11</span> <classfiles>
|
| 272 | <span class="nr"> 12</span> <path refid="bundle-org.jacoco.report"/>
|
| 273 | <span class="nr"> 13</span> </classfiles>
|
| 274 | <span class="nr"> 14</span> <sourcefiles>
|
| 275 | <span class="nr"> 15</span> <fileset dir="${workspace.dir}/org.jacoco.report/src"/>
|
| 276 | <span class="nr"> 16</span> </sourcefiles>
|
| 277 | <span class="nr"> 17</span> </group>
|
| 278 | <span class="nr"> 18</span>
|
| 279 | <span class="nr"> 19</span> ...
|
| 280 | <span class="nr"> 20</span>
|
| 281 | <span class="nr"> 21</span></structure>
|
| 282 | </pre>
|
| 283 |
|
| 284 | <h3>Element <code>html</code></h3>
|
| 285 |
|
| 286 | <p>
|
| 287 | Create a multi-page report in HTML format.
|
| 288 | </p>
|
| 289 |
|
| 290 | <table class="coverage">
|
| 291 | <thead>
|
| 292 | <tr>
|
| 293 | <td>Attribute</td>
|
| 294 | <td>Description</td>
|
| 295 | <td>Default</td>
|
| 296 | </tr>
|
| 297 | </thead>
|
| 298 | <tbody>
|
| 299 | <tr>
|
| 300 | <td><code>destdir</code></td>
|
| 301 | <td>Directory to create the report in.</td>
|
| 302 | <td><i>none (required)</i></td>
|
| 303 | </tr>
|
| 304 | </tbody>
|
| 305 | </table>
|
| 306 |
|
| 307 | <h3>Element <code>csv</code></h3>
|
| 308 |
|
| 309 | <p>
|
| 310 | Create a multi-page report in CSV format.
|
| 311 | </p>
|
| 312 |
|
| 313 | <table class="coverage">
|
| 314 | <thead>
|
| 315 | <tr>
|
| 316 | <td>Attribute</td>
|
| 317 | <td>Description</td>
|
| 318 | <td>Default</td>
|
| 319 | </tr>
|
| 320 | </thead>
|
| 321 | <tbody>
|
| 322 | <tr>
|
| 323 | <td><code>destdir</code></td>
|
| 324 | <td>Directory to create the report in.</td>
|
| 325 | <td><i>none (required)</i></td>
|
| 326 | </tr>
|
| 327 | </tbody>
|
| 328 | </table>
|
| 329 |
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 330 |
|
| 331 | <div class="footer">
|
| 332 | <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
|
| 333 | <a href="license.html">Copyright</a> © 2009 Mountainminds GmbH & Co. KG and Contributors
|
| 334 | </div>
|
| 335 |
|
| 336 | </body>
|
| 337 | </html> |