Vous êtes sur la page 1sur 100

Clover User Manual

Version 2.0a5

Clover 2.0a5 User Manual

1. Introduction
1.1. Starting Points
If you are new to Clover and want to get it going with your Ant project quickly, try the Quickstart Guide. The Introduction for Code Coverage section provides a brief background on the theory and motivation behind Code Coverage. If you are upgrading from Clover 1.x, read about what's new in Clover 2, the upgrading guide, and the Best Practices for Clover Integration. If you are browsing and interested in seeing how Clover can be used on your project, see Using Clover Interactively and Using Clover in Automated builds. If you are using a Clover IDE Plugin, see the Plugin Guides section. The Clover Tutorial provides a good alternative introduction to Clover. For help with Ant, see The online Ant manual at http://ant.apache.org/manual/index.html. Also recommended reading is Eric Burke's Top 15 Ant Best Practices. For Clover troubleshooting information, see the Online Forums. 1.1.1. System Requirements
JDK Version Ant Version Operating System JDK 1.4 or greater required. Ant 1.4.1 or greater. Ant 1.6.1 or greater recommended. Clover is a pure Java application and should run on any platform provided the above requirements are satisfied.

The Clover IDE Plugins document their own IDE version requirements. Please consult the Plugins Section 1.1.2. Installing your license file You need a valid Clover license file to run Clover. You can obtain a free 30 day evaluation license or purchase a commercial license at http://www.cenqua.com. To install your Clover license file, you need to do one of the following: • Place the license file next to the Clover jar file (or next to the Clover plugin jar file, if you

Page 2
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

Clover 2.0a5 User Manual

• •

are running a Clover IDE plugin). Place the license file on the Java Classpath that will be used to run Clover. Place the license file on the file system somewhere, and then set the Java System Property clover.license.path to the absolute path of the license file.

1.1.3. Acknowledgements Clover makes use of the following excellent 3rd party libraries.
Jakarta Velocity 1.2 Antlr 2.7.1 iText 0.96 Jakarta Ant overLIB Note:
To prevent library version mismatches, all of these libraries have been obfuscated and/or repackaged and included in the clover jar. We do this to prevent pain for users that may use different versions of these libraries in their projects.

Templating generation.

engine

used

for

Html

report

A public domain parser generator. Library for generating PDF documents. The Ant build system. JavaScript library for popups and tooltips.

1.2. ChangeLog
1.2.1. Changes in 2.0a5 5 May, 2007 New Features • [CCD-395] - coverage on test classes is now reported separately to coverage of application classes. You can also optionally nominate filesets that define your test classes. See the new <testsources/> nested element. This also applies to Clover historypoints. This means that Clover historypoints are once again compatible with Clover 1.x history points for those that excluded test source metrics. Note that the history point XML has changed to introduce the test source metrics in a separate high-level node. • [CCD-389] - coverage generated solely by a failed test is now marked orange • [CCD-390] - unique coverage a test contributes is now reported on the test results page. Source code that is only hit by a single test is high-lighted dark green when that test is selected. Improvements

Page 3
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

and there is no longer any need to use the <extendclasspath> task if you were previously.CCD-313] .Clover 2.fixed links to mover classes on Historical report • [CCD-386] .jar"/> to load Clover2 • [CCD-365] .language level for instrumentation now defaults to the JDK version detected at runtime • [CCD-397.improve bottom-left panel and make it more consistent • [CCD-416] .HTML reports are now XHTML1 (transitional) compliant • [CCD-420] .2.IOE in some cases if initstring specified manually 1.xml" classpath="/path/to/clover.jar"/> New Features • [CCD-13] .header colours for test result pages more distinguishable • [CCD-411] . quickwins.jar is no longer needed .fixed problem where rapid sequential flushing might lead to missed recordings • [CCD-415] .jar file no longer needs to reside in the ant/lib (or ~/. The clover. Changes in 2.ant/lib) directory. simply declare <taskdef resource="cloverlib.click-thru to source line includes visual cue Bugs Fixed • [CCD-419] .allow report "home" page to be specified: one of "dashboard.reporters now report the database they are reporting on during report creation • [CCD-401] .AIOOBE if the report-time source is significantly different from the instrumentation-time source • [CCD-400] . Instead.Reports now render better in IE7 and Safari • [CCD-398] . to make Clover available to your build. aggregate.xml" classpath="/path/to/clover.fixed <clover-log>'s logging • [CCD-407] . All rights reserved. overview. testresults.fixed lexer handling of \u0000 in source • [CCD-418] .TestCase detection breaks when non-test inner class present • [CCD-421] . projectrisks" Page 4 Copyright © 2002-2004 Cenqua Pty Ltd.new attribute "projectName" on clover-report task to overwrite report title • [CCD-366] .use: <taskdef resource="cloverlib.'Least Tested Methods' report on the dashboard Improvements • [CCD-371] .NPE in ANT when Clover is run from NetBeans • [CCD-126] .0a5 User Manual • [CCD-408] .0a4 28 February.2. 2007 As of this release we've simplified the way Clover integrates with Ant builds. .cenquatasks.

2.<clover-historypoint> should warn when overwriting an existing history point • [CCD-359] .Clover 2. CLI and Compiler Adapter • [CCD-362] .0a5 User Manual • [CCD-368] .detect testNG @Test class-level annotation • [CCD-373] .instrumentation results in IOException on Windows 1.minor inconsistencies • [CCD-354] . . 2006 New Features • [CCD-325] .preliminary implementation of Dashboard summary report Improvements • [CCD-306] .support filesets in <clover-report/> again • [CCD-385] .html reports . 2006 New Features • [CCD-353] . Changes in 2.0a2 9 December.0a1 Page 5 Copyright © 2002-2004 Cenqua Pty Ltd. HtmlReporter Bugs Fixed • [CCD-348] .3.Optimized HTML report performance and size Bugs Fixed • [CCD-384] .support interval based flush policies again • [CCD-372] .0a3 22 December.Clover license check fails in some non-english locales • [CCD-356] .Quick Wins should include complexity in weighting • [CCD-360] .4.2.add duplicate task name <clover-instrument/> • [CCD-370] .<clover-instr> doesn't handle srcdir==destdir gracefully 1.2.new <clover-instr> task Bugs • [CCD-355] . Changes in 2. Changes in 2.Make instrumentation more consistent between task.5.relative="true" attribute not being respected during instrumentation.[html reports] percentage bar doesn't render correctly with some localised percent values • [CCD-363] .support <sourcepath> again in <clover-report>. 1.report how many test methods were detected • [CCD-346] . All rights reserved.

• [CCD-253] .Annotation definition containing superfluous semi causes parse error 1.put inline help into html reports • [CCD-340] .3. .Clover's database fragments excessively over time.5 hexadecimal floats • [CCD-350] . What's New in Clover 2 Page 6 Copyright © 2002-2004 Cenqua Pty Ltd.improve java source rendering styles Bugs • [CCD-250] .Clover 2.historical reports don't need initstring set • [CCD-265] .should be able to link historical & current html report to each other • [CCD-89] .jdk1. leading to larger in-memory coverage arrays • [CCD-233] .respect deprecated annotation • [CCD-72] .x.add cyclomatic complexity measurement to Clover • [CCD-258] .need a runtime property to disable registration of shutdownhook • [CCD-288] .Allow secondary sort order to be specified • [CCD-180] . 2006 This is the first release of Clover 2.New <clover-html-report/> and <clover-pdf-report/> tasks Improvements • [CCD-55] .show coverage by testcase • [CCD-64] .need an aggregate package report.clover breaks on JDK1.0a5 User Manual 6 December.provide runtime logging controls • [CCD-223] .double counting try statements • [CCD-308] .allow recording-time control of which threadgroup Clover-created threads get created in. • [CCD-327] .5 with -Xlint and -Werror reports clover's fallthrough switch instr as error • [CCD-257] .movers classes should be linked to current report if possible.html reports should be client-side sortable • [CCD-269] .clover-check should support package globs • [CCD-254] .should be able to choose which columns to show in HTML reports • [CCD-158] .x feature requests and bug reports: New Features • [CCD-7] .report coverage by method • [CCD-95] .new column Formats "wideBar" • [CCD-276] . • [CCD-267] . This initial release addresses the following Clover 1.historical reports .javadoc tags not rendered correctly • [CCD-311] . All rights reserved.

All classes in your project are displayed on a single page and highlighted to inform you about project risks or potential coverage improvements. • Streamlined Ant integration and simplified Ant tasks The new <clover-html-report> and <clover-pdf-report> tasks provide sensible defaults to the existing clover-report task. • Linked.3. New Feature Highlights • Coverage By Testcase Each source file displays which tests hit which line of code. Read More. the tests that hit that line are displayed. Alternatively. Read More. the lines that the test case executed get highlighted. Source code is cross-referenced for easy traversal between classes and up and down package hierarchies. cross-referenced Reports Reports produced with the same task are automatically linked to each other. . • Coverage Cloud Reports These give an instant overview on specific aspects of your project. The Clover initstring is now optional. • Inline Help Help tooltips can be turned on for each page to describe metrics and controls. If not specified. Read More.Clover 2.0a5 User Manual Clover 2 is a major rewrite that adds new and unique functionality to help your team get the most out of your testing. Page 7 Copyright © 2002-2004 Cenqua Pty Ltd.1. • Sortable Columns All tables in Clover 2 are client side sortable. by clicking on a source line. 1. Clover2 will automatically create and manage the coverage database for you. • Integrated Test Results Test results (pass/fail/error) are now optionally integrated with the coverage report. Error traces are hyperlinked to the relevant source line. By selecting a test case. • Method-level Metrics Metrics at the method level are displayed both inline and in each class summary section. All rights reserved.

Do you know. You can be confident that when you go into production there will be minimal problems because you know the code not only passes its tests but that it is well tested. it may not meet the same testing standards you put in place when the project was first released.1. . Coverage measurement also helps to avoid test entropy.1. Measuring code coverage can keep your testing up to the standards you require.1. If you follow defensive programming principles where failure conditions are often checked at many levels in your software. Coverage generally follows an 80-20 rule. Code Coverage 2.Clover 2. Code Coverage 2. All rights reserved. a code coverage system collects information about the running program and then combines that with source information to generate a report on test suite's code coverage. some code can be very difficult to reach with practical levels of testing. how well your unit tests actually test your code? How many tests are enough? Do you need more tests? These are the questions code coverage measurement seeks to answer. Increasing coverage values becomes difficult with new tests delivering less and less incrementally. As your code goes through multiple release cycles. Page 8 Copyright © 2002-2004 Cenqua Pty Ltd. In summary. This loop will continue until coverage meets some specified target. code coverage highlights aspects of the code which may not be adequately tested and which require additional testing. Why Measure Code Coverage? It is well understood that unit testing improves the quality and predictability of your software releases. As new code is added. Code coverage is part of a feedback loop in the development process. In general. 2. Coverage measurement is not a replacement for good code review and good programming practices. there can be a tendency for unit tests to atrophy. we measure code coverage for the following reasons: • To know how well our tests actually test our code • To know whether we have enough testing in place • To maintain the test quality over the lifecycle of a project Code coverage is not a panacea. What is Code Coverage? Code coverage measurement simply determines those statements in a body of code have been executed through a test run and those which have not. As tests are developed.2. however.1.0a5 User Manual 2.

.1. 2. code coverage systems collect information about which statements have been executed.0a5 User Manual In general you should adopt a sensible coverage target and aim for even coverage across all of the modules that make up your code. 2. coverage approaches vary on what forms of coverage information they collect.3. How Code Coverage Works There are many approaches to code coverage measurement. because although it requires developers to perform an instrumented build. Clover's Ant and Maven integrations allow coverage measurement to be performed in Automated Build and Continuous Integration systems and reports generated to be shared by the team.4. Here the compiled class files are instrumented by adding new bytecodes and a new instrumented class generated.Clover 2. Code Coverage with Clover Clover is designed to measure code coverage in a way that fits seamlessly with your current development environment and practices. This information is then used as the basis of reports. whatever they may be. There are many forms of coverage beyond basic statement coverage including conditional coverage. Types of Coverage measured Clover measures three basic types of coverage analysis: Page 9 Copyright © 2002-2004 Cenqua Pty Ltd. source code instrumentation produces the most accurate coverage measurement for the least runtime performance overhead. As the code under test executes. Relying on a single overall coverage figure can hide large gaps in coverage.1. method entry and path coverage. All rights reserved. which may be used in combination: Source Code Instrumentation This approach adds instrumentation statements to the source code and compiles the code with the normal compile tool chain to produce an instrumented assembly. In addition to these basic mechanisms. This approach collects information from the runtime environment as the code executes to determine coverage information Intermediate code Instrumentation Runtime Information collection Clover uses source code instrumentation. Broadly there are three approaches. Clover's IDE Plugins provide developers with a way to quickly measure code coverage without having to leave the IDE.

package and for the project as a whole.total number of methods Page 10 Copyright © 2002-2004 Cenqua Pty Ltd.total number of statements M . . The Total Coverage Percentage (TPC) is calculated as follows: TPC = (BT + BF + SC + MC)/(2*B + S + M) where BT BF SC MC branches that evaluated to "true" at least once branches that evaluated to "false" at least once statements covered methods entered B . Method Clover uses these measurements to produce a Total Coverage Percentage for each class. All rights reserved. Method coverage measures if a method was entered at all during execution.0a5 User Manual Statement Branch Statement coverage measures whether each statement is executed Branch coverage (sometimes called Decision Coverage) measures which possible branches in flow control structures are followed. file.Clover 2.total number of branches S . The Total Coverage Percentage allows entities to be ranked in reports. Clover does this by recording if the boolean expression in the control structure evaluated to both true and false during execution.

x or greater) unzip the Clover distribution into a directory. Add Clover targets Edit build.jar"/> <taskdef resource="cloverlib.1.6.Clover 2.0a5 User Manual 3. (also see Installing your license file) 3. add one or more targets to run clover reports: For html reporting. Page 11 Copyright © 2002-2004 Cenqua Pty Ltd. use (change the outdir to a directory path where Clover should put the generated html and the testresultsdir to the location where your test results (xml) have been written): <target name="clover. All rights reserved.1.clover"> <clover-setup/> </target> 3.1. add a target to switch on Clover: <target name="with. Clover with Ant 3. Quick Start Guide for Ant This section shows you how to quickly get Clover integrated into your build.license file in CLOVER_HOME/lib. This directory will be referred to as CLOVER_HOME in this guide. add the Clover Ant tasks to your project: <property name="clover.1. Clover instrumentation and reporting are highly configurable so later sections of this manual will detail available configuration options and typical usage scenarios. Follow these simple steps to integrate Clover with your build: 3. place your clover.2.jar" location="CLOVER_HOME/lib/clover.xml" classpath="${clover.jar}"/> 2.xml for your project: 1.html"> <clover-html-report outdir="clover_html" testresultsdir="build/test/results" title="My Project"/> </target> Note: Specify the testresultsdir to have your test results integrated with your Clover coverage report. Install Clover ensure you are using a recent version of Ant (v1. .

Clover 2.0a5 User Manual

- OR - for pdf reporting, use (change the outfile to a file where Clover should write the pdf file):
<target name="clover.pdf"> <clover-pdf-report outfile="coverage.pdf"/> </target>

- OR - for xml reporting, use (change the outfile to a file where Clover should write the xml file):
<target name="clover.xml"> <clover-report> <current outfile="coverage.xml"> <format type="xml"/> </current> </clover-report> </target>

- OR - for simple emacs-style reporting to the console, try:
<target name="clover.log"> <clover-log/> </target>

4. Add clover.jar to the runtime classpath for your tests. How you do this depends on how you run your tests. For tests executed via the <junit> task, add a classpath element:
<junit ...> ... <classpath> <pathelement path="${clover.jar}"/> </classpath> <formatter type="xml"/> </junit>

3.1.3. Compile and run with Clover Now you can build your project with Clover turned on by adding the "with.clover" target to the list of targets to execute. For example (if your compile target is named 'build' and your unit test target is named 'test'):
ant with.clover build test

3.1.4. Generate a Coverage Report To generate a Clover coverage report:
ant clover.html (or clover.xml, clover.view etc)

Page 12
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

Clover 2.0a5 User Manual

3.2. Upgrading to Clover 2
We've taken care to make the upgrade to Clover 2 straightforward. To upgrade to Clover 2, follow these simple steps 1. Replace 1.x clover.jar with the 2.x clover.jar You can do this by simply copying the new jar over the top of the old one. 2. Obtain and install a Clover 2.x license Output similar to the following will appear when Clover is run:
[clover] Clover Version 2.X, built on ... [clover] Loaded from: c:/ant/lib/clover.jar

3. Configure the Test Results Directory (optional) You can now optionally configure the Clover report tasks to include test result information in the generated report. If you are using the <clover-report> task then add a <testresults/> fileset element. If you use the <clover-html-report> task, provide a testresultsdir attribute. This enables Clover 2 to display your Test Results and your Test Coverage in the same report. Please read Test Result Integration for more information. 4. Delete any existing Coverage database. The Clover database is created at the location specified in the initstring attribute of <clover-setup>
Note:
In Clover 2, the initstring parameter is now optional. We recommend leaving it unspecified unless you want to explicitly control where Clover writes it's database file.

Please also read the Best Practices For Clover Integration.

3.3. Install Options
3.3.1. Installing Clover
Note:
Clover 2.x requires Ant 1.6.x or above.

Adding Clover to your build is done by adding the following to your buildfile (e.g. build.xml) :

Page 13
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

Clover 2.0a5 User Manual

<taskdef resource="cloverlib.xml" classpath="/path/to/clover.jar">

Checking if Clover is available for the build In some cases you may want to check if Clover is available before executing Clover-related targets. For example, you may need to ship the build file to others who may not have Clover installed. To check Clover's availability you can make use of the standard Ant <available> task:
<target name="-check.clover"> <available property="clover.installed" classname="com.cenqua.clover.CloverInstr" /> </target>

<target name="guard.noclover" depends="-check.clover" unless="clover.installed"> <fail message="The target you are attempting to run requires Clover, which doesn't a </target> <target name="with.clover" depends="guard.noclover"> ...

Troubleshooting • To enable logging of the Clover installation, set the environment variable ANT_OPTS to '-Dclover.debug=true' • Run ant with the -debug and -verbose options • Certain environments may require the clover.jar to be placed directly on Ant's Classpath. Details are outlined here • Run the <clover-env/> task to display Ant and Clover runtime information 3.3.2. Adding Clover to Ant's Classpath
Note:
You only need to add Clover to Ant's Classpath in certain environments. The normal method to install Clover is outlined here.

Below are three options for adding the clover.jar to your Ant classpath directly. Installing Clover locally for a single user 1. create a directory ${user.home}/.ant/lib 2. copy clover.jar to ${user.home}/.ant/lib
Note:
The location of ${user.home} depends on your JVM and platform. On Unix systems ${user.home} usually maps to the

Page 14
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

All rights reserved.jar to the CLASSPATH system environment variable before running Ant. please consult your Operating System documentation. because a Coverage run can result in many files being written to the database. Installing Clover at an arbitary location You can install and use Clover at an arbitary location and then refer to it using the -lib command line option with Ant: ant -lib CLOVER_HOME/lib buildWithClover (Where CLOVER_HOME is the directory where Clover was installed). If not supplied. see http://www. If left to the default setting. Best Practices for Clover Integration This section describes some recommended practices when integrating Clover into your Ant build. Clover will automatically create a special directory for the Clover coverage database. Installing Clover globally into Ant Copy clover. 3. For information about setting this variable. use Page 15 Copyright © 2002-2004 Cenqua Pty Ltd.Clover 2. and build files become more portable. you can add CLOVER_HOME/clover.com/pub/a/onjava/2003/12/17/ant_bestpractices. Note: If you want to specify the initstring explicity. There are several advantages in letting Clover use the default location. Clover tasks can find the database more easily.onjava. Alternatively. Use the <clover-clean> task Once you've generated the reports or history points you require from a Coverage run.0a5 User Manual user's home directory. For a great list of general Ant best practices. Clover 2 makes the initstring attribute optional.jar into ANT_HOME/lib (Since all jars in this directory are automatically added to Ant's classpath by the scripts that start Ant). it is strongly recommended that you give Clover it's own direct directory. On Windows systems ${user.x. .html 1. Let Clover automatically choose the database location In Clover 1. the Clover database needed to be specified. 2. Check your JVM documentation for more details.4.home} will map to something like C:\Documents and Settings\username\. there is no need to have Clover reporting targets depend on the the Clover setup target. via the initstring attribute on the <clover-setup> task.

3. 5. If you don't set it. You should always strive to use this mechanism over the more "procedural" style of explicitly calling targets.BAD --> <target name="all"> <antcall target="clean"> <antcall target="compile"> <antcall target="dist"> <antcall target="test"> </target> it is much better to use something like: <!-. Set the source attribute on the <javac> task Setting the source attribute increases the portability of your build by explicitly defining the language level of the project. Using Clover Interactively In this scenario.0a5 User Manual <clover-clean> to delete the database so that it will be freshly created for the next build. If using the <junit> task. consider using fork="true" forkmode="once" Setting these attributes means that your JUnit tests will run in a single. because it can be difficult to trace which properties and references are valid for a given target. dist. All rights reserved.GOOD --> <target name="all" depends="clean. . you miss out on Ant's powerful dependency management where up-to-date targets are skipped. Avoid setting the compiler or executable attributes on the <javac> task Setting either of these attributes makes your build less portable. and means that no special flushing is required to have Clover coverage data written to disk when the tests end. 3.5. You also introduce significant memory overhead (particularly if fork="true" is set). It may also prevent Clover from installing correctly in your build.1.5. test"/> 6. 4. compile. This isolates the unit tests from the Ant JVM. Instead of: <!-. separate JVM. a developer is responsible for obtaining a certain level of code coverage on her code before it is accepted into the base. Usage Scenarios 3. This is easily achieved by adding the <clover-clean> task to any existing clean target. the language level is determined by whatever underlying compiler is found by Ant. Excessive use of <antcall> can also make a build file less readable.Clover 2. Use Target dependencies in preference to <ant> and <antcall> Ant's target dependencies are an efficient way to manage build dependencies. The typical cycle the developer follows is something like: Page 16 Copyright © 2002-2004 Cenqua Pty Ltd. By explicitly calling Ant tasks.

run tests 3.0a5 User Manual 1. Clover provides the following features to support this development pattern: • Measuring coverage on a subset of source files • Viewing source-level code coverage quickly • Viewing summary coverage results quickly • Incrementally building coverage results Measuring coverage on a subset of source files The <clover-setup> task takes an optional nested fileset element that tells Clover which files should be included/excluded in coverage analysis: <clover-setup> <files includes="**/plugins/cruncher/**.Clover 2. The <clover-log> task provides quick reporting to the console: <clover-log/> The output format from the clover-log task uses the file:line:column format that many IDEs can parse. Viewing summary coverage results quickly Page 17 Copyright © 2002-2004 Cenqua Pty Ltd.includes" value="**"/> <clover-setup> <files includes="${coverage.java Viewing source-level code coverage quickly Clover provides two ways of quickly viewing coverage results.includes=**/foo/*. . All rights reserved. write code/tests 2. **/plugins/muncher/**"/> </clover-setup> The includes could be set using an Ant property so that individual developers can specify includes on the command line: <property name="coverage. inspect test results and code coverage This process is repeated until all tests pass and code coverage of the tests meets a certain level.includes}"/> </clover-setup> Developers can then use a command line like: ant build -Dcoverage.

the project is checked out. then use the <clover-report> task.see Using Spans.0a5 User Manual The <clover-log> task provides an option that will print a summary of coverage results to the console: <clover-log level="summary"/> Incrementally building coverage results When iteratively improving coverage on a subset of your project.2.Clover 2.5. If you require more control over your report formatting and structure. built and tested at regular intervals. The <clover-html-report> task generates source-level html coverage reports that can be published for viewing by the whole team: <target name="clover. Centipede and CruiseControl. To include results gathered over the last hour use: <clover-log span="1h"/> 3. This attribute can be used to tell Clover how far back in time to include coverage results (measured from the time of the last Clover build). Clover supports this scenario with the following features: • Detailed coverage reports for the whole team • Executive summary coverage reports • Historical coverage and project metrics reporting • Coverage criteria checking and triggers Detailed coverage reports for the whole team Note: The <clover-html-report> and the <clover-pdf-report> tasks used here are simplified versions of the <clover-report> task.report" depends="with.clover"> <clover-html-report outdir="clover_html"/> </target> Executive summary coverage reports The <clover-pdf-report> task can generate summary reports in PDF suitable for email or Page 18 Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved. Using Clover in Automated Builds In this scenario. Some third party tools that support this type of build are AntHill. Clover supports this with the span attribute which works on current reports . usually by an automated process. you may want to include coverage data from several iterations in coverage results. .

<target name="clover. All rights reserved. Ant Task Reference Page 19 Copyright © 2002-2004 Cenqua Pty Ltd.summary" depends="with. if project coverage is not 80%. an executive summary coverage report is generated and mailed to the team: <target name="coverageAlert" depends="coverage.pdf"/> <mail from="nightlybuild@somewhere.6.0a5 User Manual audit purposes.check" depends="with.pdf"/> </target> Historical coverage and project metrics reporting Clover can generate a historical snapshot of coverage and other metrics for your project using the <clover-historypoint> task. If coverage does not meet the criteria.generate a historypoint for the current coverage --> <clover-historypoint historyDir="clover_hist"/> <!-. the build can be made to fail or an arbitary activity can be triggered.pdf"/> </target> <target name="coverage.Clover 2.generate a report with both current and historical data --> <clover-html-report outdir="clover_html" historyDir="clover_hist"/> </target> Coverage criteria checking and triggers The <clover-check> task can be used to monitor coverage criteria.report" depends="with.clover"> <!-.not" tolist="team@somewhere. . In the example below. Historical data can then be colated into a historical report using the <clover-report> task: <target name="clover.not" subject="coverage criteria not met" message="${coverage_check_failure}" files="coverage.check" if="coverage_check_failure"> <clover-pdf-report outfile="coverage.clover"> <clover-check target="80%" failureProperty="coverage_check_failure"/> </target> 3.clover"> <clover-pdf-report outfile="coverage.

for cases where the normal <clover-setup> integration approach can't be used.jar"/> Make sure you change the above "/path/to/clover.6.jar.jar" to point directly to your clover. Allows manual instrumentation of source files.0a5 User Manual 3.2.Clover 2. Tests project/package code coverage against criteria. <clover-report> <clover-check> <clover-log> <clover-instr> <clover-historypoint> <clover-clean> <clover-html-report> <clover-pdf-report> 3. This means that Clover will be invoked whenever the Ant <javac> is used.xml' antlib by adding the following line to your build file: <taskdef resource="cloverlib. All rights reserved. Generates a HTML report with default settings. resulting in instrumented compilation. Generates a PDF report with default settings. optionally failing the build if the criteria are not met. Records a coverage history point for use in historical coverage reports. To make these tasks available in your project build file.1. Produces coverage reports in different formats.6. Reports coverage results to the console at various levels. Clover Ant Tasks Installing the Ant Tasks Clover provides a set of Ant tasks to make project integration easy.xml" classpath="/path/to/clover. The tasks <clover-setup> Installs Clover as the Ant build. . you need to: • load the 'cloverlib.compiler. Delete the coverage database and/or associated coverage records. <clover-setup> Page 20 Copyright © 2002-2004 Cenqua Pty Ltd. see also Ant Installation Options. For further options.

defaults to true will instrument code during code compilation.0a5 User Manual Description The <clover-setup> task initialises Clover for use with your project.g.db If not specified it defaults to . If you wish to specify an alternative compiler.compiler property. Clover's operation was managed by setting various Ant properties. All rights reserved. . It takes the same values as the standard Ant build. Clover No hands off compilation to the standard Ant compiler adapter (or the compiler specified by the build. The <clover-setup> task simplifies this procedure. defaults to false controls whether the instrumented source will be retained after compilation. A boolean attribute which No. This attribute specifies the adapter to use.compiler property or use this attribute.Clover 2. enabled clovercompiler preserve Page 21 Copyright © 2002-2004 Cenqua Pty Ltd. relative to the project's base directory. you can either set the build. Typically this is a relative or absolute file reference. This controls whether Clover No.clover. ${basedir}/build/clover.0. This attribute provides a convenient control point to enable or disable Clover from the command line After instrumentation. Parameters Attribute initstring Description Required The Clover initString describes No the location of the clover coverage database. e.compiler Ant property). In Clover 1.

For more information. interval. When the flushpolicy is set to No interval or threaded this tmpdir flushpolicy flushinterval Page 22 Copyright © 2002-2004 Cenqua Pty Ltd. or threaded. directed Coverage data is flushed at JVM shutdown. as well as periodically at a rate based on the value of flushinterval. interval Coverage data is flushed as for directed. This attribute controls how No. This is a "passive" mode in that flushing potentially occurs as long as instrumented code is being executed. Note that setting the source attribute on the <javac> target will override this setting. This is an "active" mode in that flushing occurs on a separate thread and is not dependent on the execution of instrumented code. and after an inline flush directive. threaded Coverage data is flushed as for directed. .Clover 2.0a5 User Manual source The default source level to No process source files at. defaults to directed Clover flushes coverage data during a test run. see Flush Policies. All rights reserved. Valid values are directed. The directory into which Clover No will write an instrumented copy of the source code. as well as periodically at a maximum rate based on the value of flushinterval.

<fileset> As of Clover 1. These give greater flexibility in specifying which source files are to be instrumented by Clover.0a5 User Manual value is the minimum period between flush operations (in milliseconds) relative This controls whether the No. All rights reserved.Clover 2. This means that builds that use the Clover 1. Nested Elements of <clover-setup> <files> An Ant patternset element which controls which files are included or excluded from Clover instrumentation. defaults to false initstring parameter is treated as a relative path or not.2. Note: Do not set the "compiler" attribute on the <javac/> task as this overrides the Clover compiler setup by <clover-setup>. . It is important to note that the Clover compiler adapter still picks up its settings from the set of Clover Ant properties.0 property set will continue to operate as expected. Filesets also allow much greater flexibility in specifying which files to instrument by facilitating the use of Ant's fileset selectors. See Using Contexts for more information. Use the "clovercompiler" attribute instead. This is useful when you have more than one source base and only want some of those source bases to be instrumented. This can be difficult to setup with patterns. <methodContext> Specifies a method Context definition. <clover-setup> also supports multiple Ant <filesets>. The <clover-setup> task provides a convenience method to set these properties. Parameters Page 23 Copyright © 2002-2004 Cenqua Pty Ltd. Note: The <useclass> sub-element has been deprecated and has no effect.

Must Yes be unique.clover relative directory. Page 24 Copyright © 2002-2004 Cenqua Pty Ltd. This regexp should match statements you wish to include in this context. whitespace is normalised and comments are ignored. In this case the clover coverage database is located in the . Must Yes be unique. Parameters Attribute name Description Required The name for this context. All rights reserved. See Using Contexts for more information. Note that when method signatures are tested against this regexp. Note that when statements are tested against this regexp.Clover 2. whitespace is normalised and comments are ignored. regexp Examples <clover-setup/> This example is the minimal setup to use clover. This regexp should match the method signatures of methods you wish to include in this context.0a5 User Manual Attribute name Description Required The name for this context. . and not be one of the reserved context names (See Using Contexts) A Perl 5 Regexp that defines yes the context. regexp <statementContext> Specifies a statement Context definition. and not be one of the reserved context names (See Using Contexts) A Perl 5 Regexp that defines yes the context.

This is not always practical. via a shutdown hook. Note that the fileset can also be referenced using a refid attribute. Also the instrumentation will exclude all java source files in trees named "optional". To override this location use the initstring attribute. you can configure Clover to use "interval" flushing. Page 25 Copyright © 2002-2004 Cenqua Pty Ltd.java"/> </files> </clover-setup> This example shows the use of a property. Interval Flushing By default Clover will write coverage data to disk when the hosting JVM exits. Clover writes its internal database to the . By default. The attribute accepts the same values "compiler" attribute of the Ant Javac Task. "enable". All rights reserved.0a5 User Manual <clover-setup enabled="${enable}" <files> <exclude name="**/optional/**/*. <clover-setup clovercompiler="jikes"/> This example will pass compilation to the "jikes" compiler once instrumentation is complete. <clover-setup enabled="${coverage.Clover 2. In this situation. Please refer to the Ant manual for information on these selectors. Specifying a delegate compiler Clover provides the optional "clovercompiler" attribute to allow specification of the java compiler to delegate to once instrumentation is completed.clover directory relative to the project's basedir. Specifying the location of the Clover Database. where coverage data is written out periodically during execution: <clover-setup flushpolicy="interval" flushinterval="5000"/> The "flushinterval" defines in milliseconds the minimum interval between coverage data writes. particularly when the application you are testing runs in an Application Server. to control whether Clover instrumentation is enabled. Ant's filesets supports a number of these selectors.enable}" <fileset dir="src/main"> <contains text="Joe Bloggs"/> </fileset> </clover-setup> This example instruments all source files in the src/main directory tree that contain the string "Joe Bloggs". .

6. failure to generate a No. use the <clover-html-report> or <clover-pdf-report> tasks.db" This example will use clover-db/coverage. will look in the default location (${basedir}/. The basic nesting of elements within the <clover-report> task is as follows: <clover-report> <current> <fileset/> <sourcepath/> <format/> <columns/> <testresults/> <testsources/> </current> <historical> <format/> <overview/> <coverage/> <metrics/> <movers/> </historical> </clover-report> Note: If you do not require such fine grained control over your clover reports. . Clover database. <clover-report> Description Generates current and historical reports in multiple formats. If true. failOnError Page 26 Copyright © 2002-2004 Cenqua Pty Ltd.3. All rights reserved. NB.clover).0a5 User Manual <clover-setup initstring="clover-db/coverage. If not specified here. report causes a build failure. 3. If you have specified an initstring on the <clover-setup> task you must ensure <clover-setup> is called prior the execution of this task. the directory clover-db should exist before running this task. Parameters Attribute initstring Description Required The initstring of the coverage No. defaults to "true".Clover 2.db as the location for the clover DB.

All rights reserved. XML) or a directory (HTML). Each report will contain links to the other reports. Parameters Attribute title titleAnchor Description Specifies a title for the report. this href. You can generate multiple reports by specifying more than one of these inside a <clover-report> element. it is created. Specifies whether to generate a No. The outfile to write output to. default is to not render the be rendered as a hyperlink to report title as a hyperlink. Depending on the specified format. default is "_top" title is to be rendered as a hyperlink (see titleAnchor above). Defaults to "false". . Valid formats are XML. HTML. <current> Generates a current coverage report. titleTarget alwaysReport outfile summary Page 27 Copyright © 2002-2004 Cenqua Pty Ltd. Specify the report format using a nested Format element. See Current Report examples. defaults to the project in the Ant build file. HTML format only If set to true. If Yes it does not exist. and PDF although not all configurations support all formats.Clover 2. the report title will No. Required No if specified. Nested elements of <clover-report> These elements represent the actual reports to be generated. Specifies the href target if the No. See example. The default format is PDF if summary="true" or XML if not. This is used name of the Ant build file. this either represents a regular file (PDF. a report will be No. for display purposes only.0a5 User Manual projectName Overrides the project name set No. defaults to "false" generated even in the absence of coverage data. summary report or detailed report.

Clover 2.0a5 User Manual

package span

Restricts the report particular package.

to

a No

Specifies how far back in time No; Defaults to "0s". to include coverage recordings from since the last Clover build. See Using Spans. Specifies the maximum number No; unlimited if not specified or of tests (ranked by coverage -1 contribution) to display on a source file report page. This parameter can be used to reduce the size of reports for projects with very large numbers of tests. Specifies the start page to use. No; defaults to "dashboard". This can be one of the predefined pages: dashboard, overview, aggregate, testresults, quickwins, projectrisks or an arbitrary URL.

maxTestsPerFile

homepage

<historical> Generates a historical coverage report. Specify the report format using a nested Format element. Valid formats are HTML or PDF. The default format is PDF. Contents of the historical report are optionally controlled by nested elements. See Nested elements of Historical. Parameters
Attribute title titleAnchor Description Specifies a title for the report. Required No

if specified, the report title will No; default is to not render the be rendered as a hyperlink to report title as a hyperlink. this href. Specifies the href target if the No; default is "_top" title is to be rendered as a hyperlink (see titleAnchor above). HTML format only

titleTarget

Page 28
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

Clover 2.0a5 User Manual

outfile

The outfile to write output to. If Yes it does not exist, it is created. Depending on the specified format, this either represents a regular file (PDF) or a directory (HTML). The directory containing Clover Yes historical data as produced by the <clover-historypoint> task. Restricts the report particular package. to a No

historyDir

package from

Specifies the date before which No data points will be ignored. The date must be specified either using the default java.text.SimpleDateFormat for your locale or using the pattern defined in the "dateFormat" attribute. Specifies the date after which No data points will be ignored. The date must be specified either using the default java.text.SimpleDateFormat for your locale or using the pattern defined in the "dateFormat" attribute. Specifies a date format string for parsing the "from" and "to" fields. The string must contain a valid java.text.SimpleDateFormat pattern. No; default set to java.text.SimpleDateFormat using the default pattern and date format symbols for the default locale.

to

dateFormat

Nested elements of<current> <fileset> <current> supports nested filesets which control which source files are to be included in a report. Only classes which are from the source files in the fileset are included in the report. This allows reports to focus on certain packages or particular classes. By using Ant's fileset

Page 29
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

Clover 2.0a5 User Manual

selectors, more complicated selections are possible, such as the files which have recently changed, or files written by a particular author. <sourcepath> Specifies a Ant path that Clover should use when looking for source files. Nested elements of <historical> These elements represent individual sections of the historical report. If you do not specify any of these elements, all the sections will be included in the report. If you specify more one or more of these elements, only the specified sections will be included. You may specify multiple <overview> and <coverage> elements in the historical report. These may have different properties and include different elements. The charts will appear in the report in the same order they appear in the <historical> element. The <movers> element always appears at the end of the report following these charts regardless of its location in the <historical> element. <historical> element. <overview> Specifies a section that provides summary of the total percentage coverage at the last history point. This element does not support any attributes. <coverage> Specifies a chart showing percentage coverage over time. Parameters
Attribute include Description Required that

A comma or space separated No; the default is list of coverage metrics to everything is included include in the chart. Valid values are: branches, statements, methods, total

<metrics> Specifies a chart showing other metrics over time.

Page 30
Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved.

The range is automatically adjusted to the closest smaller interval available. statements. defaults to loc. logscale <movers> Specifies a table that shows those classes that have a coverage delta higher than a specified threshold over a specified time preiod. Parameters Attribute threshold Description Required The absolute point change in No. defaults to 1% percent coverage that class must have changed by for inclusion. packages Specifies that a log scale be No.g "10%". The maximum number of No. methods. The defaults to 5 classes to show. classes. ncloc.0a5 User Manual Parameters Attribute include Description Required A comma or space separated No. Valid values are: loc. The time interval over which No. The default is to take the the delta should be calculated delta of the last two history (from the last history point). range interval The <format> Element Page 31 Copyright © 2002-2004 Cenqua Pty Ltd. e. classes chart. files.Clover 2. list of metrics to include in the methods. This can be useful if you are including. default is "true" used on the Range Axis. If the value is 5. say LOC and packages in the same chart. ncloc. points Uses the Interval format. All rights reserved. . then a maximum of 5 "gainers" and 5 "losers" will be shown.

ascending ElementsCoveredDesc Total elements covered. ascending ElementsUncoveredDesc orderBy Page 32 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual Specifies the output format and various options controlling the rendering of a report. the id of this format element. descending ElementsUncoveredAsc Total elements uncovered. Valid values are pdf. Note that not all reports support all formats. defaults to PcCoveredAsc tables. unless refid is set report in. xml. See Sharing Report Formats. the id of another format No element that will be used for this report.Clover 2. This will make HTML reports smaller (with no syntax highlighting) and make PDF reports suitable for printing on a non-colour printer. No refid id bw Specify that the report should No. Specify how to order coverage No. All rights reserved. PcCoveredDesc Percent total coverage. PcCoveredAsc Percent total coverage. Valid values are: Alpha Alpabetical. ascending. This attribute has no effect on XML format. . defaults to "false" be black and white. html. descending. Parameters Attribute type Description Required The output format to render the Yes. ElementsCoveredAsc Total elements covered.

A value < 0 indicates no limit. methods. files and No. include source-level No. defaults to "true" coverage information in the report. (Source level reports only) The No. Specific columns are defined as sub-elements to this one. defaults to 4 number of space chars to replace TAB characters with.Clover 2. Valid values are A4. defaults to "false" packages that do not contain any executable code (i. If not specified. or branches) are included in reports. insert No. See example Each column element takes an optional format attribute which determines how the column's value is rendered. classes. statements. LETTER If true. See Using Contexts. defaults to "A4" size to use. comma or space separated list No of contexts to exclude when generating coverage reports. The maximum length in chars No. Longer names will be truncated. (PDF only) Specify the page No. . The format attribute may be one of the following: • raw . defaults to "false" nocache directives in html output. Always used for total columns Page 33 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual Total elements uncovered. These are normally not shown.e. if true. default columns will be output. All rights reserved. defaults to no limit of package or classnames in the report. descending noCache (HTML only) if true.the actual value. srcLevel filter pageSize showEmpty tabWidth maxNameLength The <columns> Element Specifies the data columns to be included on summary pages.

shortbar coveredElements totalBranches coveredBranches totalStatements coveredStatements totalMethods coveredMethods totalChildren The total number of statements raw in the project.%.shortbar The total number of methods in raw the project. .bar. of covered raw.%. Package. Method. of covered raw. complexity Page 34 Copyright © 2002-2004 Cenqua Pty Ltd.bar. The total number of branches raw in the project.same as bar above. File. The amount statements.render a bar chart (200px wide) showing the coverage percentage • shortbar . If the value for the column is outside the threshold the value will be highlighted. of covered raw. The total number of covered raw.shortbar elements (branches + statements) in the project. Statement Cyclomatic Complexity is a raw measure of the number of paths in your code.shortbar The number of lower order raw elements. The amount methods. Column Names Column totalPercentageCovered totalElements Description The total coverage.%.0a5 User Manual • bar .Clover 2.shortbar The total number of elements raw (branches + statements) in the project.bar.bar. All rights reserved. but only 40px wide • % . All column elements also take max and/or min threshold attributes. The amount branches.The coverage percentage value bar and % are not valid formats for total columns. The order of elements is: Project.bar.%. Valid Format Attributes raw. Class.%.

The average number statements per method. The average number of classes raw per file. All rights reserved. If the value is greater than this it will be highlighted.Clover 2. The total number of lines. this may be one of raw. The average complexity per raw statement. min max Page 35 Copyright © 2002-2004 Cenqua Pty Ltd. The total number non-comment lines. Sets a maximum threshold on No the value of the column. project or file. Depending on the column. The average number methods per class. raw of raw lineCount ncLineCount Column Attributes Each of the above column elements can take the following attributes: Attribute format Description Required Determines how the value is No rendered. bar. % or shortbar. . The total number of classes raw below the package. of raw of raw The total number of files below raw the package or project. Sets a minimum threshold on No the value of the column.0a5 User Manual avgMethodComplexity complexityDensity avgClassesPerFile avgMethodsPerClass avgStatementsPerMethod totalFiles totalClasses The average number of paths raw per method. If the value is less than this it will be highlighted.

Note. All rights reserved. <clover-report> <current outfile="current. The <testsources> fileset element <testsources> is an Ant fileset that can be used to distinguish test source code from application source code. The results should be generated using the Ant junit task with an xml formatter.xml"/> <testsources dir="src/test" includes="**/*. <clover-report> <current outfile="clover_html" title="My Project" summary="true"> <format type="html"/> <testresults dir="test/results" includes="TEST*. Clover's default test detection algorithm will be used to distinguish test sources.java"/> </current> </clover-report> Generates a detailed coverage report in HTML with output ordered by total number of covered elements. <clover-report> <current outfile="clover_html" title="Util Coverage"> <format type="html" orderBy="ElementsCoveredAsc"/> <testresults dir="test/results" includes="TEST*. Examples of Current Report Configurations <clover-report> <current outfile="current.xml"/> </current> </clover-report> Generates a summary report. . the "outfile" argument requires a directory instead of a filename. rather than percentage coverage.xml"/> </clover-report> Generates an XML report of the current coverage.pdf"> <format type="pdf"/> </current> </clover-report> Generates a PDF report of the current coverage.0a5 User Manual The <testresults> fileset element <testresults> is an Ant fileset that Clover uses to integrate the results of your unit tests into the report. in HTML with a custom title. If omitted. All files included in the fileset will be displayed in the separate 'Test' node of the coverage tree.Clover 2. All source files under src/test will be Page 36 Copyright © 2002-2004 Cenqua Pty Ltd.

It is prudent. Clover will search for source files in the directory /some/other/location. You could use this if you have changed the exclude or include definitions in the <clover-setup> task and you have not removed the coverage database.limit" pattern="MM/dd/yyyy hh:mm aa" offset="-1" unit="month"/> </tstamp> <clover-report> <current outfile="report-current" title="Coverage since ${report. <tstamp> <format property="report. from being included in the report.limit}" when="after"/> </fileset> <format srclevel="true" type="html"/> <testresults dir="test/results" includes="TEST*. Replacing the <date> selector with <contains text="@author John Doe"/> would generate a coverage report for all code where John Doe is the author.limit}"> <fileset dir="src/main"> <date datetime="${report. .xml"/> </current> </clover-report> Generates a sourcelevel report in HTML. currently in the database but now excluded. All rights reserved. <clover-report> <current outfile="report-current" title="Coverage"> <fileset dir="src"> <patternset refid="clover.0a5 User Manual in the separate 'Test' coverage node in the report. to delete the coverage databse. however. Page 37 Copyright © 2002-2004 Cenqua Pty Ltd. coverage information and recompile when you change these settings. It will prevent classes.Clover 2. <clover-report> <current outfile="clover_html" title="My Project"> <format type="html"/> <sourcepath> <pathelement path="/some/other/location"/> </sourcepath> <testresults dir="test/results" includes="TEST*.xml"/> </current> </clover-report> This example generates a current coverage report for all files in the project that have changed in the last month.files"/> </fileset> <format srclevel="true" type="html"/> </current> </clover-report> In this example the standard Clover patternset is used to restrict the report to the currently included source files.

Examples of Historical Report Configurations <clover-report> <historical outfile="historical.xml"/> </current> </clover-report> Generates a HTML report. If less than 75% of methods are covered.xml"/> </current> <current outfile="report2" title="Coverage Report 2"> <format type="html"/> <fileset dir="othersrc"> <patternset refid="other. that will only include a bar chart showing the percentage of methods covered. the actual percentage of statements covered and the actual number of branches covered. All rights reserved. Assumes that <clover-historypoint> has generated more Page 38 Copyright © 2002-2004 Cenqua Pty Ltd.clover.pdf" historyDir="clover_history"> </historical> </clover-report> Generates a historical report in PDF. those values will be highlighted.files"/> </fileset> <testresults dir="test/results" includes="TEST*.0a5 User Manual Customising Columns <clover-report> <current outfile="report-current" title="Coverage"> <format type="html"/> <columns> <coveredMethods format="bar" min="75"/> <coveredStatements format="%"/> <coveredBranches format="raw"/> </columns> <testresults dir="test/results" includes="TEST*. Both of these reports will contain a link to the other. .files"/> </fileset> </current> </clover-report> Generates two HTML reports.Clover 2. Linked Report Example <clover-report> <current outfile="report1" title="Coverage Report 1"> <format type="html"/> <fileset dir="src"> <patternset refid="clover.

a file historical. use the <clover-report> task. All rights reserved. .pdf" title="My Project" historyDir="clover_history"> <overview/> <movers threshold="5%" range="20" interval="2w"/> </historical> </clover-report> Generates a PDF historical report that only includes an overview section (showing summary coverage at the last history point) and a movers table showing classes that have a code coverage delta of greater than +. <clover-report> <historical outfile="two_months" title="My Project" from="020101" to="020301" dateFormat="yyMMdd" historyDir="clover_history"> <format type="html"/> </historical> </clover-report> Generates a basic historical report in HTML for a certain time period. <clover-report> <historical outfile="report. Parameters Attribute outdir initstring Description Required The directory to write the report Yes. The path to the Clover No.4. Clover will use the initstring set Page 39 Copyright © 2002-2004 Cenqua Pty Ltd.6. For more configuration options. it will be created. Will include at most 20 gainers and 20 losers.Clover 2. If not specified. database. Clover will scan the history dir and use any history points that fall within the requested time period. If configured. <clover-html-report> Description Generates a full HTML report with sensible default settings. a history point is also generated prior to generation of the full report. to.0a5 User Manual than one history file in the directory "clover_history".html will be written into this directory. The outfile attribute will be treated as a directory. Writes the output to the file specified in the outfile parameter.5% over the two weeks prior to the last history point. 3. If the directory doesn't exist.

title testresultsdir The title to use in the report. and all history points in that directory will be used to generate the historical section of the report. For more configuration options. The report will be titled "MyProject Coverage". The directory for Clover history No.0a5 User Manual by a previous execution of <clover-setup/> in the current build sequence.6. A history point will be created in the "clover/historypoints" directory. . a new history point will be generated prior to the generation of the full report. No. <clover-html-report outdir="build/clover/report" historydir="clover/historypoints" title="MyProject Coverage" testresultsdir="build/test/results"/> This will generate a report in the "build/clover/report" directory.Clover 2. historydir Examples <clover-html-report outdir="clover/report"/> This is the simplest way to generate a html report. points. Page 40 Copyright © 2002-2004 Cenqua Pty Ltd. use the <clover-report> task. If this attribute is set. The directory containing the No.xml files in this directory. All rights reserved. see <clover-historypoint>. Test results will be loaded from "build/test/results" 3. Otherwise. the default database location will be used. It will be written to the directory "clover/report". If configured. For more information. Clover will look for all TEST*.5. XML results of the unit tests. <clover-pdf-report> Description Generates a PDF report with sensible default settings. a history point is also generated prior to generation of the full report.

a new history point will be generated prior to the generation of the full report. If not specified. The title to use in the report. <clover-historypoint> Description Records a coverage history point for use in historical coverage reports. All rights reserved. .pdf"/> This is the simplest way to generate a pdf report. No. see <clover-historypoint>. clover history points. It will be written to the file "clover_coverage.pdf". The report will be titled "MyProject Coverage". A history point will be created in the "clover/historypoints" directory. The directory that contains any No. Parameters <clover-pdf-report outfile="clover_coverage. If this attribute is set. the default database location will be used. database. For more information.6.pdf" historydir="clover/historypoints" title Page 41 Copyright © 2002-2004 Cenqua Pty Ltd. and all history points in that directory will be used to generate the historical section of the report. historydir title Examples <clover-pdf-report outfile="clover_coverage. Otherwise. to The path to the Clover No. 3.pdf".0a5 User Manual Parameters Attribute outfile initstring Description Required The filename to write the report Yes. Clover will use the initstring set by a previous execution of <clover-setup> in the current build sequence. This will generate a report in the current directory called "clover_coverage.6.Clover 2.

All rights reserved.Clover 2. If you have specified an initstring on the <clover-setup> task you must ensure <clover-setup> is called prior the execution of this task.SimpleDateFormat pattern. See Using Spans. The initstring of the coverage No. date dateFormat filter comma or space separated list No of contexts to exclude when generating the historypoint. Specifies an override date for No. . Specifies how far back in time No. for generation of past historical data for a project. defaults to the timestamp this history point. Specifies a date format string for parsing the "date" attribute. will look in the default location (${basedir}/. See Using Contexts. span overwrite Nested elements of<clover-historypoint> <fileset> <clover-historypoint> supports nested filesets which control which source files are to be included in a historypoint. This allows historypoints to focus on certain packages or particular classes. the same date will be automatically overwritten. or files written by a particular author.text. more complicated selections are possible. existing history point for No. Defaults to "false".SimpleDateFormat using the default pattern and date format symbols for the default locale. default set to java. If true. Only classes which are from the source files in the fileset are included in the historypoint. Page 42 Copyright © 2002-2004 Cenqua Pty Ltd. No. to include coverage recordings from since the last Clover build. If not specified here.0a5 User Manual Attribute historyDir initstring Description Required The directory where historical Yes data is stored.clover). The string must contain a valid java. such as the files which have recently changed. Defaults to "0s".text. Clover database. By using Ant's fileset selectors. This allows of the current coverage data.

. e. The target percentage statement coverage for the project.g. Parameters Attribute target Description Required The target percentage total At least one of these. nested <package> elements "10%" are specified. with the effective date of 24/07/01 12:08:56 3. All rights reserved. Examples <clover-historypoint historyDir="clover-historical"/> Records a history point into the directory PROJECT_DIR/clover-historical <clover-historypoint historyDir="clover-historical" date="010724120856" dateFormat="yyMMddHHmmss"/> Records a history point. Clover methodTarget statementTarget conditionalTarget initstring Page 43 Copyright © 2002-2004 Cenqua Pty Ltd. unless coverage for the project.0a5 User Manual <testsources> <testsources> is an Ant fileset that can be used to distinguish test source code from application source code. The target percentage conditional coverage for the project. This task needs to be run after coverage has been recorded. Clover's default test detection algorithm will be used to distinguish test sources.7. The target percentage method coverage for the project.6. optionally failing the build if the criteria are not met. If not specified here. If omitted. <clover-check> Description Tests project/package code coverage against criteria. All files included in the fileset will be displayed in the separate 'Test' node of the coverage tree.Clover 2. The initstring of the coverage No.

Specifies how far back in time No. Parameters Attribute name regex Description The name of the package. Regular expression to match package names. If the target is not met. to include coverage recordings from since the last Clover build. All rights reserved. filter span Nested elements of <clover-check> <package> Specifies a target for a named package. default is "false" halted if the target is not met. will look in the default location (${basedir}/. haltOnFailure failureProperty Specifies if the build should be No. comma or space separated list No of contexts to exclude when calculating coverage. the property will contain a text description of the failure(s). Specifies the name of a No property to be set if the target is not met.0a5 User Manual database. . Defaults to "0s".clover). If you have specified an initstring on the <clover-setup> task you must ensure <clover-setup> is called prior the execution of this task. Required exactly one of these Page 44 Copyright © 2002-2004 Cenqua Pty Ltd. See Using Spans.Clover 2. See Using Contexts.

core is at least 70% • total percentage coverage for package com. <clover-check target="80%" failureProperty="coverageFailed"/> Tests if total percentage coverage is at least 80%.killerapp.killerapp. "10%" The target percentage method coverage for the package. If not.acme.Clover 2. . The target percentage conditional coverage for the package. e.ai" target="40%"/> </clover-check> Tests: • total percentage coverage for project is at least 80% • total percentage coverage for package com.ai is at least 40% If any of these criteria are not met. The target percentage statement coverage for the package. methodTarget statementTarget conditionalTarget Examples <clover-check target="80%"/> Tests if total percentage coverage is at least 80%. <clover-check target="80%" haltOnFailure="true"/> Tests if total percentage coverage is at least 80%. a message is logged and the project property coverageFailed is set. <clover-check target="80%" filter="catch"> Page 45 Copyright © 2002-2004 Cenqua Pty Ltd. If not.g.killerapp.acme. a message is logged and the build continues.acme.killerapp. If not.0a5 User Manual target The target percentage total At least one of these. a message is logged and the build continues. a message is logged and the build fails.core" target="70%"/> <package name="com. <clover-check target="80%" <package name="com. All rights reserved. coverage for the package.acme.

acme. See Using Contexts. to include coverage recordings level filter span Page 46 Copyright © 2002-2004 Cenqua Pty Ltd.killerapp.killerapp.acme. <clover-check> <package regex="com. <clover-check target="80%" conditionalTarget="90%" filter="catch"> <package name="com. Defaults to "0s". <clover-log> Description Reports coverage information to the console at different levels.6. class.ai" target="40%"/> </clover-check> As above. Clover database. statement comma or space separated list No of contexts to ignore when calculating coverage. If not specified here. but also ensure project conditional coverage is at least 90%.acme.core" target="70%"/> <package name="com. will use the default location (${basedir}/.acme.acme. Controls the level of detail No. method. . All rights reserved.0a5 User Manual <package name="com. 3. If you have specified an initstring on the <clover-setup> task you must ensure <clover-setup> is called prior the execution of this task. Specifies how far back in time No. Parameters Attribute initstring Description Required The initstring of the coverage No.killerapp.core" target="70%"/> <package name="com.killerapp.killerapp. Valid values are summary.ai" target="40%"/> </clover-check> As previous example.core.acme.killerapp.clover). defaults to "summary" included in the report. but don't include coverage of catch blocks when measuring criteria.Clover 2.8.core and all subpackages is atleast 70%.*" target="70%"/> </clover-check> Tests if coverage for com.

core to the console.core to the console. <clover-log> <package name="com.killerapp.acme.core"/> </clover-log> Prints detailed (source-level) code coverage com. information for the package <clover-log level="statement" filter="catch"> <package name="com.Clover 2. All rights reserved.acme.killerapp.killerapp. Multiple <package> elements can be specified.core"/> </clover-log> Page 47 Copyright © 2002-2004 Cenqua Pty Ltd. See Using Spans. .acme.acme. <Sourcepath> Specifies a Ant path that Clover should use when looking for source files.acme. Nested elements <Package> Specifies a named package to restrict the report to.core"/> </clover-log> Prints a summary of code coverage for the package com.0a5 User Manual from since the last Clover build. Examples <clover-log/> Prints a summary of code coverage to the console. Parameters Attribute name Description Required The name of the package to Yes include.killerapp. <clover-log level="statement"> <package name="com.killerapp.

It is detected at runtime. The source level to process No. The directory into which Clover Yes will write an instrumented copy of the source code. .clover.g.db If not specified it defaults to . These can then be compiled in place of the original source to produce an instrumented build. e. ${basedir}/build/clover.6. defaults to Java version source files at.9. source destdir srcdir Page 48 Copyright © 2002-2004 Cenqua Pty Ltd. but catch blocks will not be considered in coverage reporting. relative to the project's base directory. <clover-instr> Description The <clover-instr> task produces instrumented versions of sets of source files. The <clover-instr> task is provided for users that can't make use of the standard <clover-setup> integration task. either here or on <javac> invocations. Clover will look for source files in the directory /some/other/location. recommended that you set this parameter. The <clover-setup> task offers a simpler and less intrusive integration option for most users. element is used. Typically this is a relative or absolute file reference.Clover 2. unless a nested <fileset> instrument. Parameters Attribute initstring Description Required The Clover initString describes No the location of the clover coverage database. The directory of source code to Yes. 3. All rights reserved. <clover-log level="statement"> <sourcepath> <pathelement path="/some/other/location"/> </sourcepath> </clover-log> Prints source-level coverage report to the console.0a5 User Manual As above.

When the flushpolicy is set to No interval or threaded this value is the minimum period between flush operations (in milliseconds) This controls whether the No. interval.Clover 2. defaults to false initstring parameter is treated as a relative path or not. .0a5 User Manual flushpolicy This attribute controls how No. This is a "passive" mode in that flushing potentially occurs as long as instrumented code is being executed. All rights reserved. interval Coverage data is flushed as for directed. directed Coverage data is flushed at JVM shutdown. threaded Coverage data is flushed as for directed. as well as periodically at a maximum rate based on the value of flushinterval. or threaded. as well as periodically at a rate based on the value of flushinterval. defaults to directed Clover flushes coverage data during a test run. Valid values are directed. For more information. This is an "active" mode in that flushing occurs on a separate thread and is not dependent on the execution of instrumented code. and after an inline flush directive. flushinterval relative Nested Elements of <clover-setup> Page 49 Copyright © 2002-2004 Cenqua Pty Ltd. see Flush Policies.

Note that when statements are tested against this regexp. This regexp should match the method signatures of methods you wish to include in this context. and not be one of the reserved context names (See Using Contexts) A Perl 5 Regexp that defines yes the context. <methodContext> Specifies a method Context definition. Parameters Attribute name Description Required The name for this context.0a5 User Manual <fileset> Specifies a set of source files to instrument. whitespace is normalised and comments are ignored. Must Yes be unique. and not be one of the reserved context names (See Using Contexts) A Perl 5 Regexp that defines yes the context. . Must Yes be unique.Clover 2. All rights reserved. regexp Page 50 Copyright © 2002-2004 Cenqua Pty Ltd. See Using Contexts for more information. Note that when method signatures are tested against this regexp. Parameters Attribute name Description Required The name for this context. See Using Contexts for more information. regexp <statementContext> Specifies a statement Context definition. This regexp should match statements you wish to include in this context.

3.java"/> </fileset> </clover-instr> This example achieves the same as the first example. This is not always practical. Specifying the location of the Clover Database. <clover-instr initstring="clover-db/coverage. the directory clover-db should exist before running this task. All rights reserved. To override this location use the initstring attribute. Page 51 Copyright © 2002-2004 Cenqua Pty Ltd. In this situation. Interval Flushing By default Clover will write coverage data to disk when the hosting JVM exits. <clover-instr destdir="instr"/> <fileset dir="src"> <include name="**/*. via a shutdown hook.6. Clover writes its internal database to the .Clover 2.clover directory relative to the project's basedir. you can configure Clover to use "interval" flushing.db" srcdir="src" destdir="instr"/> This example will use clover-db/coverage. particularly when the application you are testing runs in an Application Server.0a5 User Manual whitespace is normalised and comments are ignored. Examples <clover-instr srcdir="src" destdir="instr"/> Produce an instrumented copy of all source files in the src dir into the destdir. <clover-clean> Description Delete the coverage database and associated coverage recording files. but using an embedded fileset.10. . NB. By default. The Clover registry is at the default location.db as the location for the clover DB. where coverage data is written out periodically during execution: <clover-instr flushpolicy="interval" flushinterval="5000" srcdir="src" destdir="instr" The "flushinterval" defines in milliseconds the minimum interval between coverage data writes.

clover). If not specified here.Clover 2. If "false". defaults to "true" file.7. keepdb verbose haltOnError Examples <clover-clean/> Deletes all of the coverage recordings. Unit Test Results and Per-test Coverage Clover 2 introduces the ability to integrate Unit Test results and per-test coverage information into Coverage reports. If you have specified an initstring on the <clover-setup> task you must ensure <clover-setup> is called prior the execution of this task. ("true"/"false"). <clover-clean verbose="true"/> Deletes all of the coverage recordings. Clover clean. Show the name of each deleted No. All rights reserved. will use the default location (${basedir}/. Page 52 Copyright © 2002-2004 Cenqua Pty Ltd. defaults to "false" file ("true"/"false"). by showing you exactly which statements each of your tests cover. printing out a log statement for each file deleted. This unique feature gives you a powerful insight into how well tested your covered code actually is.0a5 User Manual Parameters Attribute initstring Description Required The initstring of the database to No. <clover-clean keepdb="false"/> Deletes the coverage database and all of the coverage recordings. Keep the coverage database No. 3. the coverage database will be deleted. defaults to "false" as a failure to delete a file) stops the build or is merely reported to the screen ("true"/"false"). . Controls whether an error (such No.

. . All rights reserved.7. In an Ant build. follow these steps: 1. It is also currently not possible to configure Clover's test detection mechanism.x and TestNG. Allow Clover to instrument your test classes. 3. /> If you are using the more configurable <clover-report task. you need to pass an Ant fileset of test results: <clover-report> <current outfile="clover-html"> <format type="html"/> <testresults dir="${testreport... Sharing Report Formats You can share report formats across a number of reports.dir}"> <include name="**/TEST*xml"/> </testresults> </current> </clover-report> 3. This allows Clover to specially mark test methods to enable per-test coverage reporting. Enable XML reports from your Unit Test execution. <formatter type="xml"/> <batchtest todir="${testreport. 2. if using the <junit> task.... you need to add an XML result formatter: <property name="testreport.. Limitations Clover's per-test coverage collection does not support parallel test execution. The Clover instrumenter automatically detects test methods for Junit 3.8. </batchtest> </junit> 3.1. Tell the Clover report task(s) how to find the XML test reports.dir" value="build/test-reports"> <junit .dir}"> . Standalone Page 53 Copyright © 2002-2004 Cenqua Pty Ltd.x. This allows you to standardise on a set of report formats and use these for all your reports. specify the directory where XML test reports are written: <clover-html-report testresultsdir="${testreport.Clover 2. If you are using the <clover-html-report task. Standalone format elements are created using the <clover-format> type.> .dir}" . Junit 4. This allows Clover to integrate Unit Test results into Coverage reports.0a5 User Manual To take advantage of this feature..

You name the format using the standard Ant "id" attribute. "bw.format". PDF reports. uses the "std. The second format.format Page 54 Copyright © 2002-2004 Cenqua Pty Ltd. Once the format is declared with an identifier. The format defaults to the standard format.1 to use this feature. The following is a complete example <target name="report"> <clover-format id="std. is essentially the same except it specifies black and white output. The refid values in the <format> elements can be an Ant property allowing selection of the report format at build time.format" srclevel="true" type="pdf"/> <clover-format id="bw.format" bw="true" srclevel="true" type="pdf"/> In this example.format". it can be used by reference with a "refid" attribute.format" format defined above. The following code declares two report formats <clover-format id="std. This default can be overriden from the command line.5.4. To generate black and white reports you would use: ant report -Dformat=bw.format" bw="true" srclevel="true" type="pdf"/> <property name="format" value="std.1.pdf" title="Ant Coverage"> <format refid="std. the first format is for source level.pdf" title="Ant Coverage"> <format refid="${format}"/> </current> <historical historydir="clover-hist" outfile="report-history. All rights reserved. we are generating two reports. It is named "std. a summary report.format"/> </current> </clover-report> This report. a colour report.format" srclevel="true" type="pdf"/> <clover-format id="bw. These standalone types support the same attributes and elements as the internal <format> elements of the <clover-report> task.Clover 2. This is shown in the following report example <clover-report> <current summary="yes" outfile="report-current. which share a format.format"/> <clover-report> <current summary="yes" outfile="report-current.pdf" title="Ant Historical Coverage"> <format refid="${format}"/> </historical> </clover-report> </target> Here.0a5 User Manual formats elements are not compatible with Ant 1. You require at least Ant 1. .

3 milestone releases nor Rational Application Developer for WebSphere Software v7.2. . and JDKs 1.2. using JDKs 1. We have not tested the plugin with Eclipse 3.1. For these reasons.2) at this stage. The plugins allow you to measure and view code coverage without leaving the IDE.2.a1 (alpha 1) Note: This is an Early Access Programme (EAP) alpha release of the plugin based on a complete rewrite of the software.0a5 User Manual 4. and to view your coverage results inside Eclipse.x.0. • Ant path filters. Additionally. Plugin Guides • Eclipse • IntelliJ IDEA: coming soon • NetBeans: coming soon 4.1.x users. IDE Plugin Guides 4. Overview The Clover Eclipse Plugin allows you to instrument your Java code easily from within the Eclipse Java IDE. there are a number of features missing from this EAP release: • Context filters.5. Some functionality from previous versions of the plugin is not yet available and it's likely there are bugs in the functionality that is provided. we do not recommend you use this plugin for the development of production code in your main Eclipse installation and urge you to routinely back up / check in the source code of your Eclipse projects while using this alpha sofware.4.1.x. This plugin has been tested with Eclipse 3.2.1. Page 55 Copyright © 2002-2004 Cenqua Pty Ltd. 4. Limitations For existing Clover 1. Eclipse Plugin Guide Plugin Version 2. • Coverage markers. 4.0. once you've upgraded your project to use this new version of Clover it is non-trivial to downgrade.2. 4. • Working sets. All rights reserved. Clover IDE Plugins Clover provides fully integrated plugins for many popular Integrated Development Environments.Clover 2. They are also compatible Clover for Ant.0 (based on Eclipse 3.

• Hidden .clover_YourProjectName and although we've hidden its presence from many Eclipse UI elements there are still some places where you may see it.please ignore this warning. Know issues: • Enabling / disabling Clover compilation. • Click the "New Remote Site" button and provide a name of "Clover EAP Update Site" and a URL of http://www.cenqua. 4. This will point Eclipse to the Clover EAP update site from where it will download the plugin. Page 56 Copyright © 2002-2004 Cenqua Pty Ltd.Clover 2. • Finally. To perform the source code instrumentation required for code coverage analysis. • Accept the license agreement if you agree. Click "Yes" to restart and activate the plugin. . If in doubt. All rights reserved. The name of this project is . Installation 1 Installing the plugin • Within Eclipse. Sometimes enabling / disabling compilation with Clover on a project will require you to manually perform a clean build to restore your project to a fully instrumented / uninstrumented state. • You will then be prompted to confirm installation the Clover feature (Eclipse terminology for a collection of plugins). • Select "Search for new features to install" and click the "Next" button to continue. click the "Finish" button.clover_ projects. The Clover plugin is not yet digitally signed so you may encounter a warning to this effect . Click "Install" to proceed with the installation. Clover needs to create and control a hidden Eclipse project in your workspace for each of your Clover-enabled projects. All these features will be added back in to Clover 2. • Select the entry "Clover EAP Update Site" (and all its children elements) and click the "Next" button to select the Clover plugin for installation. 2 Installing the license • The plugin comes with an EAP license embedded and already activated.0a5 User Manual • Project properties.com/clover/20/eap/eclipse/ .3. you will be asked if you want to restart Eclipse after installing the plugin. perform a clean build.x over the course of the EAP. select from the menu "Help | Software Updates | Find and Install" to start the installation process. During the EAP programme you will not need to modify this license.2. Please ignore resources from this project while we work on completely eliminating its presence from your workflow. click the "Next" button and then click "Finish" to start download process.

Using the plugin Enabling Clover for your project Clover can be enabled for any of your Java-based Eclipse projects. • Open the Clover Coverage View by selecting "Window | Show View | Other.. • Select "Clover | Enable for this Project".2. All rights reserved. Page 57 Copyright © 2002-2004 Cenqua Pty Ltd. You should see your project listed with 0% coverage against it.4. • From the Project Explorer view. • With Clover now enabled. your project will now be automatically rebuilt. ..Clover 2." and selecting Clover > Coverage.0a5 User Manual 4. right click on your Java project.

The tree shows the project. and shows you the coverage statistics for each project. All rights reserved.Clover 2. package and Page 58 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual Image of the Clover's context menu for a sample Java project without Clover enabled The Clover Coverage View The Coverage View allows you to control Clover's instrumentation of your Java projects. .

. Launches the report generation wizard that will take you through the steps required to generate a Pdf. you can open it again using "Window | Show View | Other.Clover 2. Toggles the use of Clover instrumentation when Eclipse compiles the selected Java project." and selecting "Clover | Clover View". • Hide 100% Covered. • Hide Unit Tests. This check button hides any elements in the Coverage View's tree that don't have associated coverage information and helps reduce visual clutter. • Generate Report. . Re-loads from disk the Clover coverage data for the selected project. This is useful for finding out exactly which parts of the code are being covered. • Hide Unavailable. • Generate Coverage Cloud. This check button hides any elements in the Coverage View's tree that have full coverage and helps let you focus on only those classes that require more testing. All rights reserved.. • Delete Coverage Data. If the viewer is closed. • Show Coverage in Editor. Deletes the recordered coverage data for the selected project. The viewer allows the following actions: • Refresh Coverage Data. with this button checked any project that isn't Clover-enabled will not be shown in the Coverage View. Shows or hides red/green coverage areas in open Java editors. For instance. Image of the Clover Coverage View within Eclipse The Clover Viewer is automatically added to the workbench when you enable Clover for your project. Html or Xml. Generates a report page in cloud tag format that lists classes considered project risks or quick wins. • Compile with Clover. This check button hides any classes defining JUnit / TestNG tests in the Page 59 Copyright © 2002-2004 Cenqua Pty Ltd. Summary statistics are displayed along side the tree for the selected project/package/class.0a5 User Manual class coverage and complexity information for all Clover-enabled project.

0a5 User Manual Coverage View's tree to help reduce visual distractions when trying to find classes needing better code coverage. If you wish to switch off the source code annotations you can easily do so by deselecting the menu / toolbar item Page 60 Copyright © 2002-2004 Cenqua Pty Ltd.Clover 2. This may include coverage data created using Clover external to the Eclipse IDE. Viewing Coverage Results The Clover Eclipse plugin allows you to view Clover coverage data within the Eclipse IDE. All rights reserved. This marker has a tooltip indicating the coverage problem. Image of an Eclipse Java editor with coverage annotations enabled The Clover plugin shows coverage data in three ways: • As a marker in the overview bar (right-hand side). or coverage data generated by the Clover Plugin internal to Eclipse. • As a coloured annotation of the source code in the Java editor. .

You can prevent coverage information from being displayed in the Java editors by toggling the "Show Coverage in Editor" button although this will apply to all Clover-enabled projects in the workspace. Disabling Clover in your project You can disable Clover instrumentation using the "Compile with Clover" button. Each page lists the classes of the project enlarged or reduced depending on their significance to the report and clicking on any class name will open the corresponding source file in an editor. one tag for the project risks page and the other for quick wins page. This report has two tabs.Clover 2. As a "tag cloud" report highlighting the classes that form major project risks (low coverage. Image of cloud report Instrumenting your code You can use the Clover Eclipse plugin to instrument the Java source in your project each time it is built. This option is activated on a per-project basis by toggling the "Compile with Clover" button in the Clover Viewer. All rights reserved.0a5 User Manual • "Show Coverage in Editor" on the Coverage View. hich complexity) and potential quick wins for increasing project coverage. . Page 61 Copyright © 2002-2004 Cenqua Pty Ltd.

then un-check "Enable Clover plugin in the project" on the Clover page of the project's properties dialog. 4. Configuration options The Clover Eclipse plugin's configuration can be accessed in two places: • From the "Clover" page of a project's properties dialog (Project | Properties). • How often Clover writes coverage data to the disk.General Page 62 Copyright © 2002-2004 Cenqua Pty Ltd. • File filters that determine which files are instrumented.2. Project Properties This release of the Clover plugin does not provide any per-project configuration options. The final public release of the plugin will allow configuration of: • Where Clover stores the coverage database. . All rights reserved.5. • Context filters that determine which types of code are instrumented.Clover 2. • From the "Clover" page of the workspace preferences (Window | Preferences). Clover Preferences .0a5 User Manual If you want to completely de-activate Clover support in a project. You can also achieve this by right clicking on the project and selecting "Clover | Disable for this Project".

This section allows you to specify what the default action should be. If it is not enabled. the plugin will check for updated coverage data at the frequency given below. then you will need to use the "Refresh Coverge Data" Page 63 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual Image of the general page of the Clover plugin preferences When rebuilding project When your rebuild a project. Clover will ask you whether you want to delete the existing coverage information. . Coverage visualization should refresh automatically If enabled. All rights reserved. and whether Clover should prompt you at all.Clover 2.

Clover 2. Coverage visualization should span coverage before build The span attribute allows you to control which coverage recordings are merged to form a current coverage report. see Using spans. Clover Preferences .0a5 User Manual button to see newer coverage data.License Image of the license page of the Clover plugin preferences License text When you receive a Clover license from Cenqua you should copy its contents to this text box. For more information. All rights reserved. verbose or debug. . Miscellaneous settings This allows you to set the logging output of the plugin to one of three levels: minimal. If the license text is on the clipboard then clicking the "Paste" button Page 64 Copyright © 2002-2004 Cenqua Pty Ltd.

" button will allow you to select the file and fill the text box with its contents.0a5 User Manual will paste it to this text box automatically.. FAQ Q: Why can I only see coverage data for the last test case I executed? Why does my coverage information disappear each time I Eclipse autocompiles a file? By default. If you have saved the Clover license to a file then clicking the "Load. Clover will display the coverage information gathered since your last compile full build or auto build.2.Clover 2.. You can change how far back in time Clover will look for coverage data by setting the Span parameter in the Clover page in the Workspace preferences (Window | Preferences). All rights reserved. . Page 65 Copyright © 2002-2004 Cenqua Pty Ltd. Summary The summary box summarises the nature of the currently enabled license for Clover.6. 4.

it is managed by Clover and should not be edited directly by the user. The following table shows the various files created if Clover is initialised with an initstring of "clover. . Database structure and lifecycle The Clover database consists of several files that are constructed at various stages of the instrumentation and coverage recording process.1 (where HHHHHHH and TTTTTTTTTT are both hex strings) Page 66 Copyright © 2002-2004 Cenqua Pty Ltd. and also during report generation or coverage browsing (such as via an IDE plugin or the Swing Viewer). report generation and coverage browsing.0a5 User Manual 5. 5.1.dbHHHHHHH_TTTTTTTTTT. CoverageRecording Files Filename: clover.db Description: The Registry file contains information about all of the classes that have been instrumented by Clover.1. The ContextDef file is read during instrumentation. a new Registry file is created. lifecycle and management of the Clover database.db" Registry file Filename: clover.ctx Desription: The ContextDef file contains user-defined context definitions. All rights reserved. Note that while this file is in plain text. This file does not contain any actual coverage recording data. Background: The Clover Coverage Database This section provides background information on the structure.dbHHHHHHH_TTTTTTTTTT or clover. Lifecycle: The Registry file is written during the instrumentation process. If an existing Registry file is found. the existing file is updated.db. The Registry file is read by Clover-instrumented code when it is executed. Lifecycle: The ContextDef file is written prior to Clover instrumentation.Clover 2. If no Registry file is found. ContextDef file Filename: clover.1. Advanced Usage 5.

The number of Coverage Recorders created at runtime depends the nature of the application you are Clovering. When deploying you application in container environments. Note: Clover 1. Note that the IDE Plugins all have a feature to automatically manage the Clover database for you. 5. Using Clover with Distributed Applications In some cases the application you wish to test has many components running on separate nodes in a network. Each Coverage Recorder will write one CoverageRecording file.1 appended to its name. The <clover-clean> Ant task is provided to allow easy deletion of a Clover database. CoverageRecording files are named this way to try to minimise the chance of a name clash.Clover 2. All rights reserved. This prevents data loss in the event of abnormal JVM termination.3. it is in general recommended that the database be deleted after it is used to generate reports. Although Clover will update an existing database over successive builds.1. CoverageRecording files are read during report generation or coverage browsing. The first hex number in the filename (HHHHHHH) is a unique number based on the recording context. The secondary recording file has the same name as a normal recording file but with .7 introduced a new failsafe mechanism for writing recording files to disk when using interval-based flush policies. Lifecycle: CoverageRecording files are written during the execution of Clover-instrumented code. 5. In general a new Coverage Recorder will be created for each new ClassLoader instance that loads a Clovered class file. so that a fresh database is created on the next build. or even on disconnected machines.0a5 User Manual Description: CoverageRecording files contain actual coverage data.2. in practice the chances are very small. When running instrumented code. . While it is theoretically possible that a name clash could occur. This directory can be created at the start of a Clover build. although some additional setup is required.2. you should also check to ensure that Clover has sufficient permissions to function. you might find it easier to create the database in its own directory. The second hex number (TTTTTTTTTT) is the timestamp (ms since epoch) of the creation of the Clover Recorder. and deleted once coverage reports have been generated from the database. The mechanism alternates between writing to a primary recording file and a secondary recording file. You can use Clover to test such applications. Clover creates one or more Coverage Recorders. Page 67 Copyright © 2002-2004 Cenqua Pty Ltd. Managing the Clover database Because the Clover database can consist of many recording files. Doing this improves the runtime performance of Clover.

3.prefix To set one of these properties. Clover constructs a registry of your source code.initstring System property is not set). Telling Clover how to find it's registry If you are deploying and running your Clover-instrumented code on different machines. otherwise no coverage will be recorded.2. Specify an Initstring that is a globally accessible file path The compile-time initstring should be an absolute path to the same filesystem location and be accessible and writable from the build machine and all execution machines.0a5 User Manual 5. resolved at runtime The compile-time initstring represents a relative path (relative to the CWD of each execution context). .basedir clover. and provide a place for Clover to write coverage recording files. you need to pass it on the command line when java is Page 68 Copyright © 2002-2004 Cenqua Pty Ltd.initstring or clover. See Clover Database Structure for more information.2.initstring. Specify an Initstring at runtime via System properties You can override the Clover initstring at runtime via System Properties.initstring. Clover then records coverage data and writes coverage recording files next to the registry file during execution. If not null (and the clover.g. Clover looks in the same location for this registry file to initialise itself. All rights reserved.Clover 2. by running a suite of unit tests). 2.initstring. Two System properties are supported clover. This could be a path on shared drive or filesystem. and writes it to a file at the location specified in the Clover initstring. the value of this property is prepended to the string value of compile-time specified initstring to resolve the full path to the Clover registry.2.1.basedirSystem properties are not set). the value of this property is treated as an absolute file path to the Clover registry file If not null (and the clover. When Clover-instrumented code is executed (e. 5. the value of this property is used as the base directory for the file specified at compile-time in the initstring to resolve the full path to the Clover registry. you must provide a way for Clover to find the registry file. Specify an Initstring that is a relative path. clover. Background: the Clover initstring At build time. Clover provides three ways to achieve this: 1.initstring If not null. To do this you need to specify relative="yes" on the <clover-setup> task.

as part of the test deployment process.Clover 2.Server For application servers. To use Clover in these environments. .4. java. Recommended Permissions Clover requires access to the java system properties for runtime configurations. 5.initstring=.3. "read.util. as well as read write access to areas of the file system to read the clover coverage database and to write coverage information.FilePermission "<<ALL FILES>>". Restricted Security Environments In some java environments.PropertyPermission "*".. java. this may involve adding the property to a startup script or batch file.. Clover needs to be granted various security permissions for it to function. All rights reserved. you'll need to copy the coverage recording files from each remote machine to the initstring path on build machine to generate coverage reports. and before you run your tests. see Permissions in the Java 2 SDK. myapplication. security restrictions are applied to hosted java code that restrict access to various system resources. using the -D parameter: java -Dclover.lang. such as J2EE containers.RuntimePermission "shutdownHooks". see Default Policy Implementation and Policy File Syntax. Classpath Issues You must put clover. write". or applications deployed via Java Webstart. applet environments. For background on the syntax of the policy file. "read". Once test execution is complete.0a5 User Manual launched.jar" { java.jar (or the appropriate Clover plugin jar) in the classpath for any JVM that will load classes that have been instrumented by Clover. How you go about this depends on the nature of the application you are testing and the particular environment being deployed to. Note: For methods 2 and 3 above. To support these requirements.io. Page 69 Copyright © 2002-2004 Cenqua Pty Ltd.2. the following security permissions are recommended: grant codeBase permission permission permission } "file:/path/to/clover. This needs to occur after the Clover build is complete. you will need to copy the Clover registry file from the location on the build machine to the approriate directory on each of the execution machines. For background on setting Java security policies in general. 5. Clover also uses a shutdown hook to ensure that it flushes any as yet unflushed coverage information to disk when java exits.2. This requires the addition of a Grant Entry to the security policy file for the Clover jar.

Clover provides three policies: directed. you will want to use one of the interval-based flush policies. interval and threaded. or via the IDE plugin configuration screen. The default mode is directed. use the threaded policy.3. . and also at a maximum rate determined by the interval set at instrumentation time (see the flushinterval attribute on <clover-setup>). The interval mode is a "passive" mode in that flushing potentially occurs only while instrumented code is still being executed. The interval policy flushes as per the directed policy. because the flush interval has not elapsed between the last flush and the end of execution of instrumented code. There exists the possibility that coverage data recorded just prior to the end of execution of instrumented code may not be flushed.Clover 2. interval Page 70 Copyright © 2002-2004 Cenqua Pty Ltd. Any coverage not flushed in this manner will be flushed if/when the hosting JVM shuts down. either via the <clover-setup> Ant Task. The flush policy is set at instrumentation time. In the most common unit testing scenarios the default flushpolicy will suffice. Directed flushing has the lowest runtime performance overhead of all flush policies (depending on the use of the flush inline directive). Note that no coverage recordings will be written if the hosting JVM is not shut down. The interval policy should be used in environments where shutdown of the hosting JVM is not practical and thread creation by Clover is not desired.0a5 User Manual 5. Coverage recordings are flushed only when the hosting JVM is shut down. Flush Policies How Clover writes coverage data to disk at runtime can be configured by changing Clover's flush policy. In situations where instrumented code is executing in a hosted environment (like a J2EE container) and shutting down the JVM at the end of testing is not desirable. or if the hosting JVM terminates abnormally. Policy directed Description default. All rights reserved. Which flush policy you choose depends on the runtime environment that instrumented code is executing in. If you don't mind Clover creating a thread. or where the user has directed a flush using the ///CLOVER:FLUSH inline directive.

4. ///CLOVER:USECLASS Clover will use a static holder class rather than a static member variable to support Page 71 Copyright © 2002-2004 Cenqua Pty Ltd. Switching Clover on and off ///CLOVER:ON ///CLOVER:OFF Switch Clover instrumentation on/off. 5.3 and above. Force Clover to flush ///CLOVER:FLUSH Clover will insert code to flush coverage data to disk.3. 5. .4.2. The threaded mode starts a separate thread to perform flushes. All rights reserved. Runtime performance overhead is determined by the flush interval. Change instrumentation strategy Note: This source directive has been deprecated and has no effect in Clover 1.0a5 User Manual Runtime performance overhead is determined by the flush interval. Source Directives Clover supports a number of directives that you can use in your source to control instrumentation.Clover 2. Note that the scope of this directive is the current file only.4. Directives can be on a line by themselves or part of any valid single or multi-line java comment. 5. threaded The threaded policy flushes as per the directed policy. 5. The threaded policy should be used in environments where shutdown of the hosting JVM is not practical. See Flush Policies. and also at a rate determined by the interval set at instrumentation time (see the flushinterval attribute on <clover-setup>).4. This might be useful if you don't want Clover to instrument a section of code for whatever reason. The flush code will be inserted as soon as possible after the directive.1.

A full list of supported Block Contexts are shown below. you can specify which contexts you would like to exclude in the coverage report. 5. Block Contexts Block Contexts are pre-defined by Clover. All rights reserved. At report time. Contexts Clover defines a Context as a part of source code that matches a specified structure or pattern.Clover 2. This directive is useful when you don't want Clover to change the public interface of your class (in EJB compilation for example).0a5 User Manual instrumentation for the current file.5. . name static instance constructor method switch while do for if else try catch finally sync assert @deprecated description Static initializer block Instance initializer block Constructor body Method body Switch statement body While loop body do-while loop body For loop body if body else body try body catch body finally body synchronized block assert statement a deprecated block Page 72 Copyright © 2002-2004 Cenqua Pty Ltd. 5. Contexts are either pre-defined or user-defined at instrumentation time.1.5. The directive must occur before the first top level class declaration in the file. They represent 'block' syntatic constructs in the Java language. Each context must have a unique name.

All rights reserved.*(get|set|is)[A-Z0-9].4.Clover 2. You can define your own method contexts via the <methodContext> subelement of <clover-setup>. Clover provides several pre-defined method contexts: name private property regexp (. . For details of using filters with the IDE plugins.* description matches all private methods property (. or via the configuration panel of your Clover IDE Plugin. whitespace is normalised and comments are ignored.2.*LOG\. To filter them.5. Statement Contexts A Statement Context represents the set of statements that match a given pattern. 5.debug. Note: Contexts are matched against your source at instrumentation-time.0a5 User Manual 5. you can use Clover's predefined catch context to exclude statements inside catch blocks from a coverage report: <clover-report> Page 73 Copyright © 2002-2004 Cenqua Pty Ltd. Filtering catch blocks In some cases you may not be interested in the coverage of statements inside catch blocks.5.* getters/setters Note: When matching method signatures against context regexps. Method Contexts A Method Context represents the set of methods whose signature matches a given pattern. For example. 5. you might want to set up a statement context to allow you to filter out 'noisy' statements such as logging calls by defining a statement context regexp .3.*. see the individual documentation for the plugin.* )?private .* )?public matches all .5. Using Context Filters Note: This section describes using context filters with Ant. This means you need to re-instrument your code after defining a new context.

Clover 2.. Filtering logging statements To remove logging statements for coverage reports.> <statementContext name="log" regexp="^LOG\.6. You can you then generate a report that excludes logging statements: <clover-report> <current outfile="clover_html" title="My Coverage"> <format type="html" filter="log. Clover only considers coverage recording files that were written after the last Clover compilation. while the second matches statements that start with if (LOG.. .0a5 User Manual <current outfile="clover_html"> <format type="html" filter="catch"/> </current> </clover-report> This generates a source-level HTML report that excludes coverage from statements inside catch blocks. The first matches statements that start with LOG.. 5. you'll need to define one or more statement contexts that match logging statements in your source: <clover-setup . In some situations you may want to include earlier coverage recordings..is.iflog"/> </current> </clover-report> This generates a source-level HTML report that excludes coverage from logging statements. All rights reserved. </clover-setup> This defines two statement contexts. The span attribute takes an Interval which tells Clover how far back in time since the last Clover compilation that coverage recordings should be merged to build the report.*"> <statementContext name="iflog" regexp="^if \(LOG\.*"> . Using Spans The span attribute allows you to control which coverage recordings are merged to form a current coverage report. Page 74 Copyright © 2002-2004 Cenqua Pty Ltd. which is designed to match conditional logging statements such as if (LOG. By default.isDebugEnabled()) { // do some expensive debug logging } Once defining these contexts you now need to re-compile with Clover and then re-run your tests. The span attribute lets you do this..

foo.5 distribution.bar An XPath implementation is shipped with the JDK1.NUMBER).xpath. All rights reserved. Third party implementations that work with JDK1.foo. . XML coverage reports can be generated by the <clover-report> or <clover-historypoint> Ant tasks. XPath xpath = XPathFactory..bar']/metrics[@statements] Extracts the total number of statements in the package com.1..foo. Dom4j.Clover 2. The following example XPath expressions show how to extract data from a Clover XML coverage report: /coverage/project/metrics[@statements] Extracts the total number of statements in the project.evaluate(expression. Using XPath with Clover's XML reports Clover's XML reports provide detailed coverage data in a format that is easy to access programmatically using XPath. InputSource inputSource = new InputSource("coverage.4 and below include Jaxen. inputSource.7.*. and JXP The following code example (using the JDK1.bar /coverage/project/package[name='com. Double projectStatements = (Double) xpath.xml..NUMBER).newXPath().bar']/metrics[@coveredstatements] Extracts the total number of covered statements in the package com. /coverage/project/package[name='com.0a5 User Manual 5. Extracting coverage data programmatically 5.xml").evaluate(expression.foo..5 implementation of XPath) demonstrates simple extraction of coverage data from a Clover XML report: import javax. . Double projectCoveredStatements = (Double) xpath. XPathConstants. /coverage/project/metrics[@coveredstatements] Extracts the total number of uncovered statements in the project.7. String stmtExpr = "/coverage/project/metrics[@statements]". inputSource. Page 75 Copyright © 2002-2004 Cenqua Pty Ltd.newInstance(). . XPathConstants. String coveredStmtExpr = "/coverage/project/metrics[@coveredstatements]".

Tutorials 6. These sample files are shipped with JUnit and are described in the JUnit Cookbook. Using Clover with Ant and JUnit 6. Instructions for installing Clover can be found in the Installation Options section. Junit is already included within the Clover Tutorial. under the 'tutorial' directory. It is also assumed that you have a basic understanding of JUnit. In the 'tutorial' directory you will find the initial build file and the directory 'src' which contains the java files that you will be testing. It is split into three parts covering Current Reports.java file contains all the unit tests for the library and utilises the JUnit framework. They represent a simple library for dealing with money and provide methods to add.Clover 2. Page 76 Copyright © 2002-2004 Cenqua Pty Ltd. The Clover tutorial assumes that you have basic knowledge of creating and modifying Ant build files. The Clover Tutorial describes different features of Clover in a step-by-step approach. Using Clover with Ant and JUnit This tutorial demonstrates how you can use Clover with JUnit to measure the code coverage of a project.1. The tutorial work area The source files for this tutorial are located in the standard Clover distribution.1. and Ant installed on your system. The MoneyTest. Historical Reports and Advanced Features. Once you've completed the Tutorial. Before you start You will need Clover. It takes you through the process of compiling a sample project and running the unit tests from Ant. . A good introduction to JUnit can be found in the JUnit Cookbook. and collect money etc.0a5 User Manual 6. have a look at Using Clover Interactively and Using Clover in Automated builds for examples of how to pull the different aspects of Clover together for your project. Instructions for installing Ant can be found in the Apache Ant User Manual. The Apache Ant User Manual provides any additional support you may require in this area. All rights reserved. preferably the latest versions. subtract. This Clover tutorial is crafted around the example code described in the Cookbook.1. then modifying the build file to add Clover targets and properties.

All rights reserved. This tutorial covers the initial creation of coverage data before stepping you through how to generate and interpret coverage reports. running and cleaning the build.Clover 2. In the tutorial directory you will find the initial build file which contains targets for compiling. Compiling and running In this step we will compile the library and run the tests against it without using Clover to check that everything is working correctly before including Clover in the next step.1. Output should be similar to the following: $ ant code. In this tutorial we will be compiling and unit-testing the Money library provided in the tutorial/src directory.Measuring Coverage in the tutorial. then using Clover to determine how well the unit tests actually test the library. you are ready to progress to Part 1 .2.Measuring coverage with Clover Introduction Part 1 of this tutorial focuses on the creation and interpretation of 'Current' Clover reports.0a5 User Manual Start the tutorial Once you have Ant installed and the Clover for Ant package have been downloaded. In the first step. 6.compile Buildfile: build. Compiling To compile the java files use the command ant code. Part 1 .compile. . This section covers the very basic features of Clover and is an important first step for all users. We'll then look at how to improve the coverage achieved by tests and regenerate the coverage reports. we will compile the Money library and run tests against it. Current reports display graphical and numerical data relating to the most recent coverage data collected for the project.xml code: [mkdir] Created dir: c:\clover\tutorial\build [javac] Compiling 4 source files to c:\clover\tutorial\build BUILD SUCCESSFUL Total time: 9 seconds Page 77 Copyright © 2002-2004 Cenqua Pty Ltd.

All rights reserved.jar}"/> Note: This assumes that the clover. The test results are formatted as xml and written to the build/testresult directory. We have now compiled the Money library.jar elsewhere.0a5 User Manual This shows that the java source files have been compiled and the class files have been placed in the c:\clover\tutorial\build directory. Note: The test target uses the junit ant task.jar" location=".run.xml test: [junit] Running MoneyTest [junit] Tests run: 22./lib/clover.jar"/> <taskdef resource="cloverlib. Errors: 0.run Buildfile: build. Adding Clover task definitions Load the build. Output should be similar to the following: $ ant test. Adding Clover targets Now that we've compiled the code and run unit tests. and run tests against it. Page 78 Copyright © 2002-2004 Cenqua Pty Ltd.xml file into your favourite text editor and add the Clover Ant task and type definitions: <property name="clover. Clover's report task uses these result files to integrate test results with the coverage report.Clover 2.052 sec BUILD SUCCESSFUL Total time: 1 second This shows that all the tests have been run and have passed.jar is left in the unpacked Clover distribution from which this tutorial is being done. Running the tests To run the JUnit tests use the command ant test. adjust the path accordingly. . Firstly we need to add a target to enable and configure Clover for the build. If you've installed the clover. we'll add Clover targets and properties to the build file to enable measurement of code coverage. Failures: 0. In the next step. Modifying the build file is trivial. we are ready to add Clover targets and properties to the build file so we can measure the code coverage of the tests. Time elapsed: 0.xml" classpath="${clover..

jar}"/> <pathelement path="${app. add the line in bold below to the build. Compile with Clover Ensure that your build has been cleaned by running ant clean.clover Page 79 Copyright © 2002-2004 Cenqua Pty Ltd. Adding a target to enable Clover Add a target called with.build}"/> </path> Adding <clover-clean> to the Clean Target Its advisable that the <clover-clean/> task is added to the clean Target.0a5 User Manual These lines define the Clover Ant tasks which can then be used within the build file.clover which will enable and configure Clover for a build: <target name="with. <target name="clean" > <delete dir="build"/> <clover-clean/> </target> Once you've made these changes.xml file. you can save the build. All rights reserved.classpath Ant path: <path id="build. To achieve this. but first we'll re-compile the Money library with Clover and re-run the tests to obtain coverage data.jar}"/> <pathelement path="${junit. This deletes all class files from previous compilations. Compile your code with Clover using the command ant with.clover"> <clover-setup/> </target> Adding Clover to the build classpath The clover.Clover 2. .classpath"> <pathelement path="${clover. This will delete the Clover database when the clean target is executed. Testing with Clover We are now ready to measure the coverage of the tests over the Money library. We will add some more Clover targets later to perform coverage reporting.jar needs to be in the runtime classpath when you execute the tests.

built on . built on . Clover all over. .346 sec BUILD SUCCESSFUL Total time: 1 second During this test run.clover\clover2 code: [mkdir] [javac] [clover] [clover] [clover] [clover] [clover] Created dir: c:\clover\tutorial\build Compiling 4 source files to c:\clover\tutorial\build Clover Version 2.compile Buildfile: build.clover: [clover-setup] Clover Version 2. [clover-setup] Clover is enabled with initstring 'c:\clover\tutorial\. Loaded from: c:\ant\lib\clover.3 source level.0a5 User Manual code. Clover measured the code coverage of the tests and wrote the coverage data to disk. Running the tests We now need to run the tests again (with the command ant test.run Buildfile: build. Time elapsed: 0.xml test: [mkdir] Created dir: c:\clover\tutorial\build\test [junit] Running MoneyTest [junit] Tests run: 22. As part of the instrumentation process. The result of this process is that your source files have been instrumented by Clover and then compiled as usual.X.X.jar Site License registered to . Creating a report Page 80 Copyright © 2002-2004 Cenqua Pty Ltd.clover code. All rights reserved. Output from Ant will be the same as a normal test run: $ ant test. Processing files at 1... Instrumented 4 files. In the next step we'll generate a coverage report from this data to see how well the tests actually cover the Money library. Errors: 0..run)....Clover 2.xml with. This will run the tests. You will get output similar to the following: $ ant with.compile. Failures: 0. Clover creates a database that will be used during the coverage recording and report process. this time measuring coverage.

report: [clover-html-report] [clover-html-report] [clover-html-report] [clover-html-report] [clover-html-report] [clover-html-report] BUILD SUCCESSFUL Total time: 1 second Page 81 Copyright © 2002-2004 Cenqua Pty Ltd. built on .clover\clover2 Clover Version 2.result}" title="Clove </target> The <clover-html-report> task is a simplified version of the <clover-report> task.0a5 User Manual We are now ready to produce a coverage report. For information on how to generate a pdf report see: <clover-pdf-report> or for other types of Clover reports see the <clover-report> task...report" depends="with.Clover 2. Clover is enabled with initstring 'c:\clover\tutorial\.xml. Historical reports. processed 22 slices in 22ms (1ms per pair) Writing report to 'c:\clover\tutorial\clover_html' Done.. The output directory clover_html is relative to the path of the Ant build file. In this case.. This section will focus on producing a Clover HTML report. Adding a Clover report target Open the build. written to the directory clover_html and with the title Clover demo.x.clover"> <clover-html-report outdir="clover_html" testresultsdir="${test.x. are discussed later in this tutorial see Tutorial Part 2. The test results produced while running junit in the previous step are read from build/test. Processed 1 packages. You will get output similar to the following: $ ant clover.report with..xml file in a text editor and add the following target to create a HTML report: <target name="clover.. The current report is to be in HTML format. Loaded from: c:\ant\lib\clover. clover. . As no historydir attribute has been specified it uses the current coverage data. task Generating the report Create a HTML report with the command ant clover.report. Loaded from: c:\ant\lib\clover. the directory clover_html will be nested within tutorial as this is the location of build..jar Site License registered to . built on .. All rights reserved.jar Site License registered to .clover: [clover-setup] [clover-setup] [clover-setup] [clover-setup] Clover Version 2. which show the progress of coverage over the life of the project.

private Money f21USD. One method in the Money library that is not fully covered is the equals() method in the Money class (lines 40-42 as seen below). Line 40 has been executed 27 times but since it has never evaluated to true it has not been fully covered and is therefore in red. private Money f0USD. . Click here for details about interpreting this coverage report. private Money f14CHF. You should certainly aim to cover all of the code that will be executed under normal operation of the software. Although not always possible. To do this. Declare the variable f0USD: public class MoneyTest extends TestCase { private Money f12CHF.0a5 User Manual You can now view the report by opening the file tutorial/clover_html/index. It follows then that the two successive lines have never been executed. make the following additions (shown in bold) to the MoneyTest.java file. . you'll notice that coverage is not 100%.. The first few lines of this method handle the special case when the Money value is zero. The coverage report shows that the code to handle this has not been covered by the tests.. lines not covered in money class We can now improve the tests so that this section of code is covered. All rights reserved.Clover 2. it is best to get as close to full coverage as you can. private Money f7USD.html in a web browser. Think of it this way: every line that isn't covered could contain a bug that will otherwise make it into production. Page 82 Copyright © 2002-2004 Cenqua Pty Ltd. Improving coverage After having a look at the coverage report.

All rights reserved. f0USD = new Money(0. this section demonstrates how to set up the relevant Ant target and run the command so that a history point can be created. In the first step. assertTrue(f0USD.equals(null)).report). In the meantime. "CHF").1. . "CHF").compile ) and run the tests again (by running ant test. f21USD = new Money(21. f7USD = new Money( 7. it is possible to compare code coverage and metrics by viewing results in a single Clover report and enabling you to track the development of your project. You will see that the Money class now has 100% coverage. } After these amendments have been made. clean and then compile (by running ant clean with. we'll edit the Ant build file to generate a History Point. The generation of historical reports is discussed in later sections. "USD").3. 6. This tutorial covers the generation of a set of historical data. Adding a history point target Page 83 Copyright © 2002-2004 Cenqua Pty Ltd.Clover 2.clover code.0a5 User Manual Initialise f0USD in the setUp() method: protected void setUp() { f12CHF = new Money(12. Finally.equals(equalMoney)). f14CHF = new Money(14. By running tests with Clover over time and creating a series of history points.Historical Reporting Introduction Part 2 of this tutorial focuses on the creation and interpretation of 'Historical' Clover reports. Creating history points A history point is a snapshot of code coverage and metrics data for the project at a particular point in time. the following test needs to be added: public void testMoneyEqualsZero() { assertTrue(!f0USD.. Part 2 . "CHF"). . IMoney equalMoney = new Money(0. "USD"). interpretation of the information displayed in the Historical reports and customisation of the reports for your particular reporting preferences. Historical reports display graphical and numerical data relating to sets of coverage data collected over time for the project.. "USD").run) and then re-generate the HTML report (by running ant clover.

The value of historyDir is the directory where the history points will be stored. [clover-historypoint] Writing report to 'C:\tutorial\clover_history\clover-20030307111326. Run the command ant record. Recording a history point Ensure that the source code has been instrumented and the tests run with the commands ant with.clover: record. built on .xml file: <target name="record.clover"> <clover-historypoint historyDir="clover_history"/> </target> When this target is run. All rights reserved. Generating historical data In Part 1 of the tutorial we made additions to the testing suite to improve code coverage.x. If you wish to override the timestamp value of a history point.point" depends="with. .0a5 User Manual Add the following target to your build. recording Clover history points along the way. You should create this directory before executing this target.xml' [clover-historypoint] Done.point. a history point will be created with the timestamp value of the coverage run..xml with.clover code and ant test respectively. [clover-historypoint] Merged results from 2 coverage recordings. Note: By default Clover records the history point with a timestamp of the coverage run. Output should be similar to the following: $ ant record.. See documentation for the <clover-historypoint> task for details. In order to show the historical reporter in use.Clover 2. BUILD SUCCESSFUL Total time: 2 seconds In the next step we'll add more tests to improve coverage of the Money Library.point: [clover-historypoint] Clover Version 1. you can add date and dateformat attributes to the task allowing you to reconstruct coverage history.point Buildfile: build. we will now continue to add tests and Page 84 Copyright © 2002-2004 Cenqua Pty Ltd.

private Money f0CHF.equals(expected)).create(f12CHF. assertTrue(fMB3. . however there are several sections of code that remain untested in the MoneyBag.. f21USD).equals(null)). "CHF"). "CHF").create(f14CHF. fMB3 = MoneyBag. This section will focus on bringing the coverage of this class to 100% as well as creating historical data in the form of history points. private Money f21USD. private Money f14CHF. f21USD = new Money(21. f0USD). f7USD = new Money( 7. Then record a new history point by Page 85 Copyright © 2002-2004 Cenqua Pty Ltd. .create(f0CHF.create(new Money(0. private IMoney fMB2. private IMoney fMB1.java file.. All rights reserved. Open the source file MoneyTest. f14CHF = new Money(14. reinstrument and test your code by running ant with. f0USD = new Money(0. private Money f0USD..Clover 2. new Money(0. "USD").java in your favourite text editor and make the following additions shown in bold: Declare the variables f0CHF and fMB3: public class MoneyTest extends TestCase { private Money f12CHF. "CHF"). "USD"). "USD")). "CHF"). . f0CHF = new Money(0. "USD"). fMB1 = MoneyBag.clover code and ant test respectively. private IMoney fMB3.java file is at 100% coverage. f7USD). private Money f7USD. IMoney expected = MoneyBag. Add the following test: public void testMoneyBagEqualsZero(){ assertTrue(!fMB3. Initialise f0CHF and fMB3 in the setUp() method: protected void setUp() { f12CHF = new Money(12.. The Money. } After making the above changes.0a5 User Manual periodically record history points which will later be used as code coverage and metrics data by the historical reporter. fMB2 = MoneyBag.

All rights reserved. When the <format> element is omitted. a PDF report is produced by default.clover"> <clover-report> <historical outfile="historical. Clover will capture the new state of code coverage and metrics for comparison with past or future runs. } Once again.create(new Money(2.html target defined in Part 1. the next step is to add a target to the build file which will call the historical reporter and generate a historical report. "CHF"). new Money(2. Add a historical report target Add the following target to build.Clover 2. The main differences are that the nested element specifies <historical> rather than <current> and there is no specification of the output format as html. reinstrument your code. .0a5 User Manual running ant record. Page 86 Copyright © 2002-2004 Cenqua Pty Ltd. assertEquals(expected.report" depends="with. "USD")).equals(fMB3)). } public void testVectorSize(){ IMoney other = MoneyBag. The historical reporter needs to be able to find the coverage history files in order to create the report so the historyDir value must be the same as the historyDir defined for the history points.xml: <target name="hist.pdf" historyDir="clover_history"/> </clover-report> </target> The hist. The next section discusses how to generate a Clover historical report which will display the historical data that has been collected.report target is similar to the report. The <format> element is optional and is not included in the example above. We have now created a series of history points for the Money library.toString()). By recording a history point now. assertTrue(!other. test and record a new history point. Add the following tests to bring the coverage of the Money project to 100%: public void testToString(){ String expected="{[12 CHF][7 USD]}". Creating historical reports Now that we have recorded several history points. The format of the report can be either PDF or HTML as specified by the <format> element. fMB1.point.

Output should be similar to the following: $ ant hist.report. built on .pdf' Read 3 history points. To create an html report.pdf' Merged results from 2 coverage recordings.html: <target name="hist. Done. add a nested <format> element with type specified as html to your <clover-report> element.. Writing report to 'C:\tutorial\historical. Done. Changing output format The default historical report type is PDF although an html report can also be produced. the historical reporter is highly configurable and this section will detail some of the options you can use. To interpret this history report click herefor more details. Writing historical report to 'C:\tutorial\historical.x.pdf in a PDF viewer such as Adobe Acrobat Reader..0a5 User Manual Depending on the chosen format. In addition to basic reporting.report. All rights reserved. Processed 1 packages.xml with.report Buildfile: build. Customising historical reports In the previous sections of this tutorial we've looked at how to create and interpret a basic historical report. or the name of a directory (in the case of the HTML format). For a full list of the report configuration options see the documentation for the <clover-report> task. Generating a historical report Create a historical report by using the command ant hist.report: [clover-report] [clover-report] [clover-report] [clover-report] [clover-report] [clover-report] [clover-report] Clover Version 1.xml file and executing the command ant hist. BUILD SUCCESSFUL Total time: 8 seconds The report can now be viewed by opening the file tutorial/historical.clover"> <clover-report> <historical outfile="clover_html/historical" title="My Project" Page 87 Copyright © 2002-2004 Cenqua Pty Ltd.Clover 2.report. Try adding the following target to your build.clover: hist. .html" depends="with. the outfile value may represent a single file as in the case of the PDF format.

All rights reserved. <metrics> and <movers>. while the default elements for the metrics chart are loc.report.pdf" title="My Project" historyDir="clover_history"> <coverage include="total"/> <metrics include="methods. methods and classes.Clover 2.xml file as an example: <target name="hist.clover"> <clover-report> <historical outfile="histSelect. By using the include attribute you can specify the required configuration: <target name="hist. packages"/> Page 88 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual historyDir="clover_history"> <format type="html"/> </historical> </clover-report> </target> A custom title can also be displayed for your report by using the title attribute in the <historical> element as above. ncloc.clover"> <clover-report> <historical outfile="histCoverage. Try adding the following target to your build. <coverage>.report. Chart Configuration The 'Coverage over time' and 'Metrics over time' charts also allow you to choose which metrics information should be included.pdf" title="My Project" historyDir="clover_history"> <overview/> <coverage/> </historical> </clover-report> </target> The above code will produce a historical PDF report with the title 'My Project' which includes only two sections: the 'Overview' and the 'Coverage over time' charts. The default reporting mode is to include all four report elements: <overview>. Chart Selection The historical reporter allows you to specify which charts to include in your report and also allows you to configure further options in the charts themselves. But to include some and not the others is a simple matter of nesting the desired elements within the <historical> element. methods and total. . The default elements for the coverage chart are branches.coverage" depends="with. statements.select" depends="with.

and the same for the losers. Add the following target to your build.1.report.clover"> <clover-report> <historical outfile="histMovers. then the classes with the biggest percentage point gain will be displayed. and the initial valuation point for class coverage is 2 weeks prior to the most recent history point. Should there be greater than 20 gainers in this period. a maximum of 20 gainers and 20 losers can be displayed.0a5 User Manual </historical> </clover-report> </target> This will produce a PDF file with the filename 'histSelect.Clover 2. . perhaps the unintended result of changes to the unit test suite. Part 3 .Advanced Features Page 89 Copyright © 2002-2004 Cenqua Pty Ltd. You can also specify whether or not a chart uses a log scale by adding the logscale attribute: <metrics include="methods.4.xml file as an example of this feature in use: <target name="hist. The next section of this tutorial will discuss how you can automate the coverage checking of your project. the configuration values selected state that classes must have a change in coverage of at least 5 percentage points to be included in the chart.pdf' with two sections: the 'Coverage over time' chart with total coverage information. the maximum number of gainers and losers to display and the period across which the gains and losses are calculated. 6. All rights reserved. packages" logscale="false"/> 'Movers' Configuration The 'Movers' section of the historical report shows you the classes whose coverage has changed the most recently. See Interval Format for details on the syntax for specifying interval values.movers" depends="with.pdf" title="My Project" historyDir="clover_history"> <movers threshold="5%" range="20" interval="2w"/> </historical> </clover-report> </target> In this case. The 'Movers' chart allows you to specify the threshold of point change a class must satisfy. and the 'Metrics over time' chart with method and package information. This is useful for spotting classes that have had sudden changes in coverage.

• Automating coverage checking Automating coverage checking 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. output will be similar to the following: $ ant clover.xml with.check Buildfile: build.check Buildfile: build.check: [clover-check] Merged results from 1 coverage recording.xml Page 90 Copyright © 2002-2004 Cenqua Pty Ltd. .clover: clover.check" depends="with. It is easily integrated into your build system. All rights reserved. Adding coverage checking Ensure that you have current Clover coverage data so that you can check the coverage percentage for your project. If your test coverage satisfies the target coverage percentage.check to run the check. Add the <clover-check> task to your build by specifying a target similar to the following: <target name="clover. [clover-check] Coverage check PASSED. you'll get something like this instead: $ ant clover.0a5 User Manual Introduction This section looks at some advanced features of Clover.clover"> <clover-check target="80%"/> </target> This configuration sets an overall project target of 80% coverage Use the command ant clover. Clover coverage data is generated as described in Part 1 of the Tutorial.Clover 2. BUILD SUCCESSFUL Total time: 2 seconds If your coverage percentage does not reach the coverage target.

clover: clover.Clover 2.clover"> <clover-check target="80%" failureProperty="coverageFailed"/> </target> In this case.haltonfail" depends="with. <target name="clover. This allows you to check the value of this property in other Ant targets and manage the outcome accordingly. after the message has been written to output. For an example on managing the resulting actions for a project which does not meet its coverage target see Using Clover in Automated Builds. The default for haltOnFailure is false.check. Coverage check FAILED The following coverage targets were not met: 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. Failing the build if coverage criteria not met In the above situation where the target is not met. the property coverageFailed will have its value set to the coverage summary message "Overall coverage of *% did not meet target of 80%". the build for the specified target will continue as normal.check: [clover-check] [clover-check] [clover-check] [clover-check] Merged results from 1 coverage recording.java file to create a situation where the code coverage does not reach 80%. if the coverage does not reach 80%. This is done by adding nested Page 91 Copyright © 2002-2004 Cenqua Pty Ltd. which comes in useful if you have certain packages that have more or less stringent coverage requirements than the rest of the project.0a5 User Manual 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. 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. try commenting out some of the tests in the MoneyTest.setproperty" depends="with. . Adding Package-level coverage criteria The <clover-check> task also allows you to specify the desired percentage covered for different packages. All rights reserved.

See Coverage Contexts for more information.clover"> <clover-check target="80%"> <package name="com.nocatch" depends "with.example. All rights reserved.clover. <target name="clover.packages" depends="with.Clover 2.check. Page 92 Copyright © 2002-2004 Cenqua Pty Ltd.two" target="40%"/> </clover-check> </target> Context filtering The <clover-check> task allows you to prescribe a filter that excludes coverage from certain block-types from overall coverage calculations.0a5 User Manual 'package' elements like the following: <target name="clover. The filter attribute accepts a comma separated list of the contexts to exclude from coverage calculations.clover.check.one" target="70%"/> <package name="com.example.clover"> <clover-check target="80%" filter="catch"/> </target> This will run clover coverage percentage check as normal but will calculate coverage with omission of all 'catch' blocks. .

Selecting one of these classes will bring up the source code in the frame on the right. All rights reserved.Clover 2.java source file with the green and red bar at the top showing the amount of code coverage on this class. In the top left hand corner is the list of packages. Depending on the current selection. file or project overview which is currently selected. The screenshot below shows the generated HTML report in a browser. Clicking on the name of a package will bring up the relevant classes in the frame below it. You can view all classes in the project or select a particular package to view. The method. . Number of Classes. Interpreting the report We will now look at how to interpret the HTML report. Number of Methods.1. Number of Non-commented Lines of Code (NCLOC).0a5 User Manual 7. the metrics include all or a subset of: Number of Lines of Code (LOC). The header provides summary information relating to the current project. The screenshot shows the report for the Money. statement and conditional coverage percentages are beside this. Number of Files and Number of Packages. Page 93 Copyright © 2002-2004 Cenqua Pty Ltd. The left hand side displays the report title and the time of the coverage contained in the report. For current reports the timestamp is the timestamp of the most recent run of tests. How To 7. The right hand side of the header displays metrics for the package.

0a5 User Manual coverage measured for the Money class The left-most column shows line numbers. If a line is never executed or has only been partially executed. .java source file: Page 94 Copyright © 2002-2004 Cenqua Pty Ltd. the entire line of code will be highlighted in red. As you can see. lines 15-17 have been run 156 times by the JUnit tests. The following screenshot shows the coverage on a section of the MoneyBag.Clover 2. The second column shows the number of times a particular line has been executed during the test run. All rights reserved. whereas line 28 has only been run twice. Depending on your browser. you can hover the mouse over a line to get a popup describing in detail the coverage information for that line.

Clover 2. . This is also the case with lines 58 and 59. This highlighting feature makes it easy for you to see which parts of the code have not been fully exercised by your tests so that you can then improve testing to provide better code coverage.2. If any of the lines shaded red contained a bug. are highlighted. and the following two lines. they may never be detected because the tests as they are don't test those parts of the code. Therefore it. In the next step. 7. the method isZero() has never evaluated to true so it has not been fully tested. When you view the report you should see a picture similar to the Page 95 Copyright © 2002-2004 Cenqua Pty Ltd. All rights reserved. Interpreting historical reports We will now look at interpreting the report that you generated by enabling the report in an appropriate viewer. we will enhance the JUnit tests to improve code coverage of the Money library.0a5 User Manual code not executed Although line 52 of the above MoneyBag class has been executed 14 times.

Below this header is the Project Overview Chart which shows the branch. method and total coverage for each history point and plots them against time in an easy-to-read chart. the historical report begins with a header containing relevant project information. All rights reserved. Page 96 Copyright © 2002-2004 Cenqua Pty Ltd. Like the 'current' report. although it is likely that the the graphs that you produce will contain different values. This includes the report title. statement. the project metrics and the period for which history points are included in the report. .Clover 2. method and total coverage percentages for the project for the most recent history point included in the report.0a5 User Manual screenshot below. The 'Coverage over time' graph shows the percentage values of branch. statement.

All rights reserved. It is therefore possible to observe changes in metrics such as the number of methods. Page 97 Copyright © 2002-2004 Cenqua Pty Ltd.0a5 User Manual historical chart overview and coverage The 'Metrics over time' graph shows the project statistics for each history point plotted against time.Clover 2. In the example below. . the number of methods can be seen shown in green.

Clover 2. 'Movers'. In this case there have not been any classes which have lost more than 1 percentage point coverage.6 percentage points coverage over the two latest history points. hence the only item displayed here is the Money package which has gained 10. The tutorial will discuss how you can customise many aspects of the historical report. the default being 1 percentage point over the two latest history points. All rights reserved.0a5 User Manual metrics and movers The final section. Page 98 Copyright © 2002-2004 Cenqua Pty Ltd. displays classes that have increased or decreased in coverage by more than a specified percentage point threshold over a particular time interval. .

You will achieve the greatest increase in overall project coverage by covering the largest.2. and the other via the font color. One metric is displayed via the font size.3. yet are the least covered by your tests. Note: Tooltips on each class name provide you with the real values for each metric. The larger and redder the class. the greater the risk that class poses for your project. Metric Average Method Complexity % Coverage Attribute Font Size Font Color 7. Each Coverage Cloud displays two metrics per Java Class. reddest classes first. Coverage Clouds Coverage Clouds provide an instant overview of your entire project enabling you to identify areas of your code that pose the highest risks or shortcomings. Metric Number of Elements Number of Elements Untested Attribute Font Size Font Color Page 99 Copyright © 2002-2004 Cenqua Pty Ltd.3. Quick Wins This Cloud highlights the "low hanging coverage fruit" of your project.3. Project Risks The Project Risks Cloud highlights those classes that are the most complex. 7. Classes are sorted alphabetically.0a5 User Manual 7. Each attribute has relative weighting across the entire project.Clover 2. All rights reserved.1. .

eg. All other units are exact. Miscellaneous 8.0a5 User Manual 8. . 11m 2h 365d 10w 24mo 5y If no time unit is provided the default unit of "days" is used.Clover 2. In general. Numeric values may be fractional (eg. 5.6). Note: Due to the variable lengths of months and years. A month is considered to be 30.1. the first letter is sufficient to indicate the interval unit. All rights reserved. A numeric value must always be provided or an exception will be thrown. approximations are used for these values within Clover. Interval Format The interval type is used to specify a period of time. It consists of a value and a unit specifier. the previous example could be written as "3 d". The time ranges supported are specified in the following table Unit specifier second minute hour day week month year s m h d w mo y Abbrev.346 days and a year is considered to be 365. 3 seconds 5 minute 4 hours 7 days 4 weeks 5.6 months 100 years Example Values 20s 7 min. Page 100 Copyright © 2002-2004 Cenqua Pty Ltd. "3 days". The Interval type is very flexible about how it interprets the time unit. For example.232 days.