Clover-for-Eclipse User's Guide

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 Clover capabilities...".
3. With Clover now enabled, your project will now be automatically rebuilt. If you have upgraded from a previous version of Clover you will need to perform a clean build of all your Clover-enabled projects.
4. Open the Clover Coverage Explorer View by selecting "Window | Show View | Other..." and selecting Clover > Coverage Explorer. 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.
5. Open the Clover Test Run Explorer View by selecting "Window | Show View | Other..." and selecting Clover > Test Run Explorer. 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.
6. Open the Clover 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.

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.

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.

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

 
The Coverage Explorer 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 | Coverage Explorer".

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

• 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.*Edits the source contexts used to filter on when displaying coverage information for a project. More information on contexts 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 report page in treemap format that 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 that lists classes considered project risks or quick wins.
• Generate Report. Launches the report generation wizard that will take you through the steps required to generate a Pdf, Html or Xml.
• Hide Unavailable. This check button hides any elements in the Coverage View'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 View'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.

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 - code with coverage is coloured green while code without is coloured red. Each coloured source annotation also displays a tool tip providing more information about the relevant line or lines (e.g. that a statement was executed ten times, or that a conditional expression was only executed twice in the true case but never in the false case). These coverage annotations are added automatically to any opened source files from a Clover-enabled project. 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.

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)   

 

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.

 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. Its colour indicates its level of coverage. 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 Generage Coverage Treemap.

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.

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.

Disabling Clover in your project

You can disable Clover instrumentation using the "Compile with Clover" button. 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.

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. You can also achieve this by right clicking on the project and selecting "Clover | Remove Clover capabilities...".

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 - Instrumentaton

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.

Project Properties - Compilation

These options control the compilation of the instrumented source code that Clover generate.

• Output Folder - This specifies where instrumented classes are placed after compilation.
  "Project output folder(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.
  "User specified folder:" will cause Clover to 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).

Project Properties - Contexts

Coverage contexts allow you to marks some parts of your code so that you can later filter out the coverage for these in the Coverage Explorer. See Using Coverage Contexts.

• Coverage Contexts - Allows you to add, remove, edit or copy the coverage contexts that will be identified in your source code during future compiles. You can add two types of coverage contexts - 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.

Project Properties - Source Files

• Filtering Includes/Excludes - 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.

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.
  

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.

FAQ

See the Eclipse Plugin FAQ