Clover-for-IDEA User's Guide

This page contains all user documentation for Clover-for-IDEA. Click a heading in the table below to jump to that section.

On this page:

Overview

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

Screenshot: Clover for IDEA Plugin

Getting Started

This getting started guide will take you through the steps required to generate Clover coverage for your project.

1. Ensure that the clover plugin jar has been added to your project library path.
2. Enable Clover, by selecting the 'Enable Clover' check box in the "File | Settings | Project | Clover" interface.
3. Turn on clover instrumentation by selecting the toolbar item.
4. Rebuild your project using any of the build mechanisms provided by IDEA.
5. Run your project by running the unit tests or some other means.
6. Refresh the latest coverage data by clicking the toolbar item.
7. Highlight coverage in the source code editor by selecting the toolbar item.
   Available highlighting options:
   highlight covered code (in green) and code with no coverage (in red),
   only highlight code with no coverage,
   turn code coverage highlighting off.
   this enables little gray and green clovers in package explorer These indicate the toggled state of the exclusion annotation.
8. When option is selected only coverage from passed unit tests contributes to the coverage percentage.
9. View the TreeMap report for the current project using the button.
10. View the Cloud report for current project using button.

Viewing Coverage Results

Clover will record the code coverage information each time you run your application or a unit-test. This coverage information is available for viewing using IDEA.

The coverage information can be browsed using the Clover Tool Window. The upper portion of the tool window contains a project class browser with inline coverage information:

Screenshot: Clover Coverage Window

The tool bar at the top of the browser contains the following buttons:

• Flatten Packages. With this selected, only concrete packages are shown in the browser.
• Autoscroll to Source. With this selected, a single click on a class in the browser will load the corresponding source file in an editor pane, with coverage info overlaid.
• Autoscroll from Source. With this selected, the coverage browser will track the currently active source file in the editor pane.
• Always view package in the Cloud report. When this is selected the Cloud view will automatically show a package selected in this tree.
• Show Coverage Summary. With this selected, the Coverage metrics (see below) will be visible.
• Generate Report. Launches a dialog to create a coverage report in HTML, XML or PDF format.
• Cloud report for selected package. Opens Cloud report for selected package.
• Refresh. Reloads coverage data.
• Clean Coverage. Cleans gathered coverage data without deleting the instrumentation database.
• Delete. Delete the current coverage database.
• Set Context Filter. Launches a dialog to set the context filter.
• Hide Fully Covered Elements. Removes elements with 100% coverage from view.
  
  
• Set Coverage Scope. Choose which classes should be included in the Clover Coverage View - only application classes, only test classes or all classes.

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)

Screenshot: Clover Coverage Treemap Report

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

View the TreeMap report for current project using the button.

Setting Context Filters

The types of classes you want included in the Clover Coverage View can be set with Context Filters:

Screenshot: Setting Context Filters

Using the Tool Window

The lower portion of the Tool Window contains various Metrics for the currently selected node in the browser:

Screenshot: Clover Tool Window Summary

Showing Coverage with Annotations

In addition, the plugin can annotate the Java code with the coverage information. This can be turned on by pressing the Show Coverage toolbar button.

Screenshot: Annotated Java Code

If a source file has changed since a Clover build, then a warning will be displayed alerting you to fact that the inline coverage information may not be accurate. The coverage highlighting will be yellow, rather than the red shown above.

Test Run Explorer

The Test Run Explorer displays recently run tests in your Clover-instrumented project.

The upper panel displays test cases as a flat list ( ), grouped by package ( ) or by source root folder ( ).

The lower panel displays classes and methods covered by the testcase selected in the upper panel. Two metrics are displayed for each class and method:

• Contributed Coverage indicates the percentage of statements that have been covered by selected testcase,
• Unique Coverage indicates the percentage of statements that have been covered by selected testcase only.

Screenshot: Test Run Explorer

Unique Actions in Test Run Explorer

• / / : Click to choose test cases layout.
• : Toggle calculating test coverage to display in the upper panel. If enabled, the plugin will provide information about given test contribution to the selected target scope (see below). Note that enabling this option seriously slows down the Clover database refresh.
• Target scope : Only tests touching selected scope would be shown.
  • All tests: All recorded tests in the project,
  • File tests: All tests touching the currently displayed file,
  • Class / Method / Statement at cursor: All tests involving the class, method or statement under the cursor, respectively.

Select In -> Clover (Alt-F1 menu)

It is possible to view currently selected element in Clover using the Alt-F1 menu.

If the cursor is inside a recognized test case, it would be displayed in Test Runs Explorer, listing methods touched by the test in the lower panel.
Otherwise the element under cursor is displayed in the Coverage view.

Configuration Options

Compilation Options

Configuration options for Clover are accessible on the Clover panel of the Project Properties dialog. The first Tab on this panel provides compilation options:

Screenshot: Clover for IDEA Compilation Options

Initstring

This section controls where the Clover coverage database will be stored. Select 'Automatic' to have Clover manage this location for you (relative to your project directory). Select 'User Specified' to nominate the path to the Clover coverage database. This is useful if you want to use the plugin in conjunction with an Ant build that already sets the location of the Clover coverage database.

Flush Policy

The Flush Policy controls how Clover writes coverage data to disk at runtime. See Flush Policies.

Instrumentation

Allows you to specify a comma separated list of set of Ant Patternsets that describe which files to include and exclude in instrumentation. These options are the same as those described in the <clover-setup> task. You can also specify whether source in test folders should be also instrumented.

For example, by using an "Excludes" value of _**/remote/*.java _ you will stop instrumentation of files in the "remote" folder of your project.

It is now possible to change exclusion/inclusion patterns directly from the Project Explorer.
Right click on a package or file, click the Change Exclusion context menu and select whether a pattern corresponding to the selected element should be added (or removed) from your includes or excludes list.

Files in the Project Explorer are annotated by gray or green clover when they are currently excluded or included by the current Clover configuration. A package is annotated when it is explicitly excluded or included.

Screenshot: Right-Click Context Menu for Setting Includes and Excludes

Rebuild Policy

The Clover database becomes obsolete after certain operations (such as toggling Build with Clover). The Rebuild Policy setting allows defining the plugin's behavior in the case of such an event.

• Ask: The plugin will show a dialog window asking for confirmation.
• Rebuild Immediately: The plugin will rebuild the project automatically, without asking the user.
• Never Rebuild Automatically: The plugin will neither rebuild nor display a dialog — with this setting the user is responsible for rebuilding the project manually.

View Options

The second Tab on the configuration panel provides view options;

Screenshot: Clover for IDEA View Options

Refresh Policy

The Refresh Policy controls how the Clover Plugin monitors the Coverage Database for new data.
"Manual" means that you have to click button to refresh the coverage data.
"Automatic" means that the Clover Plugin will refresh the database on:

• project open,
• finished compilation,
• termination of unit test or application run.

"Periodically" means that the Clover Plugin will periodically check for new coverage data for you.

General

Allows you to customize where coverage data is displayed within the IntelliJ IDE. Gutter marks appear in the left hand gutter of the Java Source Editor. Source highlights appear directly over your source code. Shortcut marks appear in the right hand gutter and allow you to navigate directly to uncovered regions of code.

Span

See Using Spans.

Per-test Coverage Data

Per-test coverage can be disabled to boost performance. If you disable this feature, the following information will not be available:

• Test results.
• Code has been uniquely covered by specific tests.
• Code has been covered by failed tests only.

However, the coverage data will load load faster as a result.

Source Highlighting

Allows you to fine tune the colours used Clover in its coverage reporting. The 'highlight colour' for each item is used for Source Highlights and the 'stripe colour' for each item is used for Gutter and Shortcut marks.

Filter Options

The third Tab on the configuration panel provides filter options;

Screenshot: Clover for IDEA Filter Options

Built-in Context Filters

Allows you to specify contexts to ignore when viewing coverage information. For example, selecting the finally body context will remove 'finally' block bodies ('block' syntatic constructs in the Java language) from the reported coverage. For more information, see Coverage Contexts in the Clover Core documentation.

Custom Contexts

This allow you to define custom contexts to ignore when viewing coverage information.

Working with regexp filters:

• Use , or to Create, Delete or Copy respectively the selected filter.
• All new and edited regexp filters will be shown in 'blue', indicating that they are currently unavailable.
• To make a new/edited filter active, you need to delete the existing coverage database using the button and rebuild your project/module.

  See Coverage Contexts for more information.

Example: Creating a regexp context filter

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 "Settings | Clover | Filters".
• Select 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.
• You will notice that the name of this new filter appears in blue. Blue is used to indicate that the filter is either new or recently edited and therefore 'unavailable'. To make this new filter available, select from the Main Toolbar and recompile your project. Once active, 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.