JProbe

by

• Stephane Bailliez (sbailliez@imediation.com)

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

Parameters

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>

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

filters

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

  <filters>
    <exclude class="*" method="*"/>
  </filters>

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

Example of filters

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

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:

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

jpcovmerge collects snapshots using the nested <FileSet> element.

Example of merge

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

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

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:

• 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).
• add classes that exists in the reference set and match the filters but are not reported.
• remove abstract methods that are incorrectly reported in JProbe 3.0 (should be fixed in a later SP)
• remove classes/methods that do not match the filters.

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 *

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>

Copyright © 2001-2002,2004 The Apache Software Foundation. All rights Reserved.