6
<h1><a name="jprobe">JProbe</a></h1>
9
<li>Stephane Bailliez (<a href="mailto:sbailliez@imediation.com">sbailliez@imediation.com</a>)</li>
13
<p>This task runs the tools from the JProbe suite.<br>
14
For more information, visit <a href="http://www.sitraka.com">http://www.sitraka.com</a>.
15
An evaluation version is available for download if you already don't own it.
18
<p>This task has been written using JProbe Suite Server Side 3.0.</p>
20
<p>It is highly recommended to read the JProbe documentation to understand
21
the values of the command line arguments described below. This
22
document is less complete than the manual, it only gives the basic information
23
and is not intended as a replacement to the manual.
28
<table border="0" cellspacing="0" cellpadding="3">
30
<td><a href="#jpcoverage">JPCoverage</a></td>
31
<td>Measure coverage of Java code.</td>
34
<td><a href="#jpcovmerge">JPCovMerge</a></td>
35
<td>Merge different snapshots into one.</td>
38
<td><a href="#jpcovreport">JPCovReport</a></td>
39
<td>Create a report from a snapshot</td>
46
<h2><a name="jpcoverage">JPCoverage</a></h2>
47
Perform code covering functions by comparing source code line execution to the program�s source code as a whole.
50
<table border="1" cellpadding="2" cellspacing="0">
52
<td width="12%" valign="top"><b>Attribute</b></td>
53
<td width="78%" valign="top"><b>Description</b></td>
54
<td width="10%" valign="top"><b>Required</b></td>
57
<td valign="top">home</td>
58
<td valign="top">The directory where is intalled JProbe.</td>
59
<td align="center" valign="top">Yes</td>
62
<td valign="top">vm</td>
64
Indicates which virtual machine to run.
65
Must be one of "jdk117", "jdk118" or "java2".If "java2" is specified, the user is
66
also required to specify a path via <tt>javahome</tt>, otherwise it will check if
67
the current executing VM is 1.2+ and use its java.home property to determine its
69
in the registry for the default 1.2.x (Java 2) VM.</td>
70
<td align="center" valign="top">No, default to embedded VM if 1.2+</td>
73
<td valign="top">javahome</td>
74
<td valign="top">For Java 2 only, specifies the path of the jdk1.2.x virtual
75
machine to be used. This is only valid when specifying the <tt>vm="java2"</tt>.</td>
76
<td align="center" valign="top">No, use only for java2</td>
79
<td valign="top">javaexe</td>
80
<td valign="top">Similar to <tt>javahome</tt>, except this is the path to
81
the java executable.</td>
82
<td align="center" valign="top">No, use only for java2</td>
86
<td valign="top">applet</td>
87
<td valign="top">Run an applet. The default is false, unless the file under
88
analysis ends with htm or html.</td>
89
<td align="center" valign="top">No, default is "false".</td>
92
<td valign="top">seedname</td>
93
<td valign="top">Seed name for the temporary snapshot files (files will be named
94
seed.jpc, seed1.jpc, seed2.jpc, ...)</td>
95
<td align="center" valign="top">No, default to "snapshot"</td>
99
<td valign="top">exitprompt</td>
100
<td valign="top">Toggles display of the console prompt: "Press Enter to close
101
this window." "always": Always displays the prompt. "never": Never displays the
102
prompt. "error": Only displays prompt after an error.</td>
103
<td align="center" valign="top">No, default is "never"</td>
107
<td valign="top">finalsnapshot</td>
108
<td valign="top">Type of snapshot to send at program termination. Must be one
109
of "none","coverage","all"</td>
110
<td align="center" valign="top">No, default to "coverage"</td>
113
<td valign="top">recordfromstart</td>
114
<td valign="top">Must be one of "coverage", "all", "none". If you want
115
Coverage to start analyzing as soon as the program begins to run, use "all".
116
If not, select "none".</td>
117
<td align="center" valign="top">No, default to "coverage"</td>
120
<td valign="top">warnlevel</td>
121
<td valign="top">Set warning level (0-3, where 0 is the least amount of warnings).</td>
122
<td align="center" valign="top">No, default to 0</td>
125
<td valign="top">snapshotdir</td>
126
<td valign="top">The path to the directory where snapshot files are stored.
127
Choose a directory that is reachable by both the remote and local computers,
128
and enter the same path on the command line and in the viewer.</td>
129
<td align="center" valign="top">No, default to current directory</td>
132
<td valign="top">workingdir</td>
133
<td valign="top">The physical path to the working directory for the VM.</td>
134
<td align="center" valign="top">No, default is current directory.</td>
137
<td valign="top">tracknatives</td>
138
<td valign="top">Test native methods. Note that testing native methods with
139
Java 2 disables the JIT</td>
140
<td align="center" valign="top">No, default to "false".</td>
143
<td valign="top">classname</td>
144
<td valign="top">the name of the class to analyze.</td>
145
<td align="center" valign="top">Yes</td>
149
<h3><a name="nested">Nested Elements</a></h3>
152
<p><code>jpcoverage</code> supports a nested <code><classpath></code>
153
element, that represents a <a href="index.html#path">PATH like
158
<p>Additional parameters may be passed to the VM via nested <code><jvmarg></code>
159
attributes, for example:</p>
163
<pre><jpcoverage home="c:\jprobe" classname="MyClass">
164
<jvmarg value="-classic"/>
165
<classpath path="."/>
169
would run the coverage on "MyClass" in classic mode VM.
171
<p><code><jvmarg></code> allows all attributes described in <a
172
href="index.html#arg">Command line arguments</a>.</p>
177
Parameters may be passed to the executed class via nested <tt><arg></tt>
178
attributes, as described in <a href="index.html#arg">Command line arguments</a>.
182
<p>Define a host and port to connect to if you want to do remote viewing.
184
<table border="1" cellpadding="2" cellspacing="0">
186
<td width="12%" valign="top"><b>Attribute</b></td>
187
<td width="78%" valign="top"><b>Description</b></td>
188
<td width="10%" valign="top"><b>Required</b></td>
191
<td valign="top">host</td>
192
<td valign="top">the host name/ip of the machine on which the Viewer is running</td>
193
<td align="center">No, default to localhost</td>
196
<td valign="top">port</td>
197
<td valign="top">The port number on which you will connect to the Viewer</td>
198
<td align="center">No, default to 4444</td>
206
<p>Defines class/method filters based on pattern matching.
207
The syntax is filters is similar to a <a href="index.html#fileset">fileset</a>.
210
<table border="1" cellpadding="2" cellspacing="0">
212
<td width="12%" valign="top"><b>Attribute</b></td>
213
<td width="78%" valign="top"><b>Description</b></td>
214
<td width="10%" valign="top"><b>Required</b></td>
217
<td valign="top">defaultexclude</td>
218
<td valign="top">As a default, the coverage exclude all classes and methods.
219
Default filters are equivalent to
222
<exclude class="*" method="*"/>
226
<td align="center">No, default to "true"</td>
230
As seen above, nested elements are <b><tt>include</tt></b> and <b><tt>exclude</tt></b>
231
with a <tt>name</tt> attribute.
234
<table border="1" cellpadding="2" cellspacing="0">
236
<td width="12%" valign="top"><b>Attribute</b></td>
237
<td width="78%" valign="top"><b>Description</b></td>
238
<td width="10%" valign="top"><b>Required</b></td>
241
<td valign="top">class</td>
242
<td valign="top">The class mask as a simple regular expression</td>
243
<td align="center">No, default to *</td>
246
<td valign="top">method</td>
247
<td valign="top">The method mask as a simple regular expression</td>
248
<td align="center">No, default to *</td>
253
<h3>Example of filters</h3>
256
<include class="com.mycompany.*" method="*"/>
257
<exclude class="com.mycompany.MyClass" method="test*"/>
258
</filters></pre>
261
reports the coverage on all packages, classes and methods from <tt>com.mycompany</tt>
262
except all methods starting by <tt>test</tt> on the class <tt>MyClass</tt>
263
in the package <tt>com.mycompany</tt>
267
<p>Define a number of events to use for interacting with the collection
268
of data performed during coverage. For example you may run a whole application
269
but only decide to collect data once it reaches a certain method and once it
270
exits another one.</p>
272
The only type of nested element is the <tt>method</tt> element (triggers are performed
273
on method) and it has the following attributes:
275
<table border="1" cellpadding="2" cellspacing="0">
277
<td width="12%" valign="top"><b>Attribute</b></td>
278
<td width="78%" valign="top"><b>Description</b></td>
279
<td width="10%" valign="top"><b>Required</b></td>
282
<td valign="top">name</td>
283
<td valign="top">The name of the method(s) as a regular expression. The name
284
is the fully qualified name on the form <tt>package.classname.method</tt></td>
285
<td align="center" valign="top">Yes</td>
288
<td valign="top">event</td>
289
<td valign="top">the event on the method that will trigger the action. Must be
290
"enter" or "exit".</td>
291
<td align="center" valign="top">Yes</td>
294
<td valign="top">action</td>
295
<td valign="top">the action to execute. Must be one of "clear",
296
"pause", "resume", "snapshot", "suspend",
297
or "exit". They respectively clear recording, pause recording,
298
resume recording, take a snapshot, suspend the recording and exit the program.
300
<td align="center" valign="top">Yes</td>
304
<h3>Example of triggers</h3>
306
<pre><triggers>
307
<method name="ClassName.*()" event="enter" action="snapshot"/>
308
<method name="ClassName.MethodName()" event="exit" action="exit"/>
313
<p>Will take a snapshot when it enters any method of the class <tt>ClassName</tt>
314
and will exit the program once it exits the method <tt>MethodName</tt> of the
318
<h2><a name="jpcovmerge">JPCovMerge</a></h2>
322
<p>Perform the merge of several snapshots into a single one.</p>
325
<table border="1" cellpadding="2" cellspacing="0">
327
<td width="12%" valign="top"><b>Attribute</b></td>
328
<td width="78%" valign="top"><b>Description</b></td>
329
<td width="10%" valign="top"><b>Required</b></td>
332
<td valign="top">home</td>
333
<td valign="top">The directory where is installed JProbe.</td>
334
<td align="center" valign="top">Yes</td>
337
<td valign="top">tofile</td>
338
<td valign="top">the output filename that will be the result
340
<td align="center" valign="top">Yes</td>
343
<td valign="top">verbose</td>
344
<td valign="top">Perform the merge in verbose mode giving
345
details about the snapshot processing.</td>
346
<td align="center" valign="top">No. Default to false</td>
351
<tt>jpcovmerge</tt> collects snapshots using the nested <a href="index.html#fileset"><code><FileSet></code></a>
355
<h3>Example of merge</h3>
357
<pre><jpcovreport home="c:\jprobe" tofile="merge.jpc" verbose="true">
358
<fileset dir="./snapshots">
359
<include name="snap*.jpc"/>
365
would run the merge in verbose mode on all snapshot files starting by <tt>snap</tt> in the
366
directory <tt>snapshots</tt>. The resulting file will be named <tt>merge.jpc</tt>.
375
<p>Generate a readable/printable report of a snapshot. Note that you will need <a href="http://jakarta.apache.org/oro/index.html">Jakarta
376
Oro</a> in Ant classpath, to run the <tt>reference</tt> feature.</p>
379
<table border="1" cellpadding="2" cellspacing="0">
381
<td width="12%" valign="top"><b>Attribute</b></td>
382
<td width="78%" valign="top"><b>Description</b></td>
383
<td width="10%" valign="top"><b>Required</b></td>
386
<td valign="top">home</td>
387
<td valign="top">The directory where is intalled JProbe.</td>
388
<td align="center" valign="top">Yes</td>
391
<td valign="top">format</td>
392
<td valign="top">The format of the generated report. Must be "xml", "html" or "text"</td>
393
<td align="center" valign="top">No, default to "html"</td>
396
<td valign="top">type</td>
397
<td valign="top">The type of report to be generated. Must be "executive",
398
"summary", "detailed" or "verydetailed"</td>
399
<td align="center" valign="top">No. Default to "detailed"</td>
402
<td valign="top">percent</td>
403
<td valign="top">A numeric value for the threshold for printing methods. Must
404
be between 0 and 100.</td>
405
<td align="center" valign="top">No, default to 100</td>
408
<td valign="top">snapshot</td>
409
<td valign="top">The name of the snapshot file that is the source to the report.</td>
410
<td align="center" valign="top">Yes</td>
413
<td valign="top">tofile</td>
414
<td valign="top">The name of the generated output file</td>
415
<td align="center" valign="top">Yes</td>
418
<td valign="top">includesource</td>
419
<td valign="top">Include text of the source code lines. Only applies to
420
format="xml" and type="verydetailed"</td>
421
<td align="center" valign="top">No. Defaults to "yes"</td>
428
Path to source files can be set via nested sourcepath elements that are <a href="index.html#path">PATH like structures</a>.
431
<h4>reference (only applies to format="xml")</h4>
433
<p>A reference is a set of classes whose coverage information will be checked
434
against. Since Coverage is only able to give you information about loaded
435
classes, it will only report classes that were at least used in some points in
437
therefore you will not be able to know what classes are not exercised at all
438
during your tests. The reference is an additional feature that will analyze the
439
bytecode of all classes in a given classpath that match some filters and modify
440
the XML report accordingly. In short, it will:
444
<li>remove the classes that do not exists in the reference classpath. (For
445
example you might have in your report some helper test classes that you do
446
not want to appear in the report, but are unable to filter without adding
447
hundred of filters for all your classes).</li>
448
<li>add classes that exists in the reference set and match the filters but are
450
<li>remove abstract methods that are incorrectly reported in JProbe 3.0
451
(should be fixed in a later SP)</li>
452
<li>remove classes/methods that do not match the filters.</li>
459
Path to the reference set of files can be set via nested classpath elements that are <a href="index.html#path">PATH like structures</a>.
465
<p>Nested elements are <b><tt>include</tt></b> and <b><tt>exclude</tt></b>
466
with a <tt>class </tt>and <tt>method </tt>attribute.
470
<table border="1" cellpadding="2" cellspacing="0">
472
<td width="12%" valign="top"><b>Attribute</b></td>
473
<td width="78%" valign="top"><b>Description</b></td>
474
<td width="10%" valign="top"><b>Required</b></td>
477
<td valign="top">class</td>
478
<td valign="top">The class mask as a simple regular expression</td>
479
<td align="center">No, default to *</td>
482
<td valign="top">method</td>
483
<td valign="top">The method mask as a simple regular expression</td>
484
<td align="center">No, default to *</td>
489
<h3>Example of report</h3>
491
<pre><jpcovreport home="c:\jprobe" snapshot="merge.jpc" format="xml" tofile="result.xml">
492
<sourcepath path="./src"/>
494
<classpath path="./bin/classes"/>
496
<include class="com.mycompany.*"/>
497
<exclude class="com.mycompany.MyClass" method="test*"/>
503
would generate the report of the file <tt>merge.jpc</tt> and write it to <tt>result.xml</tt>
504
using the source path <tt>src</tt>. As well, it will modify the result.xml by
505
analyzing all classes in the <tt>./bin/classes</tt> that are port of the package
506
<tt>com.mycompany</tt> except the method that start by <tt>test</tt> from the class <tt>MyClass</tt>.
509
<h3>Recommendation</h3>
511
<p>If you generate your main code and your testcases in a separate directory,
512
say bin/classes and test/classes. You should mostly end up with a reference such
515
<pre><reference>
516
<classpath path="./bin/classes"/>
517
</reference></pre>
519
<p>With such a reference, your XML report will be cleaned up against parasite
520
classes from your testcases (that as a common practice, generally match the
521
exact package structure of the class you exercise).</p>
522
<h3>HTML reports</h3>
523
<p>You will find in Ant etc directory a stylesheet called coverage-frames.xsl.
524
This file can be used to generate a framed report a la javadoc similar to the
525
one for JUnit. It needs either Xalan 1.2.2 or Xalan 2.x.</p>
526
<p>Xalan 1.2.2 (you must have xalan.jar and bsf.jar in your classpath)
528
<pre><style processor="xalan" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
529
style="${ant.home}/etc/coverage-frames.xsl">
530
<param name="output.dir" expression="'${basedir}/reports/html'"/>
532
<p>Xalan 2.x (note the parameter without single quote)</p>
533
<pre><style processor="trax" in="./reports/xml/results.xml" out="./reports/html/dummy.file"
534
style="${ant.home}/etc/coverage-frames.xsl">
535
<param name="output.dir" expression="${basedir}/reports/html"/>
added
removed
docs/manual/OptionalTasks/jpcoverage.html
