Part 3 - Automating Coverage Checks

This section of the tutorial looks at some advanced features of Clover.

The <clover-check> task provides a useful mechanism for automating your coverage checking and gives you the option of failing your build if the specified coverage percentage is not met. It is easily integrated into your build system.

On this page:

Adding coverage checking

Ensure that you have current Clover coverage data so that you can check the coverage percentage for your project. Clover coverage data is generated as described in Part 1 of the Tutorial.

Add the <clover-check> task to your build by specifying a target similar to the following:

<target name="clover.check" depends="with.clover">
    <clover-check target="80%"/>
</target>

This configuration sets an overall project target of 80% coverage.

Use the command ant clover.check to run the check. If your test coverage satisfies the target coverage percentage, output will be similar to the following:

$ ant clover.check
 Buildfile: build.xml

 with.clover:

 clover.check:
  [clover-check] Merged results from 1 coverage recording.
  [clover-check] Coverage check PASSED.

 BUILD SUCCESSFUL
 Total time: 2 seconds

If your coverage percentage does not reach the coverage target, you'll get something like this instead:

$ ant clover.check
 Buildfile: build.xml

 with.clover:

 clover.check:
  [clover-check] Merged results from 1 coverage recording.
  [clover-check] Coverage check FAILED
  [clover-check] The following coverage targets were not met:
  [clover-check] Overall coverage of 74% did not meet target of 80%

 BUILD SUCCESSFUL
 Total time: 2 seconds

In order to try this out on the Money Library used in this tutorial, try commenting out some of the tests in the MoneyTest.java file to create a situation where the code coverage does not reach 80%.

Failing the build if coverage criteria not met

In the above situation where the target is not met, after the message has been written to output, the build for the specified target will continue as normal.

Adding the haltOnFailure attribute allows you to specify whether or not you want the build to fail automatically if the coverage target is not met. The default for haltOnFailure is false.

<target name="clover.check.haltonfail" depends="with.clover">
    <clover-check target="80%" haltOnFailure="true"/>
 </target>

The failureProperty attribute of the <clover-check> task allows you to set a specified property if the target of the project is not met:

<target name="clover.check.setproperty" depends="with.clover">
    <clover-check target="80%" failureProperty="coverageFailed"/>
 </target>

In this case, if the coverage does not reach 80%, the property coverageFailed will have its value set to the coverage summary message "Overall coverage of *% did not meet target of 80%". This allows you to check the value of this property in other Ant targets and manage the outcome accordingly. For an example on managing the resulting actions for a project which does not meet its coverage target, see Using Clover in Automated Builds.

Adding Package-level coverage criteria

The <clover-check> task also allows you to specify the desired percentage covered for different packages, which is useful if you have certain packages that have more or less stringent coverage requirements than the rest of the project. This is done by adding nested 'package' elements like the following:

<target name="clover.check.packages" depends="with.clover">
    <clover-check target="80%">
        <package name="com.clover.example.one" target="70%"/>
        <package name="com.clover.example.two" target="40%"/>
    </clover-check>
</target>

Context filtering

The <clover-check> task allows you to prescribe a filter that excludes coverage of certain block-types from overall coverage calculations. See Coverage Contexts for more information. The filter attribute accepts a comma separated list of the contexts to exclude from coverage calculations.

<target name="clover.check.nocatch" depends "with.clover">
    <clover-check target="80%" filter="catch"/>
</target>

This will run the Clover coverage percentage check as normal, but will calculate coverage with omission of all 'catch' blocks.

NEXT:

Part 4 - Test Optimization Tutorial