Java cvprof Coverage Profiler, Analysis, Reporting

Note

I recommend that you consider using Cobertura for your coverage profiling needs, as it is actively maintained, and has a better feature-set.

About

cvprof is a source-line coverage profiler for Java code, released under the terms of the LGPL. cvprof is a rewrite of JVMDICover that works under J2SDK-1.2, J2SDK-1.3 and J2SDK-1.5 (beta).

JVMDICover was written by Joel Crisp and others.

cvprof is implemented using the Java2 JVMDI interface present in Sun's Java Virtual Machines. It is a native library, loaded into the JVM at startup. The reporting portion of cvprof is implemented in the Ruby language, and the coverage profile is stored in a BerkleyDB hash file.

Example Reports

This example cvprof report shows the coverage of a number of test-case classes.

A coverage report for JUnit, after profiling JUnit's own unit test suite.

Usage

Having obtained the source and compiled the library, you should ensure that the profiler plugin will be found by the JVM. If the library isn't installed in the system library path, this can be achived by adjusting the LD_LIBRARY_PATH environmental variable. e.g., in bash,

LD_LIBRARY_PATH=/path/containing/library/
export LD_LIBRARY_PATH

Then, invoke your JVM like this,

java -Xdebug -Xnoagent -Djava.compiler=NONE -Xruncvprof some.class.Name

This will generate a coverage profile in a binary file called coverage.db, in the current directory. After the JVM has finished running, a coverage report can be generated from the coverage profile using the reporting tool,

cvprof_report.rb --sourcepath=path_to/source/files

This should produce an HTML report in a new directory called html_cvprof_report.

Status

The profiler has only be tested under Linux. The software is not quite production quality yet, though there are no known crashing issues, and those features that exist work pretty well.

Tested successfully in,

J2SDK 1.5 beta 1 for 32bit Linux
J2SDK Blackdown-1.3.1_02b-FCS
J2SDK JDK-1.2.2_017

Works partially in, (see below for known issues)

J2SDK 1.4.0.99beta-1
J2SDK 1.4.1_01

Known Issues

The versions of J2SDK 1.4 that have been tested (1.4.0.99beta-1 and 1.4.1_01 for Linux) seem to interact badly with cvprof, producing dubious coverage information: cvprof's single-step event handler doesn't seem to get invoked for some methods, which will leave gaps in the coverage profile.
The coverage profile, stored in coverage.db, will be updated by any cvprof-enabled JVM invocations after the initial invocation that created it. This behaviour isn't supported, or guaranteed to work properly. If in doubt, explicitly delete coverage.db between each profiling run.
The reporting software does not yet sort lists of classes/packages, or do other sensible stuff that it should.
There appears to be a Java interface to BerkleyDB these days, so it would be interesting to re-implement the reporting tool in Java, rather than Ruby.

Download

Current

2004-04-27 cvprof-0.1.2.tar.gz ~287KiB

HTML report now gives overview coverage metrics on package/class list pages
Profiling works again on JDK1.2
Now uses Autoconf

2004-04-19 cvprof-0.1.1.tar.gz ~29KiB

Fixed a race-condition in the VM-death handler that sometimes caused java to crash
Allow specification of a list of packages and classes to be excluded from profiling
MinGW/Cygwin compliation fixes, though profiling under windows is still untested

2004-04-11 cvprof-0.1.0.tar.gz ~17KiB

Compiling

mkdir /tmp/cvprof
./configure --prefix=/tmp/cvprof
make
make install

This will install cvprof_report in /tmp/cvprof/bin and libcvprof.so in /tmp/cvprof/lib. If using this prefix, you will need to set LD_LIBRARY_PATH to /tmp/cvprof/lib as explained above.

Contact

<dave at badgers-in-foil.co.uk>.