1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
<name>Using GroboCoverage With Ant</name>
<doc-version>$Date: 2004/04/18 20:11:05 $</doc-version>
<author>Matt Albrecht</author>
</head>
<body>
<section>Getting Started</section>
<p>
This document describes how to get up and running with
simple build files. The <link name="v2_antdoc">ant task guide</link> describes
each Ant task in detail. If your build environment is "complex",
then <link name="complex_setup">this document</link> should help your more
basic questions. If you need more detailed information regarding the
operation of GroboCoverage, <link name="advanced_users">try this
document</link>.
</p>
<h3>Downloading the GroboCoverage Files</h3>
<p>
Before you get started, download the latest GroboCoverage zip file
(you can find it <a
href="https://sourceforge.net/project/showfiles.php?group_id=22594">
here</a>), which, at the time of this document, is called
<code>GroboUtils-5-codecoverage.zip</code>.
</p>
<p>
Inside are two JAR files, the "ant" and "runtime" code-coverage files.
The "ant" file contains the code-coverage files required for compiling
the coverage probes into your class files and all the dependent libraries,
while the "runtime" jar only contains those class files necessary to
run the recompiled class files.
</p>
<h2>Changing Your Ant Build File</h2>
<P>
To test with the coverage-enabled class files, you'll need to change your
build files.
</P>
<h3><a name="referenceNewTasks">Referencing the New Tasks</a></h3>
<p>
First off, before using any of the provided Ant tasks, you'll need to
tell Ant about them. You have two options:
<ol>
<li>
Copy <code><project />-<version />-ant.jar</code> to the
<code>lib</code> directory of your Ant installation. Then add
the next lines to your build file before you reference the tasks:
<pre>
<taskdef resource="ant-grobocoverage.properties"/>
</pre>
</li>
<li>
Keep <code><project />-<version />-ant.jar</code> in a separate
location. You now have to tell Ant explicitly where to find it
(say in <code>/usr/share/java/lib</code>):
<pre>
<taskdef resource="ant-grobocoverage.properties">
<classpath>
<pathelement location="/usr/share/java/lib/<project />-<version />-ant.jar"/>
</classpath>
</taskdef>
</pre>
</li>
</ol>
</p>
<p>
In order to use the <code><grobo-report></code> task, you need to
have a Xalan-2 compatible XSL processor in the classpath. If one is not in
your Ant classpath, then it needs to be referenced in the
<code><taskdef></code> classpath. Ant versions 1.5 and above come with
one by default.
</p>
<h3>Post-Compile Your Classes</h3>
<p>
Next, you'll need to "post-compile" your classes, after they've been
compiled. This "post-compilation" stage inserts probes into your
class files to tell when lines of code have been encountered.
</p>
<p>
Since post-compilation makes different class files that will most probably
be slower than the original, the author recommends putting these into
a different directory, separate from the original class files.
</p>
<p>
So, let's say you have a compilation step that looks like this:
<pre>
<javac srcdir="${src.dir}" destdir="${classes.dir}" debug="on">
<classpath>
<path refid="classpath.base" />
</classpath>
</javac>
</pre>
You would then add after it the <code><grobo-instrument></code>
task:
<pre>
<grobo-instrument logdir="coverage/logs" logger="fast"
destdir="coverage/classes">
<fileset dir="${classes.dir}">
<exclude name="dont/check/coverage/*.class" />
</fileset>
<measure type="linecount" />
<measure type="function" />
</grobo-instrument>
</pre>
which would put all the coverage-enabled class files into the
<code>coverage/classes</code> directory. It will insert probes into the
classes to check for Java code-lines executed, and which Java functions
were called, but only for the classes that were post-compiled. In this
case, none of the classes in the package "dont.check.coverage" were
post-compiled. Also, this task puts all the data discovered for the
compilation into the <code>coverage/data</code> directory. It also
sets up the logging properties in the output classes directory, describing
the directory to put the log files in, and to use the "fast" logger.
</p>
<p>
This task is described in <link name="v2_antdoc_grobo-instrument">the Ant task
documentation</link>.
</p>
<p>
Note: if you want the coverage report to include line numbers (showing a
trace back to the original Java source files), then you <i>must</i> enable
debugging during the <code><javac></code> task. See the
<ant-link href="CoreTasks/javac.html">Ant task reference</ant-link> for
details.
</p>
<h3>Running Your Tests With the Post-Compiled Classes</h3>
<p>
If you want to run your tests with code coverage enabled, and you're using
<a href="http://junit.org">JUnit</a>, here's an easy method.
</p>
<p>
Let's say you run your tests with JUnit using the optional Ant
<ant-link href="OptionalTasks/junit.html">junit</ant-link> task
like this:
<pre>
<junit printsummary="yes" fork="yes" dir="${test-output.dir}">
<classpath>
<pathelement location="${classes.dir}" />
<pathelement location="${test-classes.dir}" />
<path refid="classpath.base" />
</classpath>
<formatter type="xml" usefile="yes" />
<batchtest todir="${test-output.dir}">
<fileset dir="${test-classes.dir}">
<include name="*Test.class" />
</fileset>
</batchtest>
</junit>
</pre>
Since the post-compilation step above only puts coverage-enabled
versions of the specified classes into the directory
<code>coverage/classes</code>, this class directory, then, doesn't contain
any special files or classes excluded from coverage. So, we need to
tell the JUnit task to reference these covered classes, but also to
include the other files. We do this by replacing the JUnit task's
classpath with this:
<pre>
<classpath>
<pathelement location="coverage/classes" />
<pathelement location="${classes.dir}" />
<pathelement location="${test-classes.dir}" />
<path refid="classpath.base" />
<pathelement location="<project />-<version />-runtime.jar" />
</classpath>
</pre>
We added the coverage-enabled classes before everything else (so they have
priority in the class loader), and we also added the runtime jar, as the
coverage-enabled classes require these to run.
</p>
<p>
The <code><grobo-instrument></code> task told the logger running these
tests will put all the coverage log information into the
<code>coverage/logs</code> directory, and to use the "fast" logger.
</p>
<h3>Generating a Report</h3>
<p>
Now that coverage numbers are being generated, we need to add in additional
Ant script to generate a coverage-number report.
</p>
<p>
If you're using the <code><junit></code> task, then you're probably
also using the <code><junitreport></code> task. If not, check it out.
The ant documentation for it can be found
<ant-link href="OptionalTasks/junitreport.html">here</ant-link>
</p>
<p>
Whether you use the <code><junitreport></code> task or not,
we can add in the coverage report task after the <code><junit></code>
task, when the reports should be generated:
<pre>
<grobo-report logdir="coverage/logs">
<simple destdir="coverage" removeempty="true" />
<source destdir="coverage/source-report" removeempty="true"
srcdir="src" title="Summary Coverage Report of My Code" />
</grobo-report>
</pre>
The <code><grobo-report></code> task takes all the different
generated data from the data and log directories (as specified in the
<code><grobo-instrument></code> task above) and generates reports.
</p>
<p>
The embedded style tags define what kind of reports to generate. The
"simple" tag generates one HTML file for each measure, and
the "source" tag generates a JavaDoc-style collection of web pages
that link the Java souce code to the coverage reports.
</p>
<p>
On large class-file systems, this report generator may consume large
amounts of memory. If you see Ant generate an OutOfMemoryError, then
you can increase the amount of memory that the JVM uses with the
environment variable <code>ANT_OPTS</code>. For instance, to increase
the memory usage to 128 MB, on a 1.4 JVM, you would use:
<pre>
> set ANT_OPTS=-Xmx128M
</pre>
on Windows, and
<pre>
$ ANT_OPTS=-Xmx128M
$ export ANT_OPTS
</pre>
on the Bourne shell.
</p>
</body>
</document>
|
