Using GroboCoverage With Ant

Author:Matt Albrecht

Getting Started

This document describes how to get up and running with simple build files. The ant task guide describes each Ant task in detail. If your build environment is "complex", then this document should help your more basic questions. If you need more detailed information regarding the operation of GroboCoverage, try this document.

Downloading the GroboCoverage Files

Before you get started, download the latest GroboCoverage zip file (you can find it here), which, at the time of this document, is called GroboUtils-5-codecoverage.zip.

Inside are two JAR files, the "ant" and "runtime" code-coverage files. The "ant" file contains the code-coverage files required for compiling the coverage probes into your class files and all the dependent libraries, while the "runtime" jar only contains those class files necessary to run the recompiled class files.

Changing Your Ant Build File

To test with the coverage-enabled class files, you'll need to change your build files.

Referencing the New Tasks

First off, before using any of the provided Ant tasks, you'll need to tell Ant about them. You have two options:

Copy GroboCodeCoverage-1.1.0-ant.jar to the lib directory of your Ant installation. Then add the next lines to your build file before you reference the tasks:
```
<taskdef resource="ant-grobocoverage.properties"/>
```

Keep GroboCodeCoverage-1.1.0-ant.jar in a separate location. You now have to tell Ant explicitly where to find it (say in /usr/share/java/lib):

<taskdef resource="ant-grobocoverage.properties">
  <classpath>
    <pathelement location="/usr/share/java/lib/GroboCodeCoverage-1.1.0-ant.jar"/>
  </classpath>
</taskdef>

In order to use the <grobo-report> task, you need to have a Xalan-2 compatible XSL processor in the classpath. If one is not in your Ant classpath, then it needs to be referenced in the <taskdef> classpath. Ant versions 1.5 and above come with one by default.

Post-Compile Your Classes

Next, you'll need to "post-compile" your classes, after they've been compiled. This "post-compilation" stage inserts probes into your class files to tell when lines of code have been encountered.

Since post-compilation makes different class files that will most probably be slower than the original, the author recommends putting these into a different directory, separate from the original class files.

So, let's say you have a compilation step that looks like this:

    <javac srcdir="${src.dir}" destdir="${classes.dir}" debug="on">
        <classpath>
            <path refid="classpath.base" />
        </classpath>
    </javac>

You would then add after it the <grobo-instrument> task:

    <grobo-instrument logdir="coverage/logs" logger="fast"
            destdir="coverage/classes">
        <fileset dir="${classes.dir}">
            <exclude name="dont/check/coverage/*.class" />
        </fileset>
        
        <measure type="linecount" />
        <measure type="function" />
    </grobo-instrument>

which would put all the coverage-enabled class files into the coverage/classes directory. It will insert probes into the classes to check for Java code-lines executed, and which Java functions were called, but only for the classes that were post-compiled. In this case, none of the classes in the package "dont.check.coverage" were post-compiled. Also, this task puts all the data discovered for the compilation into the coverage/data directory. It also sets up the logging properties in the output classes directory, describing the directory to put the log files in, and to use the "fast" logger.

This task is described in the Ant task documentation.

Note: if you want the coverage report to include line numbers (showing a trace back to the original Java source files), then you must enable debugging during the <javac> task. See the Ant task reference for details.

Running Your Tests With the Post-Compiled Classes

If you want to run your tests with code coverage enabled, and you're using JUnit, here's an easy method.

Let's say you run your tests with JUnit using the optional Ant junit task like this:

    <junit printsummary="yes" fork="yes" dir="${test-output.dir}">
        <classpath>
            <pathelement location="${classes.dir}" />
            <pathelement location="${test-classes.dir}" />
            <path refid="classpath.base" />
        </classpath>
        <formatter type="xml" usefile="yes" />
        <batchtest todir="${test-output.dir}">
            <fileset dir="${test-classes.dir}">
                <include name="*Test.class" />
            </fileset>
        </batchtest>
    </junit>

Since the post-compilation step above only puts coverage-enabled versions of the specified classes into the directory coverage/classes, this class directory, then, doesn't contain any special files or classes excluded from coverage. So, we need to tell the JUnit task to reference these covered classes, but also to include the other files. We do this by replacing the JUnit task's classpath with this:

        <classpath>
            <pathelement location="coverage/classes" />
            <pathelement location="${classes.dir}" />
            <pathelement location="${test-classes.dir}" />
            <path refid="classpath.base" />
            <pathelement location="GroboCodeCoverage-1.1.0-runtime.jar" />
        </classpath>

We added the coverage-enabled classes before everything else (so they have priority in the class loader), and we also added the runtime jar, as the coverage-enabled classes require these to run.

The <grobo-instrument> task told the logger running these tests will put all the coverage log information into the coverage/logs directory, and to use the "fast" logger.

Generating a Report

Now that coverage numbers are being generated, we need to add in additional Ant script to generate a coverage-number report.

If you're using the <junit> task, then you're probably also using the <junitreport> task. If not, check it out. The ant documentation for it can be found here

Whether you use the <junitreport> task or not, we can add in the coverage report task after the <junit> task, when the reports should be generated:

    <grobo-report logdir="coverage/logs">
        <simple destdir="coverage" removeempty="true" />
        <source destdir="coverage/source-report" removeempty="true"
            srcdir="src" title="Summary Coverage Report of My Code" />
    </grobo-report>

The <grobo-report> task takes all the different generated data from the data and log directories (as specified in the <grobo-instrument> task above) and generates reports.

The embedded style tags define what kind of reports to generate. The "simple" tag generates one HTML file for each measure, and the "source" tag generates a JavaDoc-style collection of web pages that link the Java souce code to the coverage reports.

On large class-file systems, this report generator may consume large amounts of memory. If you see Ant generate an OutOfMemoryError, then you can increase the amount of memory that the JVM uses with the environment variable ANT_OPTS. For instance, to increase the memory usage to 128 MB, on a 1.4 JVM, you would use:

    > set ANT_OPTS=-Xmx128M

on Windows, and

    $ ANT_OPTS=-Xmx128M
    $ export ANT_OPTS

on the Bourne shell.


This space graciously provided by the SourceForge project	Copyright © 2002-2004 GroboUtils Project. All rights reserved.