# 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](https://ant.apache.org/manual/index.html). 1. The Diffblue Cover `cover-buildsystem-ant.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: \ 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](#test-filtering) below) 5. The project is configured to produce JUnit and JaCoCo XML reports (see [Reporting Test Execution and Coverage](#reporting-test-execution-and-coverage) below) 1. For JUnit reports, refer to 2. For JaCoCo XML reports, refer to 6. The project is configured to generate the structure and event messages (see [Reporting the Project Structure and Events](#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](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md)) 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): ```properties // 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 `path`s 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): {% code lineNumbers="true" fullWidth="true" %} ```xml ``` {% endcode %} ### 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](https://www.eclemma.org/jacoco/trunk/doc/ant.html) 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](https://ant.apache.org/manual/Tasks/junitreport.html) 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: {% code lineNumbers="true" fullWidth="true" %} ```xml ``` {% endcode %} #### 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. {% code lineNumbers="true" fullWidth="true" %} ```xml ${ant.project.name} ${antversion} ${java.target} ${file.encoding} xml ``` {% endcode %}

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 `projectModule`s 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](https://docs.diffblue.com/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cover-docs.diffblue.com/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system/getting-started-with-ant-projects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.