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. -
- -| Task | -Description | -
| 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 JProbe is installed. | -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 javaexe, otherwise it will check if - the current executing VM is 1.2+ and use its java.home property to determine its - location. | -No, default to embedded VM if 1.2+ | -
| javaexe | -The path to the java executable. | -No, use only for java2 vm. | -
| 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 for filters is similar to a fileset. -
- -| Attribute | -Description | -Required | -
| defaultexclude | -As a default, the coverage excludes 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, defaults to "*" -- -method -The method mask as a simple regular expression -No, defaults to "*" -- -enabled -is the filter enabled? -No, defaults to true -
-- -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 JProbe is installed. | -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.
-
--<jpcovmerge home="c:\jprobe" tofile="merge.jpc" verbose="true"> - <fileset dir="./snapshots"> - <include name="snap*.jpc"/> - </fileset> -</jpcovmerge> --
-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 JProbe is installed. | -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>
-
-Copyright © 2001-2002,2004-2005 The Apache Software Foundation. All rights -Reserved.
- -