Ant Tasks

JaCoCo comes with Ant tasks to launch Java programs with execution recording and for creating coverage reports from the recorded data. The JaCoCo Ant tasks require

All tasks are defined in jacocoant.jar (which is part of the distribution) and can be included in your Ant scripts with the usual taskdef declaration:

    1<project name="Example" xmlns:jacoco="antlib:org.jacoco.ant">
    2
    3    <taskdef uri="antlib:org.jacoco.ant" resource="org/jacoco/ant/antlib.xml">
    4        <classpath>
    5            <pathelement location="path_to_jacoco/lib/jacocoant.jar"/>
    6        </classpath>
    7    </taskdef>
    8    
    9    ...
   10    
   11</project>

Alternatively you might also place the jacocoant.jar in your Ant ANT_HOME/lib folder. If you use the name space URI antlib:org.jacoco.ant for JaCoCo tasks Ant will find them automatically without the taskdef declaration above.

Declaring a XML namespace for JaCoCo tasks is optional but always recommended if you mix tasks from different libraries. All subsequent examples use the jacoco prefix declared above.

Task coverage

The standard Ant tasks to launch Java programs are java and junit. To add code coverage recording to these tasks they can simply be wrapped with the coverage task as shown in the following examples:

    1<jacoco:coverage>
    2    <java classname="org.jacoco.examples.HelloJaCoCo" fork="true">
    3        <classpath>
    4            <pathelement location="./bin"/>
    5        </classpath>
    6    </java>
    7</jacoco:coverage>
    8
    9
   10<jacoco:coverage>
   11    <junit fork="true" forkmode="once">
   12        <test name="org.jacoco.examples.HelloJaCoCoTest"/>
   13        <classpath>
   14            <pathelement location="./bin"/>
   15        </classpath>
   16    </junit>
   17</jacoco:coverage>

Resulting coverage information is collected during execution and written to a file when the process terminates. Note the fork attribute above in the wrapped java task.

The nested task always has to declare fork="true", otherwise the coverage task can't record coverage information and will fail. In addition the junit task should declare forkmode="once" to avoid starting a new JVM for every single test case and decreasing execution performance dramatically (unless this is required by the nature of the test cases).

The coverage task must wrap exactly one task. While it typically works without any configuration, the behavior can be adjusted with some optional attributes:

Attribute Description Default
enabled If set to true coverage data will be collected for the contained task. true
destfile Path to the output file for execution data. jacoco.exec
append If set to true and the execution data file already exists, coverage data is appended to the existing file. If set to false, an existing execution data file will be replaced. true
includes A list of class names that should be included in execution analysis. The list entries are separated by a vertical bar (|) and may use wildcard characters (* and ?). Except for performance optimization or technical corner cases this option is normally not required. * (all classes)
excludes A list of class names that should be excluded from execution analysis. The list entries are separated by a vertical bar (|) and may use wildcard characters (* and ?). Except for performance optimization or technical corner cases this option is normally not required. empty (no excluded classes)
exclclassloader A list of class loader names, that should be excluded from execution analysis. The list entries are separated by a vertical bar (|) and may use wildcard characters (* and ?). This option might be required in case of special frameworks that conflict with JaCoCo code instrumentation, in particular class loaders that do not have access to the Java runtime classes. sun.reflect.DelegatingClassLoader

Task agent

If the coverage task is not suitable for your launch target, you might alternatively use the agent task to create the Java agent parameter. The following example defines a Ant property with the name agentvmparam that can be directly used as a Java VM parameter:

    1<jacoco:agent property="agentvmparam"/>

This task has the same attributes as the coverage task plus an additional property to specify the target property name:

Attribute Description Default
enabled When this variable is set to false the value of property will be set to an empty string, effectively disabling coverage instrumentation for any tasks that used the value. true
property Name of the Ant property to set. none (required)
All attributes of the coverage task.

Task merge

This task can be used to merge the execution data from multiple test runs into a single data store.

    1<jacoco:merge destfile="merged.exec"/>
    2    <fileset dir="executionData" includes="*.exec"/>
    3</jacoco:merge/>

The task definition can contain any number of resource collection types and has the following mandatory attribute:

Attribute Description Default
destfile Location to write the merged execution data. none (required)

Task report

Finally different reports can be created with the report task. A report task declaration consists of different sections, two specify the input data, additional ones specify the output formats:

    1<jacoco:report>
    2			
    3    <executiondata>
    4        <file file="jacoco.exec"/>
    5    </executiondata>
    6			
    7    <structure name="Example Project">
    8        <classfiles>
    9            <fileset dir="bin"/>
   10        </classfiles>
   11        <sourcefiles encoding="UTF-8">
   12            <fileset dir="src"/>
   13        </sourcefiles>
   14    </structure>
   15			
   16    <html destdir="report"/>
   17			
   18</jacoco:report>

As you can see from the example above the report task is based on several nested elements:

Element executiondata

Within this element Ant resources and resource collections can be specified, that represent JaCoCo execution data files. If more than one execution data file is specified, execution data is combined. A particular piece of code is considered executed when it is marked as such in any of the input files.

Element structure

This element defines the report structure. It might contain the following nested elements:

The structure can be refined with a hierarchy of group elements. This way the coverage report can reflect different modules of a software project. For each group element the corresponding class and source files can be specified separately. For example, the build script of JaCoCo itself contains the following declaration to separate the different bundles in the report (see the resulting report):

    1<structure name="JaCoCo">
    2    <group name="org.jacoco.core">
    3        <classfiles>
    4            <path refid="bundle-org.jacoco.core"/>
    5        </classfiles>
    6        <sourcefiles>
    7            <fileset dir="${workspace.dir}/org.jacoco.core/src"/>
    8        </sourcefiles>
    9    </group>
   10    <group name="org.jacoco.report">
   11        <classfiles>
   12            <path refid="bundle-org.jacoco.report"/>
   13        </classfiles>
   14        <sourcefiles>
   15            <fileset dir="${workspace.dir}/org.jacoco.report/src"/>
   16        </sourcefiles>
   17    </group>
   18    
   19    ...
   20    
   21</structure>

Element html

Create a multi-page report in HTML format.

Attribute Description Default
destdir Directory to create the report in. none (required)
footer Footer text for each report page. No footer
encoding Encoding of the generated HTML pages. UTF-8

Element xml

Create a single-file report in XML format.

Attribute Description Default
destfile Location to write the report file to. none (required)
encoding Encoding of the generated XML document. UTF-8

Element csv

Create single-file report in CSV format.

Attribute Description Default
destfile Location to write the report file to. none (required)
encoding Encoding of the generated CSV document. UTF-8