JCov 2.0 Tutorial
 

This tutorial describes some typical methods for using JCov to get and analyze code coverage information for Java. It covers the following topics:

[Top]

Tutorial overview

[Top]

This tutorial demonstrate the typical usage of JCov, including different ways to receive code coverage data using JCov, and some JCov features that give more useful information about tested code. The procedure to receive code coverage information for any product contains 3 general steps:

With JCov you can perform these steps separately (called static instrumentation mode) or simultaneously (called dynamic instrumentation mode). Some of the different approaches of coverage measurement shown in this tutorial are:

The tutorial contains:

Component Description
tutorial JCov tutorial, consisting of the following:

Tutorial.html

Short user guide how to start work with JCov tool.

tutorial.build.xml, tutorial.build.properties

The file tutorial.build.xml should be used to build the demo application and run the tutorial examples. Default properties can be found in the tutorial.build.properties file. Without any changes in properties (after building jcov binaries with default values) tutorial.build.xml will create DEMOAPP_BUILD directory with the following structure:

  • classes of demo application
  • example# contains build.xml file to run each example
  • test_classes classes to verify demo application functionality
  • demoapp.jar demo application jar file

/doc

Documentation directory.

/example

There is build.xml in each example directory. During the demo application build, these examples will be added to DEMOAPP_BUILD directory.

/src

Source files for simple demo application (the application could count area of figures on the plane).

/test

Source files for tests to verify the demo application functionality.

Stepping through the tutorial

[Top]

The tutorial contains basic steps which are discussed in their own section as follows:

Compile the Source Code

To compile source code of the example application and tests, execute ant in the tutorial directory:

ant -f tutorial.build.xml

This will create the DEMOAPP_BUILD directory with all jcov examples for this application. The tutorial.build.properties file contains properties which are used in building the demo application and running jcov examples. This simple demo application allows users to create two types of figures (square and disc); add these figures to the plane, and count the area of the figures on the plane depending on their color. There are two tests in the directory test (TestDemoApp1, TestDemoApp2) for this demo application. All the JCov examples will show how to receive code coverage data for this demo application - which describes how well the demo application is covered by these tests.

Run JCov example

After building the tutorial demo application (previous step), you can see the example# directories in the created DEMOAPP_BUILD directory. Each of these directories contains a build.xml file for independent JCov examples. Execution of the ant command (in the corresponding example# directory):

ant -f build.xml

will run a JCov example and create a coverage directory in the example# with the code coverage report for the executed tests.

Static instrumentation with grabber

This example is using JCov static instrumentation, it means that there are 5 separate steps to receive code coverage information:

  1. instrumenting the application

    java -jar jcov.jar instr -t template.xml -o instr_classes $path_to_classes

  2. starting a grabber to receive code coverage results

    java -jar jcov.jar grabber -t template.xml -o result.xml

    (separate process)

  3. running tests

    (as usual just adding jcov_network_saver.jar in classpath)

  4. saving code coverage results (stopping the grabber)

    java -jar jcov.jar grabbermanager -kill

  5. generating report for received code coverage results

    java -jar jcov.jar repgen -o report result.xml

All these steps are presented in the static_instr.xml file. These are the same steps that can be executed from the command line. The static instrumentation may be generally easier to setup for complicated cases (eg. loading large API sets, things that require a large set of Java classes to be loaded). Static instrumentation typically adds only minor overhead on test execution.

Dynamic instrumentation with grabber

The general procedure to receive code coverage information for any product contains 3 steps:
  1. instrument product code
  2. running tests
  3. save and display received code coverage results
Step1 and Step2 could be combined together if javaagent is used. In this case, application classes will be instrumented on loading, and a template.xml file is created in memory. This example is using JCov dynamic instrumentation:

  1. generate template

    java -jar jcov.jar tmplgen -t template.xml $path_to_classes

    (this step is needed to include unmodified application classes to the final code coverage report)

  2. start the grabber to receive code coverage results

    java -jar jcov.jar grabber -t template.xml -o result.xml

    (separate process)

  3. run the tests

    adding javaagent option: "-javaagent:jcov.jar=grabber"

  4. save the code coverage results (stopping the grabber)

    java -jar jcov.jar grabbermanager -kill

  5. generate the report for received code coverage results

    java -jar jcov.jar repgen -o report result.xml

All these steps are presented in the dynamic_instr.xml file, the same steps could be executed from the command line. The dynamic instrumentation is good for small and simple cases (eg. small apps, limited API, things that don't require a large set of Java classes to be loaded). Without the tmplgen command the report will not include unused classes in dynamic mode.

Static instrumentation with file

This example is using jcov static instrumentation without a grabber. This approach (or dynamic instrumentation without grabber) could be used for fast results in small and simple cases:

  1. instrument the application

    java -jar jcov.jar instr -t template.xml -o instr_classes $path_to_classes

  2. run tests

    (adding jcov_file_saver.jar in classpath, setting jcov.template and jcov.file properties)

  3. generate a report for received code coverage results

    java -jar jcov.jar repgen -o report result.xml

All these steps are presented in the static_instr_file.xml file, the same steps could be executed from the command line.

One command to get coverage

This example is using JCov 'one command' feature to get coverage data without understanding any JCov inner processes. For this, a user needs to specify the application classes and the command to run tests:

  1. get coverage for tests using one jcov command

    java -jar jcov.jar jcov -pro $path_to_classes -out report -command "java -cp jcov_network_saver.jar MainTestsExecuter"

With this approach JCov will perform static instrumentation with a grabber in background mode. All these steps are presented in the one_command.xml file, the same steps could be executed from the command line.

JCov ant tasks to get coverage

This example shows how to add regular code coverage support to an existing applications' ant build. JCov ant tasks can be used in an applications' ant build to add static instrumentation with a grabber in a more convenient way. To be able to use instrument, grabber, grabber-manager or report tasks, a user needs to add JCov tasks in the application build.xml file:

<taskdef name="jcovTasks" classname="com.sun.tdk.jcov.ant.AllTasks" classpath="jcov.jar"/>

Usage of the jcov ant tasks is presented in the jcov_ant_tasks.xml file.

Individual test coverage

This example is using JCov static instrumentation with grabber and additional information for each test:

  1. instrument the application

    java -jar jcov.jar instr -t template.xml -o instr_classes $path_to_classes

  2. start the grabber to receive code coverage results with tests information

    java -jar jcov.jar grabber -t template.xml -outtestlist testlist.txt -o result.xml

    (separate process)

  3. run the tests

    (adding jcov_network_saver.jar in classpath, setting jcov.testname property for each test)

  4. save code coverage results (stopping the grabber)

    java -jar jcov.jar grabbermanager -kill

  5. generate a report for received code coverage results with tests' information

    java -jar jcov.jar repgen -o report -tests testlist.txt -testsinfo -src $path_to_src result.xml

All these steps are presented in the jcov_scales.xml file, the same steps could be executed from the command line.