Test Optimization Quick Start Guide for Ant

This page contains the basic steps for adding Clover's Test Optimization to an existing Ant configuration.

Follow the steps in this document to set up Clover's Test Optimization, which allows targeted testing of only the code which has changed since the last build.

These steps assume your build is Clover-enabled already (in particular it has a with.clover task already set up and has a taskdef established for the Clover Ant tasks). You will have to complement this quick start guide with basic Clover configuration information.

These steps also assume that your build file is currently used for a CI (Continuous Integration) build and possibly for general builds (e.g. On a developer's own machine). Below, we describe how you can take that build file and add sections to bake in Test Optimization. Adding optional support for Test Optimization (switching it on/off), specifying whether test minimisation is performed and test reordering other than the default 'failfast' are advanced options which are covered elsewhere.

BEFORE YOU START

Try to ensure your unit tests do not have dependencies between them as this may cause optimized builds to fail more frequently than usual.

BASIC STEPS

1. You will need to use this:

   <taskdef resource="cloverlib.xml" classpath="${clover.jar}"/>
   

   
   If you are using Ant 1.7 or later, you will also need to use the following:

   <taskdef resource="cloverjunitlib.xml" classpath="${clover.jar}"/>
   

2. Choose a location for the test snapshot file that can survive clean builds. This location:

   <PROJECT_DIR>/.clover/coverage.db.snapshot
   

   The default is not as good as manually deleting this directory each build, but it is workable if you only use <clover-clean/>as, by default, it won't delete snapshots. Add a property for this, as in the following example:

   <property name="clover.snapshot.file" value="/path/to/clover.snapshot"/>
   

3. Add a target to generate the test snapshot:

   <target name="clover.snapshot" depends="with.clover">
        <clover-snapshot file="${clover.snapshot.file}"/>
    </target>
   

4. For Ant 1.7 and later, modify the batchtest element of the <junit/> task used to test your application, so that the filesets are wrapped in the clover-optimized-testsetelement. See the following example:

   <junit ...>
   <batchtest fork="true" todir="${test.results.dir}/results">
       <fileset dir="src/tests" includes="${test.includes}" excludes="${test.excludes}"/>
   </batchtest>
   </junit>
   

   This becomes the following:

   <junit ...>
   <batchtest fork="true" todir="${test.results.dir}/results">
       <clover-optimized-testset snapshotfile="${clover.snapshot.file}">
           <fileset dir="src/tests" includes="${test.includes}" excludes="${test.excludes}"/>
       </clover-optimized-testset>
   </batchtest>
   </junit>
   

5. For Ant 1.6, modify any fileset in the batchtest element and add a clover-optimized-selectorelement:

   <junit ...>
   <batchtest fork="true" todir="${test.results.dir}/results">
       <fileset dir="src/tests" includes="${test.includes}" excludes="${test.excludes}"/>
   </batchtest>
   </junit>
   

   This becomes the following:

   <junit ...>
   <batchtest fork="true" todir="${test.results.dir}/results">
       <fileset dir="src/tests" includes="${test.includes}" excludes="${test.excludes}">
           <clover-optimized-selector snapshotfile="${clover.snapshot.file}"/>
       </fileset>
   </batchtest>
   </junit>
   

   Optimized test reordering is only available for Ant 1.7 and using the clover-optimized-testset element. Ant 1.6 and clover-optimized-selector only permit the minimisation of the tests run, not optimal ordering.

6. Run the optimized build (this will typically be run by their CI plan). Assuming a "run.tests" target modified in steps 4/5 (with appropriate dependencies so that the code is instrumented/compiled/packaged):

   ant with.clover clean run.tests clover.snapshot
   

Running Java and Groovy test cases

Please note that Ant's <junit>/<batchtest> collects the included resources from any number of nested resource collections and then generates a test class name for each resource that ends in .java or .class. It means that you cannot use <include name="**/*Test.groovy"/> because such files will be ignored. However, you can point to *.class files, for example:

<junit ...>
    <classpath refid="build.classpath"/>
    <batchtest fork="yes" todir="${test.result}">
        <clover-optimized-testset snapshotfile="${clover.snapshot.file}">
            <fileset dir="${build.dir}">
                 <include name="**/*Test.class"/>
            </fileset>
        </clover-optimized-testset>
    </batchtest>
</junit>

Using the configuration above, Clover will optimize tests according to:

• changes in application code written in Java or Groovy
• changes in test code written in Java

Related Links

• Overview of Test Optimization

• Test Optimization Technical Details

• Test Optimization Quick Start for Maven 2

• Clover for Maven 2 - Test Optimization Best Practices