Getting Started with Ant Projects

Overview

This page guides you through configuring your Ant project to work with Diffblue Cover. Cover needs to understand the structure of the project, and to execute commands and receive feedback from the build system. This is achieved by adding an event spy to produce structured messages and easily add support for additional build systems for Cover.

The diagram below gives an overview of how Diffblue Cover interacts with a build system. The rest of this document walks through how to configure this for an Ant project.

High-level overview of the interaction between Cover and a generic build system. Diffblue provided components are highlighted in blue, external components are in yellow. By-products that Cover requires are in grey and are expected to be generated from the build system.

The following is a list of requirements for Diffblue Cover to analyse an Ant project:

1. The Ant application binary is installed and can be used to build the project on the command line. Instructions for installing Ant are available on the Apache Ant website.

   1. The Diffblue Cover cover-buildsystem-ant-jar-with-dependencies.jar is available to Ant and added to the classpath. This is available via the Diffblue Maven Repository as well as being distributed in the zip file containing the rest of the Diffblue Cover application. The artifact can be resolved on the Diffblue Maven Repository using the following details: URL: https://maven.diffblue.com/release organisation: com.diffblue.cover name: cover-buildsystem-ant version: matches the version of Diffblue Cover you're using, e.g. 2025.02.02
2. The project is available on your computer and builds without any warnings or errors (i.e. the exit code is zero).

3. The project is configured to compile test classes (including **/*DiffblueTest.java files)

4. The project is configured to filter tests by file name from a (series of) command line options (see Test Filtering below)
5. The project is configured to produce JUnit and JaCoCo XML reports (see Reporting Test Execution and Coverage below)

   1. For JUnit reports, refer to https://ant.apache.org/manual/tasksoverview.html#testing
   2. For JaCoCo XML reports, refer to https://www.eclemma.org/jacoco/trunk/doc/ant.html
6. The project is configured to generate the structure and event messages (see Reporting the Project Structure and Events)
7. Diffblue Cover is configured to invoke tasks and command line flags for the different phases (see Configuring Cover to work with your project's build system)

The next parts of this document will describe the configuration using an example project.

Project Overview

For the rest of this guide we will refer to the project outlined below. This is a single module project configured with separated production classes and dependencies from test classes and dependencies. The project has been configured to run tests using JUnit Jupiter (junit5) and measure coverage via JaCoCo reports.

.
├── build.xml
├── build-lib
│  ├── apache-ivy-2.5.3.jar
│  ├── jacocoant-0.8.12.jar
│  └── org.jacoco.ant-0.8.8.jar
├── ivy.xml
└── src
    ├── main
    │  └── org
    │     └── example
    │         ├── Basic.java
    │         └── HelloWorld.java
    └── test
        └── org
           └── example
               └── BasicTest.java

In this example project, we have two production classes in the org.example package (Basic and HelloWorld). There is a single test class BasicTest which has been configured to run with JUnit Jupiter. In the lib folder is where the dependencies of the project's build phase live.

The build.xml has been configured to provide the following targets:

Main targets:

 clean         Remove files generated at build time
 clean-jar     Cleans and packages the project
 compile       Compile the production sources of the project
 jar           Package the compiled production classes in an executable JAR
 main          Cleans and runs the project
 resolve       Retrieve project test/production dependencies
 run           Run the executable JAR
 test          Runs the tests and generate JUnit and JaCoCo coverage reports
 test-compile  Compile the test sources of the project

There are a number of properties that are defined (which will become important later on when configuring the project description):

// The name of the project, defined in the `project` definition
ant.project.name=sample

file.encoding=UTF-8
java.target=11

// Test inclusion and exclusion by file name
test.excludes=
test.includes=**/*Test*

// Location of source code
src.dir=${BASEDIR}/src
prod.src.dir=${BASEDIR}/src/main
test.src.dir=${BASEDIR}/src/test

// Location of third-party dependencies for production and tests
lib.dir=${BASEDIR}/lib

// Location of the build artifacts
build.dir=${BASEDIR}/out

// The final jar artifact
jar.dir=${BASEDIR}/out/jar

// The compiled production and test classes respectively
prod.classes.dir=${BASEDIR}/out/classes
test.classes.dir=${BASEDIR}/out/test-classes

// Various report artifacts for JUnit and JaCoCo tests
jacoco.exec.file=${BASEDIR}/out/jacoco.exec
test.report.dir=${BASEDIR}/out/reports
junit.report.dir=${BASEDIR}/out/reports/tests
jacoco.report.dir=${BASEDIR}/out/reports/coverage
jacoco.report.xml=${BASEDIR}/out/reports/coverage/report.xml

There are also the following classpath entries defined. First, there are two paths used to group the third-party product and test dependencies (respectively), these are resolved by the resolve target (defined on line 1) using Ivy to manage the dependencies and put the list in the compile.path (line 3) and test.path (line 4) for the different sets of dependencies. The test.classpath contains the list of test dependencies (line 8), the compiled production classes (derived from src/main -- line 9), and finally the compiled test classes (derived from src/test -- line 10):

<target name="resolve" description="Retrieve project test/production dependencies">
    <ivy:retrieve/>
    <ivy:cachepath pathid="compile.path" conf="compile,provided"/>
    <ivy:cachepath pathid="test.path" conf="test,compile,provided"/>
</target>

<path id="test.classpath">
    <path refid="test.path"/>
    <pathelement location="${prod.classes.dir}"/>
    <pathelement location="${test.classes.dir}"/>
</path>

Project Configuration

Before we can configure Cover the project needs to be set up correctly to: measure coverage of any preexisting tests as well as coverage of any newly created tests; report on test successes and/or failures. This ensures the written tests are not going to fail when integrated into the code base.

We will explain the requirements below in turn. The following configuration examples highlight just the necessary parts for illustrative purposes but they must cooperate in a complete project configuration.

Test Filtering

During execution of tests we need to differentiate between any preexisting tests and those created by Diffblue Cover, as well as running a single test. By default all the tests created by Diffblue Cover will be placed in files that end in DiffblueTest.java. This filter needs to be able to be specified via the command line.

An example of a configuration allowing this follows:

<property name="test.includes" value="**/*Test*"/>
<property name="test.excludes" value=""/>

<!-- some point later -->

<junitlauncher>
  <classpath refid="test.classpath"/>
  <testclasses>
    <fileset dir="${test.classes.dir}" 
      includes="${test.includes}"
      excludes="${test.excludes}"/>
  </testclasses>
</junitlauncher>

In this example, we define two properties: test.includes (line 1) and test.excludes (line 2). On the command line, you can then over-ride the include/exclude tests as outlined below:

• Only Diffblue tests:

  -Dtest.includes=**/*DiffblueTest*

• Only Manual tests:

  -Dtest.excludes=**/*DiffblueTest*

• Named test:

  -Dtest.includes=**/DummyDiffblueTest*

By not specifying either of those properties on the command line, all tests (i.e. those with file names containing Test) will be considered as per the configuration file.

Reporting Test Execution and Coverage

The project must be set up to measure the coverage (taking into account the test filters described above). The JaCoCo Ant Tasks should be configured to produce XML reports. Furthermore, the project must be set up to report on the status of the tests. The JUnit Report Task documentation describes the necessary steps. Diffblue Cover expects that the names of the reports follow the task’s default settings.

The configuration for these follows the respective documentation. An example of the configuration for these two requirements follows:

<target name="test" depends="test-compile">

  <mkdir dir="${junit.report.dir}"/>
  <jacoco:agent property="jacocoagent" destfile="${jacoco.exec.file}"/>

  <junitlauncher>
  <!-- as above -->
  </junitlauncher>

  <mkdir dir="${jacoco.report.dir}"/>

  <jacoco:report>
    <executiondata>
      <file file="${jacoco.exec.file}"/>
    </executiondata>
    <structure name="${ant.project.name} JaCoCo Coverage Report">
      <classfiles>
        <fileset dir="${prod.classes.dir}"/>
      </classfiles>
      <sourcefiles encoding="UTF-8">
        <fileset dir="${prod.src.dir}"/>
      </sourcefiles>
    </structure>
    <xml destfile="${jacoco.report.xml}"/>
  </jacoco:report>

  <junitreport todir="${junit.report.dir}">
    <fileset dir="${junit.report.dir}">
      <include name="TEST-*.xml"/>
    </fileset>
    <report format="frames" todir="${junit.report.dir}/html"/>
  </junitreport>

</target>

Reporting the Project Structure and Events

For Diffblue Cover to process the project structure needs to be passed via a custom task called projectModule. First we show an example and then describe the purpose and requirements of each of the different options.

This comprises of four steps:

1. Add Cover to the name space (there may be other namespaces and attributes present in your project definition), lines 1 and 2.

2. Add the taskdef pointing to the resource and the jar file (in this example we point to location on the file system where the jar has been extracted manually - adjust if you have used Ivy to manage the dependency). This appears in lines 4 to 8.

3. Add the build event listener, conditional on the cover property being set (to avoid unnecessary output when invoked outside Diffblue Cover). This appears on line 10, and should appear as early as possible (but after the taskdef step).

4. Add a task to create the projectModule structure (we will explain what each field does below), lines 12 onwards.

<project
  xmlns:cover="antlib:com.diffblue.buildsystem.cover.ant">
  
  <taskdef 
    uri="antlib:com.diffblue.buildsystem.cover.ant"
    resource="com/diffblue/cover/buildsystem/ant/antlib.xml">
    <classpath path="path/to/cover-buildsystem-ant-jar-with-dependencies.jar"/>
  </taskdef>
  
  <cover:installListener if:set="cover"/>
  
  <target name="info" depends="compile">
    <cover:projectModule>
    
      <!-- Mandatory for correct presentation of project in CLI output -->
      <cover:moduleName>${ant.project.name}</cover:moduleName>
      
      <!-- Optional for correct presentation of project in CLI output -->
      <cover:version>${antversion}</cover:version>
      
      <!-- Optional for creating tests -->
      <cover:location location="${basedir}"/>
      
      <cover:classpath>
        <path refid="test.classpath"/>
      </cover:classpath>
      
      <cover:productionClasses location="${prod.classes.dir}"/>
      <cover:productionSources location="${prod.src.dir}"/>
      <cover:testClasses location="${test.classes.dir}"/>
      <cover:testSources location="${test.src.dir}"/>
      
      <!-- Optional for creating tests -->
      <cover:complianceLevel>${java.target}</cover:complianceLevel>
      <cover:encoding>${file.encoding}</cover:encoding>
      <cover:junitReport location="${junit.report.dir}"/>
      
      <!-- Mandatory for coverage-reports -->
      <cover:buildDirectory location="${build.dir}"/>
      <cover:jacocoReport location="${jacoco.report.xml}"/>
      <cover:jacocoDestFile location="${jacoco.exec.file}"/>
      
      <!-- Optional for coverage reports -->
      <cover:jacocoFormats>xml</cover:jacocoFormats>
      
      <!-- Optional -->
      <cover:submodules/>
    </cover:projectModule>
  </target>
</project>

Element	Explanation	Requirement
moduleName	The name of the module. Appears in the output of Diffblue Cover	Mandatory[1]
version	The version of Ant in use	Optional
location	The absolute path on the file system to that module.	Mandatory[1]
classpath	The classpath containing any production classes, third party production libraries, and third party test libraries	Mandatory
productionClasses	The absolute path to the compiled production class files	Mandatory
productionSources	The absolute path to the compiled production source code	Mandatory
testClasses	The absolute path to the compiled test classes	Mandatory
testSources	The absolute path to the test source code	Mandatory
complianceLevel	The version of java used to compile the classes in the project	Optional
encoding	The file encoding used in the project	Optional
junitReportLocation	The absolute path to the JUnit test reports	Optional
buildDirectory	The absolute path to the directory containing the compiled classes and reports	Mandatory
jacocoReport	The absolute path to the JaCoCo report file	Mandatory
jacocoDestFile	The absolute path to the JaCoCo exec file	Mandatory
jacocoFormats	The list of report formats produced during JaCoCo's report task	Optional
submodules	A list of projectModules that describe submodules of the project	Optional

[1] Diffblue Cover is designed to iterate across the modules if they're present. If the submodules have been specified, then only the moduleName and location are mandatory - representing the root module of the project.

Diffblue Cover Configuration

To configure the DiffblueBuild.yaml file for use with ant, refer to configuring Diffblue Cover to work with your project's build system. Briefly, Diffblue Cover combines the arguments specified in that file to invoke commands as if a user had typed them on the command line.