| 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>
|
| 31 | <span class="nr"> 5</span> <file file="<i>path_to_jacoco</i>/lib/jacocoant.jar"/>
|
| 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>
|
| 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><jacoco:coverage>
|
| 58 | <span class="nr"> 2</span> <java classname="org.jacoco.examples.HelloJaCoCo" fork="true">
|
| 59 | <span class="nr"> 3</span> <classpath>
|
| 60 | <span class="nr"> 4</span> <pathelement location="./bin"/>
|
| 61 | <span class="nr"> 5</span> </classpath>
|
| 62 | <span class="nr"> 6</span> </java>
|
| 63 | <span class="nr"> 7</span></jacoco:coverage>
|
| 64 | <span class="nr"> 8</span>
|
| 65 | <span class="nr"> 9</span>
|
| 66 | <span class="nr"> 10</span><jacoco:coverage>
|
| 67 | <span class="nr"> 11</span> <junit fork="true" forkmode="once">
|
| 68 | <span class="nr"> 12</span> <test name="org.jacoco.examples.HelloJaCoCoTest"/>
|
| 69 | <span class="nr"> 13</span> <classpath>
|
| 70 | <span class="nr"> 14</span> <pathelement location="./bin"/>
|
| 71 | <span class="nr"> 15</span> </classpath>
|
| 72 | <span class="nr"> 16</span> </junit>
|
| 73 | <span class="nr"> 17</span></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>
|
| Marc R. Hoffmann | 2a6b5bf | 2009-08-11 12:54:36 +0000 | [diff] [blame] | 120 | <td>A list of class loader names, that should be excluded from execution
|
| 121 | analysis. The list entries are separated by a vertical bar
|
| 122 | (<code>|</code>) and may use wildcard characters (<code>*</code> and
|
| 123 | <code>?</code>). This option might be required in case of special
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 124 | frameworks that conflict with JaCoCo code instrumentation, e.g. class
|
| 125 | loaders that do not have access to the Java runtime classes.
|
| 126 | </td>
|
| 127 | <td><code>sun.reflect.DelegatingClassLoader</code></td>
|
| 128 | </tr>
|
| 129 | </tbody>
|
| 130 | </table>
|
| 131 |
|
| 132 |
|
| 133 | <h2>Task <code>agent</code></h2>
|
| 134 |
|
| Marc R. Hoffmann | d519add | 2009-08-11 11:09:29 +0000 | [diff] [blame] | 135 | <p>
|
| 136 | If the <code>coverage</code> task is not suitable for your launch target, you
|
| 137 | might alternatively use the <code>agent</code> task to create the Java agent
|
| 138 | parameter. The following example defines a Ant property with the name
|
| 139 | <code>agentvmparam</code> that can be directly used as Java VM parameter:
|
| 140 | </p>
|
| 141 |
|
| 142 | <pre class="source">
|
| 143 | <span class="nr"> 1</span><jacoco:agent property="agentvmparam"/>
|
| 144 | </pre>
|
| 145 |
|
| 146 | <p>
|
| 147 | This task has the same attributes as the <code>coverage</code> task plus an
|
| 148 | additional property to specify the target property name:
|
| 149 | </p>
|
| 150 |
|
| 151 | <table class="coverage">
|
| 152 | <thead>
|
| 153 | <tr>
|
| 154 | <td>Attribute</td>
|
| 155 | <td>Description</td>
|
| 156 | <td>Default</td>
|
| 157 | </tr>
|
| 158 | </thead>
|
| 159 | <tbody>
|
| 160 | <tr>
|
| 161 | <td><code>property</code></td>
|
| 162 | <td>Name of the Ant property to set.</td>
|
| 163 | <td><i>none (required)</i></td>
|
| 164 | </tr>
|
| 165 | </tbody>
|
| 166 | </table>
|
| 167 |
|
| Marc R. Hoffmann | f7d1752 | 2009-08-07 11:21:23 +0000 | [diff] [blame] | 168 | <h2>Task <code>report</code></h2>
|
| 169 |
|
| 170 |
|
| 171 | <div class="footer">
|
| 172 | <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
|
| 173 | <a href="license.html">Copyright</a> © 2009 Mountainminds GmbH & Co. KG and Contributors
|
| 174 | </div>
|
| 175 |
|
| 176 | </body>
|
| 177 | </html> |