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.
- From the Project Explorer view, right click on your Java project.
- Select "Clover | Enable Clover capabilities...".
- 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.
- Open the Clover Coverage Explorer View by selecting "Window | Show View | Other..." and selecting Clover > Coverage Explorer. This view is designed for horizontal placement. You should see your project listed with 0% coverage against it.
- Open the Clover Test Contributions View by selecting "Window | Show View | Other..." and selecting Clover > Test Contributions. The view is designed for vertical placement. As your project has no coverage yet, this view won't tell you anything interesting.
The Clover Coverage Explorer
The Coverage Explorer view allows you to control Clover's instrumentation of your Java projects, and shows you the coverage statistics for each project. The tree shows the project, package and class coverage and complexity information for all Clover-enabled projects. Summary statistics are displayed alongside the tree for the selected project/package/class.
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:
- 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 plugin shows coverage data in five ways:
- As a coloured annotation of the source code in the Java editor. Each annotation has a tooltip indicating the coverage problem. If you wish to switch off the source code annotations you can easily do so by deselecting the menu / toolbar item "Show Coverage in Editor" on the Coverage View.
- As a tag cloud report highlighting the classes that form major project risks (low coverage, high complexity) and potential quick wins for increasing project coverage. This report has two tabs, one tag for the project risks page and the other for quick wins page. 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.
- As a treemap report allowing simultaneous comparison of classes and package by complexity and by code coverage. The treemap is divided by package (labeled) and then further divided by class (unlabeled). 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.
- By reporting on the unit tests and methods that generated coverage for the currently opened Java source file. As you switch between Java editors the top most tree is updated with the the tests and 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. This allows you to better understand the relationship between your test code and your application code.
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
Clover-for-Eclipse User's Guide
