From d5a2eaa26653c5c5a67c671debd8c68ddfc03ba3 Mon Sep 17 00:00:00 2001 From: Stephane Bailliez Date: Tue, 31 Jul 2001 08:41:08 +0000 Subject: [PATCH] Documentation for JProbe Coverage tasks git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269414 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/OptionalTasks/jpcoverage.html | 539 ++++++++++++++++++++++ 1 file changed, 539 insertions(+) create mode 100644 docs/manual/OptionalTasks/jpcoverage.html diff --git a/docs/manual/OptionalTasks/jpcoverage.html b/docs/manual/OptionalTasks/jpcoverage.html new file mode 100644 index 000000000..5b8709e24 --- /dev/null +++ b/docs/manual/OptionalTasks/jpcoverage.html @@ -0,0 +1,539 @@ + + + + + +

JProbe

+

by

+ +

Introduction

+ +

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. +

+ +

Tasks

+ + +
+ +

JPCoverage

+Perform code covering functions by comparing source code line execution to the program’s source code as a whole. + +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
homeThe 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+
javahomeFor 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
javaexeSimilar to javahome, except this is the path to + the java executable.No, use only for java2
appletRun an applet. The default is false, unless the file under + analysis ends with htm or html.No, default is "false".
seednameSeed name for the temporary snapshot files (files will be named + seed.jpc, seed1.jpc, seed2.jpc, ...)No, default to "snapshot"
exitpromptToggles 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"
finalsnapshotType of snapshot to send at program termination. Must be one + of "none","coverage","all"No, default to "coverage"
recordfromstartMust 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"
warnlevelSet warning level (0-3, where 0 is the least amount of warnings).No, default to 0
snapshotdirThe 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
workingdirThe physical path to the working directory for the VM.No, default is current directory.
tracknativesTest native methods. Note that testing native methods with + Java 2 disables the JITNo, default to "false".
classnamethe name of the class to analyze.Yes
+ +

Nested Elements

+ +

classpath

+

jpcoverage supports a nested <classpath> +element, that represents a PATH like +structure.

+ +

jvmarg

+ +

Additional parameters may be passed to the VM via nested <jvmarg> +attributes, for example:

+ +

+

+
<jpcoverage home="c:\jprobe" classname="MyClass">
+  <jvmarg value="-classic"/>
+  <classpath path="."/>
+</jpcoverage>
+

+

+would run the coverage on "MyClass" in classic mode VM.
+
+
<jvmarg> allows all attributes described in Command line arguments.

+
+
arg

+
+

+Parameters may be passed to the executed class via nested <arg>
+attributes, as described in Command line arguments.
+

+
+
socket

+
Define a host and port to connect to if you want to do remote viewing. 
+

+
+
+  
+  
+  
+
+  
+     
+    
+    
+  
+  
+     
+    
+    
+    
+
AttributeDescriptionRequired
hostthe host name/ip of the machine on which the Viewer is runningNo, default to localhost
portThe port number on which you will connect to the ViewerNo, default to 4444

+
+
+
+
filters

+
+
Defines class/method filters based on pattern matching.
+The syntax is filters is similar to a fileset.
+

+
+
+
+  
+  
+  
+
+  
+     
+    
+    
+  
+
AttributeDescriptionRequired
defaultexcludeAs 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.
+

+

+
+
+  
+  
+  
+
+  
+     
+    
+    
+  
+  
+     
+    
+    
+  
+
AttributeDescriptionRequired
classThe class mask as a simple regular expressionNo, default to *
methodThe method mask as a simple regular expressionNo, default to *

+

+
+
Example of filters

+

+  
<filters>
+    <include class="com.mycompany.*" method="*"/>
+    <exclude class="com.mycompany.MyClass" method="test*"/>
+</filters>

+

+
+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
+
+
triggers

+
+
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:
+

+
+
+  
+  
+  
+
+  
+     
+    
+    
+  
+  
+     
+    
+    
+  
+  
+     
+    
+    
+  
+
AttributeDescriptionRequired
nameThe name of the method(s) as a regular expression. The name
+	is the fully qualified name on the form package.classname.methodYes
eventthe event on the method that will trigger the action. Must be
+	"enter" or "exit".Yes
actionthe 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

+
+
Example of triggers

+

+
<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.

+
+

+
JPCovMerge

+
+
Description

+
+
Perform the merge of several snapshots into a single one.

+
+
Parameters

+
+
+	
+	
+	
+
+
+	
+    
+    
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
AttributeDescriptionRequired
homeThe directory where is installed JProbe.Yes
tofilethe output filename that will be the result
+	of the name.Yes
verbosePerform the merge in verbose mode giving
+	details about the snapshot processing.No. Default to false

+
+

+jpcovmerge collects snapshots using the nested <FileSet>
+element.
+

+
+
Example of merge

+

+
<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.
+

+
+

+
+
JPCovReport

+
+
Description

+
+
Generate a readable/printable report of a snapshot. Note that you will need Jakarta
+Oro in Ant classpath, to run the reference feature.

+
+
Parameters

+
+
+	
+	
+	
+
+
+	
+    
+    
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
+	
+	
+	
+
+
AttributeDescriptionRequired
homeThe directory where is intalled JProbe.Yes
formatThe format of the generated report. Must be "xml", "html" or "text"No, default to "html"
typeThe type of report to be generated. Must be "executive",
+	"summary", "detailed" or "verydetailed"No. Default to "detailed"
percentA numeric value for the threshold for printing methods. Must
+	be between 0 and 100.No, default to 100
snapshotThe name of the snapshot file that is the source to the report.Yes
tofileThe name of the generated output fileYes
includesourceInclude text of the source code lines. Only applies to
+      format="xml" and type="verydetailed"No. Defaults to "yes"

+
+
sourcepath

+
+

+Path to source files can be set via nested sourcepath elements that are PATH like structures.
+

+
+
reference (only applies to format="xml")

+
+
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.
+

+

+

+
+
+  
+  
+  
+
+  
+     
+    
+    
+  
+  
+     
+    
+    
+  
+
AttributeDescriptionRequired
classThe class mask as a simple regular expressionNo, default to *
methodThe method mask as a simple regular expressionNo, default to *

+

+
+
Example of report

+

+
<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.
+

+
+
Recommendation

+
+
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).

+
HTML reports

+
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>

+
+
+