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
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
|
<html>
<head>
<title>JProbe Tasks</title>
<link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
</head>
<body>
<h1><a name="jprobe">JProbe</a></h1>
<p>by</p>
<ul>
<li>Stephane Bailliez (<a href="mailto:sbailliez@imediation.com">sbailliez@imediation.com</a>)</li>
</ul>
<h2>Introduction</h2>
<p>This task runs the tools from the JProbe suite.<br>
For more information, visit <a href="http://www.sitraka.com">http://www.sitraka.com</a>.
An evaluation version is available for download if you already don't own it.
</p>
<p>This task has been written using JProbe Suite Server Side 3.0.</p>
<p>It is highly recommended to read the JProbe documentation to understand
the values of the command line arguments described below. This
document is less complete than the manual, it only gives the basic information
and is not intended as a replacement to the manual.
</p>
<h2>Tasks</h2>
<table border="0" cellspacing="0" cellpadding="3">
<tr>
<td><a href="#jpcoverage">JPCoverage</a></td>
<td>Measure coverage of Java code.</td>
</tr>
<tr>
<td><a href="#jpcovmerge">JPCovMerge</a></td>
<td>Merge different snapshots into one.</td>
</tr>
<tr>
<td><a href="#jpcovreport">JPCovReport</a></td>
<td>Create a report from a snapshot</td>
</tr>
</table>
<hr>
<h2><a name="jpcoverage">JPCoverage</a></h2>
Perform code covering functions by comparing source code line execution to the program’s source code as a whole.
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">home</td>
<td valign="top">The directory where JProbe is intalled.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">vm</td>
<td valign="top">
Indicates which virtual machine to run.
Must be one of "jdk117", "jdk118" or "java2".If "java2" is specified, the user is
also required to specify a path via <tt>javaexe</tt>, otherwise it will check if
the current executing VM is 1.2+ and use its java.home property to determine its
location.</td>
<td align="center" valign="top">No, default to embedded VM if 1.2+</td>
</tr>
<tr>
<td valign="top">javaexe</td>
<td valign="top">The path to the java executable.</td>
<td align="center" valign="top">No, use only for java2 vm.</td>
</tr>
<tr>
<td valign="top">applet</td>
<td valign="top">Run an applet. The default is false, unless the file under
analysis ends with htm or html.</td>
<td align="center" valign="top">No, default is "false".</td>
</tr>
<tr>
<td valign="top">seedname</td>
<td valign="top">Seed name for the temporary snapshot files (files will be named
seed.jpc, seed1.jpc, seed2.jpc, ...)</td>
<td align="center" valign="top">No, default to "snapshot"</td>
</tr>
<tr>
<td valign="top">exitprompt</td>
<td valign="top">Toggles display of the console prompt: "Press Enter to close
this window." "always": Always displays the prompt. "never": Never displays the
prompt. "error": Only displays prompt after an error.</td>
<td align="center" valign="top">No, default is "never"</td>
</tr>
<tr>
<td valign="top">finalsnapshot</td>
<td valign="top">Type of snapshot to send at program termination. Must be one
of "none","coverage","all"</td>
<td align="center" valign="top">No, default to "coverage"</td>
</tr>
<tr>
<td valign="top">recordfromstart</td>
<td valign="top">Must be one of "coverage", "all", "none". If you want
Coverage to start analyzing as soon as the program begins to run, use "all".
If not, select "none".</td>
<td align="center" valign="top">No, default to "coverage"</td>
</tr>
<tr>
<td valign="top">warnlevel</td>
<td valign="top">Set warning level (0-3, where 0 is the least amount of warnings).</td>
<td align="center" valign="top">No, default to 0</td>
</tr>
<tr>
<td valign="top">snapshotdir</td>
<td valign="top">The path to the directory where snapshot files are stored.
Choose a directory that is reachable by both the remote and local computers,
and enter the same path on the command line and in the viewer.</td>
<td align="center" valign="top">No, default to current directory</td>
</tr>
<tr>
<td valign="top">workingdir</td>
<td valign="top">The physical path to the working directory for the VM.</td>
<td align="center" valign="top">No, default is current directory.</td>
</tr>
<tr>
<td valign="top">tracknatives</td>
<td valign="top">Test native methods. Note that testing native methods with
Java 2 disables the JIT</td>
<td align="center" valign="top">No, default to "false".</td>
</tr>
<tr>
<td valign="top">classname</td>
<td valign="top">the name of the class to analyze.</td>
<td align="center" valign="top">Yes</td>
</tr>
</table>
<h3><a name="nested">Nested Elements</a></h3>
<h4>classpath</h4>
<p><code>jpcoverage</code> supports a nested <code><classpath></code>
element, that represents a <a href="../using.html#path">PATH like
structure</a>.</p>
<h4>jvmarg</h4>
<p>Additional parameters may be passed to the VM via nested <code><jvmarg></code>
attributes, for example:</p>
<pre></pre>
<blockquote>
<pre><jpcoverage home="c:\jprobe" classname="MyClass">
<jvmarg value="-classic"/>
<classpath path="."/>
</jpcoverage>
</pre>
</blockquote>
would run the coverage on "MyClass" in classic mode VM.
<p><code><jvmarg></code> allows all attributes described in <a
href="../using.html#arg">Command line arguments</a>.</p>
<h4>arg</h4>
<p>
Parameters may be passed to the executed class via nested <tt><arg></tt>
attributes, as described in <a href="../using.html#arg">Command line arguments</a>.
</p>
<h4>socket</h4>
<p>Define a host and port to connect to if you want to do remote viewing.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">host</td>
<td valign="top">the host name/ip of the machine on which the Viewer is running</td>
<td align="center">No, default to localhost</td>
</tr>
<tr>
<td valign="top">port</td>
<td valign="top">The port number on which you will connect to the Viewer</td>
<td align="center">No, default to 4444</td>
</tr>
</table>
<h4>filters</h4>
<p>Defines class/method filters based on pattern matching.
The syntax is filters is similar to a <a href="../CoreTypes/fileset.html">fileset</a>.
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">defaultexclude</td>
<td valign="top">As a default, the coverage excludes all classes and methods.
Default filters are equivalent to
<pre>
<filters>
<exclude class="*" method="*"/>
</filters>
</pre>
</td>
<td align="center">No, default to "true"</td>
</tr>
</table>
<p>
As seen above, nested elements are <b><tt>include</tt></b> and <b><tt>exclude</tt></b>
with a <tt>name</tt> attribute.
</p>
<blockquote>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">class</td>
<td valign="top">The class mask as a simple regular expression</td>
<td align="center">No, defaults to "*"</td>
</tr>
<tr>
<td valign="top">method</td>
<td valign="top">The method mask as a simple regular expression</td>
<td align="center">No, defaults to "*"</td>
</tr>
<tr>
<td valign="top">enabled</td>
<td valign="top">is the filter enabled?</td>
<td align="center">No, defaults to true</td>
</tr>
</table>
</blockquote>
<h3>Example of filters</h3>
<blockquote>
<pre><filters>
<include class="com.mycompany.*" method="*"/>
<exclude class="com.mycompany.MyClass" method="test*"/>
</filters></pre>
</blockquote>
reports the coverage on all packages, classes and methods from <tt>com.mycompany</tt>
except all methods starting by <tt>test</tt> on the class <tt>MyClass</tt>
in the package <tt>com.mycompany</tt>
<h4>triggers</h4>
<p>Define a number of events to use for interacting with the collection
of data performed during coverage. For example you may run a whole application
but only decide to collect data once it reaches a certain method and once it
exits another one.</p>
<p>
The only type of nested element is the <tt>method</tt> element (triggers are performed
on method) and it has the following attributes:
</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">name</td>
<td valign="top">The name of the method(s) as a regular expression. The name
is the fully qualified name on the form <tt>package.classname.method</tt></td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">event</td>
<td valign="top">the event on the method that will trigger the action. Must be
"enter" or "exit".</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">action</td>
<td valign="top">the action to execute. Must be one of "clear",
"pause", "resume", "snapshot", "suspend",
or "exit". They respectively clear recording, pause recording,
resume recording, take a snapshot, suspend the recording and exit the program.
</td>
<td align="center" valign="top">Yes</td>
</tr>
</table>
<h3>Example of triggers</h3>
<blockquote>
<pre><triggers>
<method name="ClassName.*()" event="enter" action="snapshot"/>
<method name="ClassName.MethodName()" event="exit" action="exit"/>
</triggers>
</pre>
</blockquote>
<p>Will take a snapshot when it enters any method of the class <tt>ClassName</tt>
and will exit the program once it exits the method <tt>MethodName</tt> of the
same class.</p>
<hr>
<h2><a name="jpcovmerge">JPCovMerge</a></h2>
<h3>Description</h3>
<p>Perform the merge of several snapshots into a single one.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">home</td>
<td valign="top">The directory where JProbe is installed.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">tofile</td>
<td valign="top">the output filename that will be the result
of the name.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">verbose</td>
<td valign="top">Perform the merge in verbose mode giving
details about the snapshot processing.</td>
<td align="center" valign="top">No. Default to false</td>
</tr>
</table>
<p>
<tt>jpcovmerge</tt> collects snapshots using the nested <a href="../CoreTypes/fileset.html"><code><FileSet></code></a>
element.
</p>
<h3>Example of merge</h3>
<blockquote>
<pre><jpcovmerge home="c:\jprobe" tofile="merge.jpc" verbose="true">
<fileset dir="./snapshots">
<include name="snap*.jpc"/>
</fileset>
</jpcovmerge>
</pre>
</blockquote>
<p>
would run the merge in verbose mode on all snapshot files starting by <tt>snap</tt> in the
directory <tt>snapshots</tt>. The resulting file will be named <tt>merge.jpc</tt>.
</p>
<hr>
<h2><a name="jpcovreport">JPCovReport</a></h2>
<h3>Description</h3>
<p>Generate a readable/printable report of a snapshot. Note that you will need <a href="http://jakarta.apache.org/oro/index.html">Jakarta
Oro</a> in Ant classpath, to run the <tt>reference</tt> feature.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">home</td>
<td valign="top">The directory where JProbe is intalled.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">format</td>
<td valign="top">The format of the generated report. Must be "xml", "html" or "text"</td>
<td align="center" valign="top">No, default to "html"</td>
</tr>
<tr>
<td valign="top">type</td>
<td valign="top">The type of report to be generated. Must be "executive",
"summary", "detailed" or "verydetailed"</td>
<td align="center" valign="top">No. Default to "detailed"</td>
</tr>
<tr>
<td valign="top">percent</td>
<td valign="top">A numeric value for the threshold for printing methods. Must
be between 0 and 100.</td>
<td align="center" valign="top">No, default to 100</td>
</tr>
<tr>
<td valign="top">snapshot</td>
<td valign="top">The name of the snapshot file that is the source to the report.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">tofile</td>
<td valign="top">The name of the generated output file</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">includesource</td>
<td valign="top">Include text of the source code lines. Only applies to
format="xml" and type="verydetailed"</td>
<td align="center" valign="top">No. Defaults to "yes"</td>
</tr>
</table>
<h4>sourcepath</h4>
<p>
Path to source files can be set via nested sourcepath elements that are <a href="../using.html#path">PATH like structures</a>.
</p>
<h4>reference (only applies to format="xml")</h4>
<p>A reference is a set of classes whose coverage information will be checked
against. Since Coverage is only able to give you information about loaded
classes, it will only report classes that were at least used in some points in
your tests,
therefore you will not be able to know what classes are not exercised at all
during your tests. The reference is an additional feature that will analyze the
bytecode of all classes in a given classpath that match some filters and modify
the XML report accordingly. In short, it will:
</p>
<ul>
<li>remove the classes that do not exists in the reference classpath. (For
example you might have in your report some helper test classes that you do
not want to appear in the report, but are unable to filter without adding
hundred of filters for all your classes).</li>
<li>add classes that exists in the reference set and match the filters but are
not reported.</li>
<li>remove abstract methods that are incorrectly reported in JProbe 3.0
(should be fixed in a later SP)</li>
<li>remove classes/methods that do not match the filters.</li>
</ul>
<blockquote>
<h4>classpath
</h4>
<p>
Path to the reference set of files can be set via nested classpath elements that are <a href="../using.html#path">PATH like structures</a>.
</p>
<h4>filters
</h4>
<p>Nested elements are <b><tt>include</tt></b> and <b><tt>exclude</tt></b>
with a <tt>class </tt>and <tt>method </tt>attribute.
</p>
</blockquote>
<blockquote>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">class</td>
<td valign="top">The class mask as a simple regular expression</td>
<td align="center">No, default to *</td>
</tr>
<tr>
<td valign="top">method</td>
<td valign="top">The method mask as a simple regular expression</td>
<td align="center">No, default to *</td>
</tr>
</table>
</blockquote>
<h3>Example of report</h3>
<blockquote>
<pre><jpcovreport home="c:\jprobe" snapshot="merge.jpc" format="xml" tofile="result.xml">
<sourcepath path="./src"/>
<reference>
<classpath path="./bin/classes"/>
<filters>
<include class="com.mycompany.*"/>
<exclude class="com.mycompany.MyClass" method="test*"/>
</filters>
</reference>
</jpcovreport>
</pre>
</blockquote><p>
would generate the report of the file <tt>merge.jpc</tt> and write it to <tt>result.xml</tt>
using the source path <tt>src</tt>. As well, it will modify the result.xml by
analyzing all classes in the <tt>./bin/classes</tt> that are port of the package
<tt>com.mycompany</tt> except the method that start by <tt>test</tt> from the class <tt>MyClass</tt>.
</p>
<h3>Recommendation</h3>
<p>If you generate your main code and your testcases in a separate directory,
say bin/classes and test/classes. You should mostly end up with a reference such
as:</p>
<blockquote>
<pre><reference>
<classpath path="./bin/classes"/>
</reference></pre>
</blockquote>
<p>With such a reference, your XML report will be cleaned up against parasite
classes from your testcases (that as a common practice, generally match the
exact package structure of the class you exercise).</p>
<h3>HTML reports</h3>
<p>You will find in Ant etc directory a stylesheet called coverage-frames.xsl.
This file can be used to generate a framed report a la javadoc similar to the
one for JUnit. It needs either Xalan 1.2.2 or Xalan 2.x.</p>
<p>Xalan 1.2.2 (you must have xalan.jar and bsf.jar in your classpath)
</p>
<pre><style processor="xalan" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
style="${ant.home}/etc/coverage-frames.xsl">
<param name="output.dir" expression="'${basedir}/reports/html'"/>
</style></pre>
<p>Xalan 2.x (note the parameter without single quote)</p>
<pre><style processor="trax" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
style="${ant.home}/etc/coverage-frames.xsl">
<param name="output.dir" expression="${basedir}/reports/html"/>
</style></pre>
<hr>
<p align="center">Copyright © 2001-2002,2004 The Apache Software Foundation. All rights
Reserved.</p>
</body>
</html>
|
