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