Overview

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.

Using the plugin

Enabling Clover for your project

Clover can be enabled for any of your Java-based Eclipse projects.

1. From the Project Explorer view, right click on your Java project.
2. Select "Clover | Enable on this project". Alternatively you can enable Clover on multiple projects at the same time by selecting "Clover | Enable/Disable on..." and then selecting the projects to enable or disable.
3. With Clover now enabled, your project will now be automatically rebuilt. If you have upgraded from a previous version of Clover you may need to perform a clean build of all your Clover-enabled projects.
4. When enabling Clover on a project, the Coverage Explorer, Test Run Explorer and the Test Contributions views will all open automatically.
5. Select the Coverage Explorer view. This view is designed for horizontal placement but will also work well if placed vertically. You should see your project listed with 0% code coverage.
6. Select the Test Run Explorer view. The view is designed for horizontal placement but will also work well if placed vertically. As you have not executed any Clover-enabled tests, this view won't tell you anything interesting yet.
7. Select the Test Contributions View by selecting "Window | Show View | Other..." and selecting Clover > Test Contributions. The view is designed for vertical placement but will also work well if placed horizonally. As you have not executed any Clover-enabled tests, this view won't tell you anything interesting yet.

Screenshot: Enabling Clover in Eclipse

 
 Screenshot: Enabling/Disabling Clover on Multiple Projects

 

The Clover Coverage Explorer

The Coverage Explorer allows you to view and control Clover's instrumentation of your Java projects, and shows you the coverage statistics for each project based on recent test runs or application runs. It 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 | Coverage Explorer".

The main tree shows coverage and metrics information for packages, files, class and methods of any Clover-enabled project in your workspace. Clover will auto-detect which classes are your tests and which are your application classes - by using the drop-down box above the tree you can then restrict the coverage tree shown so that you only see coverage for application classes, test classes or both.

Screenshot: Clover Coverage Explorer

Columns

Initially the Coverage Explorer's tree displays the following four columns:

• Element - The name of the package, file, class or method.
• %TOTAL Coverage - The total coverage of the element as a percentage.
• Complexity - The cyclomatic complexity of the element
• Average Method Complexity - The average method complexity of the element

Clover supports 24 standard column types which can be chosen in the Coverage Explorer Column Chooser. The Column Chooser can be summoned by selecting "Columns..." in the Coverage Explorer view menu.

Screenshot: Coverage Explorer Column Chooser

Clover-for-Eclipse also lets your define your own custom columns for display within the Coverage Explorer tree. While choosing columns in the Column Chooser dialog, click the "New" button to summon the Custom Column Builder dialog. Custom columns must have a name and a valid Clover expression. Custom columns may be left, center or right justified and the value may be displayed as a decimal value or as a percentage value. Clover expressions can refer to any of the 24 standard columns; these references can be easily inserted into the expression by selecting "Insert..." and choosing the appropriate column name.

Screenshot: Coverage Explorer Custom Column Builder

Summary Panel

Summary metrics are displayed alongside the tree for the selected project, package, file, class or method in the tree. The following metrics are provided:

• Structure
  • Packages: The number of packages the project or package root contains
  • Files: The number of files the package, package root or project contains
  • Classes: The number of classes the file, package, package root or project contains
  • Methods: The number of methods the class, file, package, package root or project contains
  • Statements: The number of statements the method, class, file, package, package root or project contains
  • Branches: The number of branches the method, class, file, package, package root or project contains
•  Tests:
  • Tests: The total number of tests in the class, file, package, package root or project
  • Passes: The total number of passing tests in the class, file, package, package root or project
  • Fails: The total number of failing tests in the class, file, package, package root or project
  • Errors: The total number of tests with errors in the class, file, package, package root or project. Currently Clover does not differentiate between fails and errors and counts all errors as failures.
• Source:
  • LOC: The total number of lines of code in the class, file, package, package root or project
  • NC LOC: The total number of non-commented lines of code in the class, file, package, package root or project
  • Total Cmp: The total cyclomatic complexity of code in the method, class, file, package, package root or project
  • Avg Method Cmp: The average method complexity of the class, file, package, package root or project
  • Cmp Density: The complexity density of code in the class, file, package, package root or project

Actions and Menus

The viewer allows the following actions (from the view toolbar, menu or both):

• Enable/Disable Clover On... Allows you to select multiple project to enable or disable Clover for. This allows you, for example, to quickly turn Clover on for all projects in your workspace in one action.
• Refresh Coverage Data. Re-loads from disk the Clover coverage data for the selected project.
• Delete Coverage Recordings. Deletes the coverage recording data recorded from test runs or applications runs for the selected project.
• Compiled with Clover. Toggles the use of Clover instrumentation when Eclipse compiles the selected Java project.
• Edit Context Filter... Allows you to edit the block and custom coverage 'contexts' used to help you filter out unwanted coverage data. An explanation of what contexts are can be found here.
• Coverage in Explorer > Show for All Classes. Shows code coverage for all application and test classes in the Coverage Explorer.
• Coverage in Explorer > Show for Application Classes. Shows code coverage only for application (non-test) classes in the Coverage Explorer.
• Coverage in Explorer > Show for Test Classes. Shows code coverage only for test classes in the Coverage Explorer.
• Coverage in Editors > Show All. Shows red/green coverage areas in open Java editors. This is useful for finding out exactly which parts of the code are being covered.
• Coverage in Editors > Show Uncovered. Shows only red (uncovered) areas in open Java editors. This is useful for finding out exactly which parts of the code are not being covered while not cluttering your editor with the overwhelming large green areas (covered code).
• Coverage in Editors > Show None. Hides all red/green coverage areas in open Java editors.
• Enabled Clover Working Set. Enables or disables usage of the Clover working set. This filters the files, directories and projects that Clover will report on and are especially handy for large projects.
• Edit Clover Working Set. Allows you to edit the files, directories and projects in the Clover working set.
• Clear Clover Working Set. Removes all files, directories and projects from the Clover working set.
• Generate Coverage Treemap. Generates a mini report page in treemap format for the selected project. This report arranges package and classes enabling easy comparison of their complexity while also indicating their level of code coverage.
• Generate Coverage Cloud. Generates a report page in cloud tag format for the selected project. This lists classes considered project risks or quick wins.
• Generate Coverage Report... Launches the report generation wizard that will take you through the steps required to generate a PDF, HTML or XML. These reports can be generated for single or multiple projects.
• Hide Unavailable. This check button hides any elements in the Coverage Explorer's tree that don't have associated coverage information and helps reduce visual clutter. For instance, with this button checked any project that isn't Clover-enabled will not be shown in the Coverage View.
• Hide 100% Covered. This check button hides any elements in the Coverage Explorer's tree that have full coverage and helps you focus on only those classes that require more testing.
• Layout > Packages. Arranges the coverage tree by package. This is useful if you have a single source directory for your project.
• Layout > Package Roots. Arranges the coverage tree first by package root, then by package. This is useful if you have multiple source directories within your project.
• Columns... Allows you to customise the columns shown shown in the Coverage Explorer.

Viewing Coverage Results

The Clover-for-Eclipse plugin shows coverage data in number of ways. Viewing any coverage data, of course, requires that you have executed tests or you have launched your application and it also requires that Clover has detected the change in coverage. On the Clover preferences page, you can change how often Clover looks for new coverage data for your application or tests.

Source Code Annotations 

To view coverage information on a line-by-line basis, Clover adds coloured annotations to your project's Java source code editors.

Screenshot: Clover Source Annotations

The table below explains the meanings of various colours:

Each coloured source annotation displays a tool tip providing more information about the relevant line or lines. These coverage annotations are added automatically to any opened source files from a Clover-enabled project. For example, if a statement was executed ten times, or a conditional expression was only executed twice in the true case but never in the false case, this information will appear in the tool tip.

If you wish to switch off the source code annotations, you can easily do so by de-selecting the menu / toolbar item "Show Coverage in Editor" on the Coverage Explorer view or Test Run Explorer view. Using an adjacent menu / toolbar item you can also force Clover to only annotate code without coverage, thus only showing the red annotations.

You can also change these colours and effects in Eclipse. To do so, access 'Eclipse Preferences > General > Editors > Text Editors > Annotations'. On this page, see the 'Annotation Types' list and click the settings that begin with 'Clover'.

Screenshot: Clover Source Annotation Settings

Test Run Explorer

The Test Run Explorer view, like several popular plugins such as the JUnit Plugin or TestNG Plugin, lets you explore your recently run tests - showing whether they passed or failed, their duration and any error messages that they generated. Clover-for-Eclipse takes this one step further and allows you to explore the code coverage caused by an individual test, a test class, a package or even your entire project.

After running tests in a Clover-enabled project, select the Test Run Explorer view (or to open it, select Window > Show Views > Other... > Test Run Explorer). On the left-hand side of this view you will see a tree of tests that were run and their containers such as classes, packages, projects etc. On selecting an element on the left-hand side, the right-hand side displays all the application (i.e. non-test) classes that had coverage caused by the selection.

For example, selecting a test method on the left side will cause the right-hand side to show the application classes with code executed (directly or indirectly) by that test method. Selecting a test class or test package will cause the right-hand side to show application classes with code executed by all the test methods contained by the test classes or test package.

The right-hand table displays not only the names of the classes that were partially or fully covered by the test methods, but also the percentage of class' total coverage that is attributable to the test method (the test method's coverage contribution) as well as the percentage of the class' coverage that was attributable only to the selected test method (the test method's unique coverage).

The tree of tests and their containers on the left-hand tree can be presented in three different ways for maximum convenience:

1. Packages : shows Project > Package > Class > Files > Test Classes > Test Methods
2. Package Roots: shows Project > Package Root > Package > Class > Files > Test Classes > Test Methods
3. Test Cases: shows Project > Test Methods (qualified with Test Class names)     

Screenshot: Clover Test Run Explorer

Coverage Cloud Reports

Coverage cloud report are a great way to work out the classes that form major risks (low coverage but high complexity) to your project and its packages, and also to highlight potential quick wins for increasing the overall project or per-package coverage.

The coverage cloud report has two tabs, one tab for the project/package risks cloud and the other for quick wins cloud. Each cloud shows the classes of the project/package 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. At the bottom of the report you can select the target for the clouds - either the entire project or one of the packages within the project - changing this will update the cloud tabs. Where a package is selected and has sub-packages, the checkbox "Include classes from sub-packages" allows you to include or exclude sub-package clouds from the clouds.

The coverage cloud report can be generated by right clicking on your Clover-enabled project in the Coverage Explorer view or Test Run Explorer view and selecting Generate Coverage Cloud.

Screenshot: Clover Coverage Cloud Report

 Coverage Treemap Reports

The coverage treemap report allows simultaneous comparison of classes and package by complexity and by code coverage. The treemap is divided by package (labelled) and then further divided by class (unlabelled). The size of the package or class indicates its complexity (larger squares indicate great complexity, while smaller squares indicate less complexity). Colours indicate the level of coverage, as follows:

• Bright green (most covered)
• Dark green (more coverage)
• Black (around 50% coverage)
• Dark Red (little coverage)
• Bright Red (uncovered)

The percentage shown in the yellow box is the code coverage for the class currently under the mouse.

Right clicking on a package area and selecting the magnify option will then focus the treemap on the package's classes. Right clicking again and selecting the demagnify option will re-focus on the project's top level. Double clicking on a class will open the corresponding source file in an editor.

The treemap cloud report can be generated by right clicking on your Clover-enabled project in the Coverage Explorer and selecting Generate Coverage Treemap.

Screenshot: Clover Coverage Treemap Report

Test Contributions

The Test Contributions view shows unit tests and methods that generated coverage for the currently opened and selected Java source file. As you switch between Java source file editors, the top most tree is updated with the test methods that contributed to coverage of this file. Clicking on the any of the tests and their methods will take you to their associated source. Unchecking a test or test method will remove the coverage it provides from the open source file. The bottom tree tracks the test methods that contributed to coverage of the file at the current cursor position.

The Test Contributions view allows you to better understand the relationship between your test code and your application code as you move between Java source files.

Screenshot: Clover Test Contributions

Disabling Clover

In order to track the code coverage of your projects, Clover must insert special code into your programs at compilation time - called instrumentation - to record this coverage. When Clover is enabled on your projects, Clover will automatically perform this task for every file you compile in the project. You can tell Clover not to instrument your projects by right clicking on them in the Coverage Explorer or Test Run Explorer views and deselecting "Compiled with Clover".

If you wish to temporarily disable the red/green code coverage annotations in your Java source editors (but wish to continue using Clover on your projects), you can simple toggle the "Show Coverage in Editor". This setting applies to all Clover-enabled projects in the workspace.

If you want to completely disable Clover support for a project (which will remove it from the three Clover views etc), then right clicking on the project and selecting "Clover | Disable on this Project". If you wish to disable Clover on multiple projects, right click on one of them and select "Clover | Enable/Disable on..." and deselect the projects you wish to disable Clover for.

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).
• From the "Clover" page of the workspace preferences (Window | Preferences).

Project Properties - Instrumentation

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

• Initstring - This controls where the Clover plugin stores (and looks for) the coverage database. You may want to specify a custom value if you want the Clover coverage data generated to be available to an external merge task or report generation.
• Flush Policy - The Flush Policy controls how Clover writes coverage data to disk when your application runs.
  "At JVM shutdown and on special instruction" is the default and means coverage data is written to disk when the JVM shutsdown or when Clover encounters an inline comment directive instructing it to flush.
  "At set intervals" allows you to specify that coverage data should be written out at regular intervals.
  "At set intervals from a Clover thread" causes Clover to create a separate thread within your application which regularly flushes coverage data to disk. See Flush Policies.
  These options control the compilation of the instrumented source code that Clover generate.
• Output Folder - This specifies where instrumented classes are placed after compilation.
  "Copy instrumented class files to project output dir(s)" will cause instrumented classes to be placed in the same folder or folders as Eclipse would normally place class files according to your project settings. In this mode Clover will only output instrumented class files.
  If a different project directory is specified, Clover will place instrumented class files in the folder specified by you and continue to place un-instrumented class files in the project's configured output folder(s).

Screenshot: Instrumentation Properties

Project Properties - Contexts

Clover's coverage contexts allow you to filter out certain parts of your project's code when considering how much of your code is covered. This is useful when you do not have 100% code coverage yet don't feel the uncovered code is of sufficient importance to invest time to test. See Using Coverage Contexts for an in-depth discussion of contexts and how they are used.

Clover recognises two main types of contexts - block contexts which are pre-defined by Clover, and custom contexts which are defined by you.

• Block Contexts - these are pre-defined by Clover and refer to common Java coding constructs or idioms such as the body of if statements; static initialiser blocks; or property style methods.

• Custom Contexts - Are defined by you and and come in two flavours - method contexts and statement contexts.
  Methods contexts are specified as regular expressions that match methods in your classes. For example, a method context of "(.* )?public .(foo|bar)(.*" will identify any public method named foo or bar. You could then later filter out coverage for such methods if you considered them unimportant to your project's total coverage figures. See Using Coverage Contexts - Method Contexts.
  Statement contexts are also specified as regular expressions and they match statements in your methods. For example, a statement context of ".LOG\.debug." would identify identify statements that perform debug level logging. You could then filter out coverage for these logging statements if you found their coverage (or lack of coverage) too distracting.

Screenshot: Eclipse Project Context Filtering

Project Properties - Source Files

The Source Files tab let you select in detail what exactly should be instrumented. You can select one of the following:

• A global pattern for including and/or excluding source files.
• A per-source root selection (including per-source root includes/excludes).

This configuration windows allows you to use Ant-style pattern sets. If there are only certain source files you want instrumented, then by using these Ant-style include and exclude patternsets you can fine-tune how Clover determines whether files are eligible for instrumentation. For example, by using an "Excludes" value of **/remote/*.java you will stop instrumentation of files in the "remote" folder of your project.

• Look in all source folders and apply the following Ant-style pattern sets (relative to the project root) -
  Applies your pattern sets to all source folders.

• Only look in these folders and apply their Ant-style pattern sets (relative to the project root) -
  Applies your pattern sets to all specified set of folders.

Screenshot: Eclipse Project Source File Settings

Project Properties - Test Classes

The Test classes tab lets you select how Clover should look for your tests. You can select from one of the following:

• A global pattern for including and/or excluding source files.
• A per-source root selection.
• None (Clover makes no attempt to look for tests).

Clover Preferences - General

These options control how Clover works across all projects which have "Compile with Clover" enabled.

• When rebuilding project — When you 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.
• Coverage visualisation should refresh automatically — If enabled, the plugin will check for updated coverage data at the frequency given below and display and new coverage. If it is not enabled, then you will need to use the "Refresh Coverge Data" button to see updated coverage data.
• Coverage visualisation should span coverage before build — The span attribute allows you to control which coverage recordings are merged to form a current coverage report. For more information, see Using Spans.
• Miscellaneous settings
  "When generating reports first initialise AWT in the UI thread" is a compatibility setting for certain systems. Please leave this in its default setting unless advised otherwise by Atlassian support personnel.
  "Clover plugin logging output level" allows you to set the logging output of the plugin to one of three levels: minimal, verbose or debug.
  "JDT Hooks Integration" allows you to integrate or de-integrate Clover from Eclipse's Java compiler. After changing this a restart of Eclipse is required for it to take effect. Please leave this in its default setting unless advised otherwise by Atlassian support personnel.
  

Screenshot: Clover Eclipse Preferences

Clover Preferences - License

This option allows you to view and change the license you use with Clover.

• License text — When you receive a Clover license from Atlassian, you should copy its contents to this text box. If the license text is on the clipboard then clicking the "Paste" button will paste it to this text box automatically. If you have saved the Clover license to a file then clicking the "Load..." button will allow you to select the file and fill the text box with its contents.
• Summary — The summary box summarises the nature of the currently-enabled Clover license.

Screenshot: Clover License Preferences

FAQ

See the Eclipse Plugin FAQ