The Clover Eclipse Plugin allows you to instrument your Java code easily from within the Eclipse Java IDE, and to view your coverage results inside Eclipse.

Please be aware of the following when using this version of the plugin.

• This plugin may not work correctly if you have configured your Eclipse project so that the Java source and output directories are the same.
• When compiling your Java project with the Clover plugin, you must add and use a Java Development Kit (JDK) to your list of Installed JRE locations, or give the Clover plugin a JDK_HOME override value. (see below).
• This plugin will not work with WebSphere Studio Application Developer v5.0 (WSAD v5.0 is based upon Eclipse 2.0.2).
• There have been some reported problems when using the plugin with WSAD J2EE projects, where the build-path contains .JARs that are embedded in an .EAR or .WAR. This issue is being investigated and a fix is slated for the next release.

1 Locating your Eclipse plugin directory

You will need to locate where you installed Eclipse on your system. The rest of this document will refer to this location as ECLIPSE_HOME.

2 Removing previous versions of the plugin

It is important to remove previous version of the Clover Eclipse plugin.

• Go to to the ECLIPSE_HOME/plugins directory.
• Remove any directory named com.cenqua.clover*

3 Installing the plugin

• Once you have downloaded the Clover Eclipse plugin .zip file, extract it to a temporary location on your drive. This will create a directory named com.cenqua.clover_x.x
• Copy this directory to the ECLIPSE_HOME/plugins directory. That is, you should end up the directory ECLIPSE_HOME/plugins/com.cenqua.clover_x.x

4 Installing the license

• If you don't have one already, you will need to download a clover.license file to activate the plugin. A free evaluation license is available from here.
• Copy the clover.license file into the ECLIPSE_HOME/plugins/com.cenqua.clover_x.x directory.

5 Start Eclipse

Next time you start Eclipse, the Clover plugin will be available.

Setting up a JDK

There are two ways to instruct the Clover plugin which JDK it should use.

1. Set a JDK_HOME override setting on a per-project basis. In the Compilation tab of the Clover section of your Project properties, enter a value such as "C:\j2sdk1.4.2" into the JDK_HOME override field.
2. Globally choose a JDK instead of a JRE as your Default JRE.
   • In Eclipse, choose "Windows | Preferences" then select "Java / Installed JREs".
   • Click "Add..." and enter the path to your JDK in the "JRE home directory" field. For example, enter "C:\j2sdk1.4.2".
   • Choose a name (such as "JDK1.4.2") and click "OK".
   • Ensure you have this JDK checked as the default build JRE.

Activating the Clover Eclipse plugin

The Clover Eclipse plugin can be activated in any Eclipse project when using the Java (JDT) perspective.

• Open up the project's properties, by using "Project | Properties" or right-clicking on the project in the Package Explorer.
• Select the "Clover" page.
• Toggle the "Enable Clover plugin in the project" checkbox. You can leave the Clover options at the defaults for now.
• When you hit OK, the Clover Viewer tool should appear on your workbench.

The Clover Viewer tool

The Clover Viewer tool allows you to control Clover's instrumentation of your Java projects, and shows you the coverage statistics for each project. The tree shows the package and class coverage information for each project. Summary statistics are displayed below the tree for the selected project/package/class.

The Clover Viewer is automatically added to the workbench when you enable Clover for your project. If the viewer is closed, you can open it again using "Window | Show View | Other..." and selecting "Clover | Clover View".

The viewer allows the following actions:

• Show coverage. Toggles the display of coverage information in the Java editors and in the Tasks list.
• Refresh Coverage Data. Re-loads from disk the Clover coverage data for the selected project.
• Delete Coverage Data. Deletes the recordered coverage data for the selected project.
• Compile with Clover. Toggles the use of Clover instrumentation when Eclipse compiles the selected Java project.
• Context Filter.... Allows you to specify what coverage contexts are shown in the Java Editor.
• Generate Report.... Launches the report generation wizard that will take you through the steps required to generate a Pdf, Html or Xml. report.
• Use Clover WorkingSet. Toggles the use of the Clover WorkingSet. This limits the files Clover will consider when instrumenting and when showing coverage data. This is particularly useful for large projects.
• Edit WorkingSet. Brings up a dialog for editing the Clover WorkingSet.
• Clear WorkingSet. Empties the Clover WorkingSet. This means Clover will not consider any files while "Use Clover WorkingSet" is enabled.

Viewing Coverage Results

The Clover Eclipse plugin allows you to view Clover coverage data within the Eclipse IDE. This may include coverage data created using Clover external to the Eclipse IDE, or coverage data generated by the Clover Plugin internal to Eclipse.

The Clover plugin shows coverage data in three ways:

• As a marker in the overview bar (right-hand side). This marker has a tooltip indicating the coverage problem.
• As a marker in the vertical ruler (left-hand side). This marker has a tooltip indicating the coverage problem.
• As a warning item in Eclipse Tasks list. If you do not want coverage warnings to appear in the task list, you can filter them out using the Tasks list filter preferences. Note that warnings associated with a file will appear in the Tasks list only for those files that are currently opened by an editor.

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.

Online help

The Clover Eclipse plugin includes help documentation integrated into the Eclipse help system.

Deactivating the Clover Eclipse plugin

You can disable Clover instrumentation using the "Compile with Clover" button, and you can prevent coverage information from being displayed in the Java editors by toggling the "Show Coverage" button.

But if you want to completely de-activate Clover support in a project, then un-check "Enable Clover plugin in the project" on the Clover page of the project's properties dialog.

Disabling Clover in this way will require a full rebuild of that project. If this is undesirable then you can simply toggle the "Compile with Clover" and "Show Coverage" options.

The Clover Eclipse plugin's configuration can be accessed in two places; a) from the "Clover" page of a project's properties dialog (Project | Properties), and b) from the "Clover" page of the workspace preferences (Window | Preferences).

Project Properties - Instrumentation Options

These options control how Clover instrumentation works when "Compile with Clover" is selected.

Initstring

This controls where the Clover plugin stores (and looks for) the coverage database. You may want to specify a "User specified" value if you want to view Clover coverage data generated external to the Eclipse IDE.

Flush Policy

The Flush Policy controls how Clover writes coverage data to disk at runtime. "Directed" is the default an means coverage data is written to disk when the JVM exists. "Interval" allows you to specify that coverage data should be written out at regular intervals. See Flush Policies.

Filtering Includes/Excludes

If you do not want all of your source instrumented, then you can control which this using these two Ant patternsets. For example, you may prevent instrumentation of files in the "remote" package using an "Excludes" value of **/remote/*.java.

Project Properties - Compilation Options

These options allow you to specify how Clover will compile your instrumented files.

Fork compiler into separate JVM

If enabled, Clover will launch a separate JVM to compile your instrumented files.

Heap size of compiler JVM

The heap size of the forked JVM (in MB). Leave blank to use the default.

Project Properties - Filter Options

These options allow you to define custom coverage filters.

Name

The name for this context. Must be unique, a valid java identifier and not be one of the reserved context names

Type

The type for this context. A method context type matches against method signatures, and a statement context type against statement signatures.

Regexp

A Perl 5 Regexp that defines the context. This regexp should match the signatures of the method/statement you wish to include in this context. Note that when signatures are tested against this regexp, whitespace is normalised and comments are ignored.

Clover Preferences

Deleting existing coverage data

When your rebuild a project, Clover will ask you whether you want to delete the existing coverage information. This section allows you to specify what the default action should be, and whether Clover should prompt you at all.

Automatically refresh coverage data

If enabled, the plugin will check for updated coverage data at the frequency given below. If it is not enabled, then you will need to use the "Refresh Coverge Data" button to see newer coverage data.

Span

The span attribute allows you to control which coverage recordings are merged to form a current coverage report. For more information, see Using spans

It is common for developers to work in different ways when working on an extremely large project compared to small/medium sized projects. For example, doing a complete rebuild then running all the unit tests can take hours for some projects. For this reason, some developers may want to focus only on a few files or packages at a time. The Clover Eclipse plugin has a Working-Set mode to assist in this style of development.

The Clover Working-Set

Eclipse has an inbuilt concept of a Working-Set, which allows you to specify a subset of the Workspace that you want to consider. Clover can use one of these Working-Sets to:

• Limit the files that will be instrumented by the Clover plugin.
• Filter the files/packages/directories for which Clover will display coverage information. This includes filtering the coverage statistics. For example, Clover will report 100% coverage if just all the files in the Working-Set are covered.

The Clover Working-Set can be manipulated via the tool menu in the Clover Viewer and by the context menu on files, packages and projects.

Enabling the Clover Working-Set is a Workspace-wide setting; it affects all projects in Eclipse. If you have an "Excludes" setting on a project (in the Clover section of the Project Properties), then those files are excluded in addition to those excluded by the Working Set. Similarly, if you have an "Includes" setting, then only those files that are included in both this setting and the Working-Set are Instrumented by Clover.

For the sake of this example, let us assume that we want to remove all private methods from the coverage reports. How would we go about this?

• Open the configuration panel "Clover | Filters".
• Select the Add button to create a new Regexp Context Filter.
• Set the name to private.
• Since we are creating this filter to filter private 'methods', specify the Method type.
• We now need to define regular expression that will match all private method signatures. That is, a regexp that will match any method with the private modifier. An example of such a regexp is (.* )?private .*. Enter this regexp in the regexp field.
• When a filter has been newly created or edited, a (*) will be displayed next to its name. This indicates that the filter is currently 'unavailable' for use. To make this new filter available, you will need to run a clean build of your project. Once available, you will notice the private filter appear in the Context Filter Dialog. You will now be able to filter private methods out of your Clover coverage calulations and reports.

Q: Why, when doing a build, do I get an error dialog with the message "Clover build error. Error running javac.exe compiler"? Why do I need to configure a JDK instead of a JRE for my project?

In order to compile your instrumented source code, the Clover Plugin needs to find the "javac" command that comes with the JDK. The plugin does not use Eclipse's inbuild Java Builder.

Q: I've run my tests, but coverage information does not show in Eclipse.

You may need to press the Refresh Button in the Clover tool window.

Q: Why can I only see coverage data for the last test case I executed? Why does my coverage information disappear each time I compile a file?

By default, Clover will display the coverage information gathered since your last compile. 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).