by
+This task runs the tools from the JProbe suite.
+For more information, visit http://www.sitraka.com.
+An evaluation version is available for download if you already don't own it.
+
This task has been written using JProbe Suite Server Side 3.0.
+ +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. +
+ +| JPCoverage | +Measure coverage of Java code. | +
| JPCovMerge | +Merge different snapshots into one. | +
| JPCovReport | +Create a report from a snapshot | +
| Attribute | +Description | +Required | +
| home | +The directory where is intalled JProbe. | +Yes | +
| vm | ++ 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 javahome, otherwise it will check if + the current executing VM is 1.2+ and use its java.home property to determine its + location. + in the registry for the default 1.2.x (Java 2) VM. | +No, default to embedded VM if 1.2+ | +
| javahome | +For Java 2 only, specifies the path of the jdk1.2.x virtual + machine to be used. This is only valid when specifying the vm="java2". | +No, use only for java2 | +
| javaexe | +Similar to javahome, except this is the path to + the java executable. | +No, use only for java2 | +
| applet | +Run an applet. The default is false, unless the file under + analysis ends with htm or html. | +No, default is "false". | +
| seedname | +Seed name for the temporary snapshot files (files will be named + seed.jpc, seed1.jpc, seed2.jpc, ...) | +No, default to "snapshot" | +
| exitprompt | +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. | +No, default is "never" | +
| finalsnapshot | +Type of snapshot to send at program termination. Must be one + of "none","coverage","all" | +No, default to "coverage" | +
| recordfromstart | +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". | +No, default to "coverage" | +
| warnlevel | +Set warning level (0-3, where 0 is the least amount of warnings). | +No, default to 0 | +
| snapshotdir | +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. | +No, default to current directory | +
| workingdir | +The physical path to the working directory for the VM. | +No, default is current directory. | +
| tracknatives | +Test native methods. Note that testing native methods with + Java 2 disables the JIT | +No, default to "false". | +
| classname | +the name of the class to analyze. | +Yes | +
jpcoverage supports a nested <classpath>
+element, that represents a PATH like
+structure.
Additional parameters may be passed to the VM via nested <jvmarg>
+attributes, for example:
++would run the coverage on "MyClass" in classic mode VM. + +<jpcoverage home="c:\jprobe" classname="MyClass"> + <jvmarg value="-classic"/> + <classpath path="."/> +</jpcoverage> ++
<jvmarg> allows all attributes described in Command line arguments.
+Parameters may be passed to the executed class via nested <arg> +attributes, as described in Command line arguments. +
+ +Define a host and port to connect to if you want to do remote viewing. +
+| Attribute | +Description | +Required | +
| host | +the host name/ip of the machine on which the Viewer is running | +No, default to localhost | +
| port | +The port number on which you will connect to the Viewer | +No, default to 4444 | +
Defines class/method filters based on pattern matching. +The syntax is filters is similar to a fileset. +
+ +| Attribute | +Description | +Required | +
| defaultexclude | +As a default, the coverage exclude all classes and methods.
+ Default filters are equivalent to
++ <filters> + <exclude class="*" method="*"/> + </filters> ++ |
+ No, default to "true" | +
+As seen above, nested elements are include and exclude +with a name attribute. +
+++ ++
++ +Attribute +Description +Required ++ +class +The class mask as a simple regular expression +No, default to * ++ +method +The method mask as a simple regular expression +No, default to * +
++ +reports the coverage on all packages, classes and methods from com.mycompany +except all methods starting by test on the class MyClass +in the package com.mycompany + +<filters> + <include class="com.mycompany.*" method="*"/> + <exclude class="com.mycompany.MyClass" method="test*"/> +</filters>+
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.
++The only type of nested element is the method element (triggers are performed +on method) and it has the following attributes: +
+| Attribute | +Description | +Required | +
| name | +The name of the method(s) as a regular expression. The name + is the fully qualified name on the form package.classname.method | +Yes | +
| event | +the event on the method that will trigger the action. Must be + "enter" or "exit". | +Yes | +
| action | +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. + | +Yes | +
++ +<triggers> + <method name="ClassName.*()" event="enter" action="snapshot"/> + <method name="ClassName.MethodName()" event="exit" action="exit"/> +</triggers> ++
Will take a snapshot when it enters any method of the class ClassName +and will exit the program once it exits the method MethodName of the +same class.
+ +Perform the merge of several snapshots into a single one.
+ +| Attribute | +Description | +Required | +
| home | +The directory where is installed JProbe. | +Yes | +
| tofile | +the output filename that will be the result + of the name. | +Yes | +
| verbose | +Perform the merge in verbose mode giving + details about the snapshot processing. | +No. Default to false | +
+jpcovmerge collects snapshots using the nested <FileSet>
+element.
+
++<jpcovreport home="c:\jprobe" tofile="merge.jpc" verbose="true"> + <fileset dir="./snapshots"> + <include name="snap*.jpc"/> + </fileset> +</jpcovreport> ++
+would run the merge in verbose mode on all snapshot files starting by snap in the +directory snapshots. The resulting file will be named merge.jpc. +
+ +Generate a readable/printable report of a snapshot. Note that you will need Jakarta +Oro in Ant classpath, to run the reference feature.
+ +| Attribute | +Description | +Required | +
| home | +The directory where is intalled JProbe. | +Yes | +
| format | +The format of the generated report. Must be "xml", "html" or "text" | +No, default to "html" | +
| type | +The type of report to be generated. Must be "executive", + "summary", "detailed" or "verydetailed" | +No. Default to "detailed" | +
| percent | +A numeric value for the threshold for printing methods. Must + be between 0 and 100. | +No, default to 100 | +
| snapshot | +The name of the snapshot file that is the source to the report. | +Yes | +
| tofile | +The name of the generated output file | +Yes | +
| includesource | +Include text of the source code lines. Only applies to + format="xml" and type="verydetailed" | +No. Defaults to "yes" | +
+Path to source files can be set via nested sourcepath elements that are PATH like structures. +
+ +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: +
+ +++classpath +
+ ++Path to the reference set of files can be set via nested classpath elements that are PATH like structures. +
+ +filters +
+ +Nested elements are include and exclude +with a class and method attribute. +
+
++ ++
++ +Attribute +Description +Required ++ +class +The class mask as a simple regular expression +No, default to * ++ +method +The method mask as a simple regular expression +No, default to * +
+<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> ++
+would generate the report of the file merge.jpc and write it to result.xml +using the source path src. As well, it will modify the result.xml by +analyzing all classes in the ./bin/classes that are port of the package +com.mycompany except the method that start by test from the class MyClass. +
+ +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:
+++<reference> + <classpath path="./bin/classes"/> +</reference>+
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).
+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.
+Xalan 1.2.2 (you must have xalan.jar and bsf.jar in your classpath) +
+<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>
+Xalan 2.x (note the parameter without single quote)
+<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>
+
+
+