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.

If you have downloaded the Clover IDEA Plugin package from http://www.cenqua.com/, you can install the plugin manually as follows:

1. shutdown any running instances of IDEA
2. remove any previous versions of the the clover plugin jar from IDEA_HOME/config/plugins OR IDEA_HOME/plugins.
3. copy CLOVER_HOME/lib/clover-idea4.jar into the IDEA_HOME/config/plugins directory, and restart IDEA.

Alternatively, if you have downloaded the plugin via the "File | Settings | IDE | Plugins" interface, the plugin will be available after a restart.

You will need a license to activate your plugin.

• Download your clover.license file from http://www.cenqua.com/licenses.jspa. Evaluation licenses are available free of charge.
• Place the clover.license file next to the clover-idea4.jar file in either the IDEA_HOME/config/plugins or IDEA_HOME/plugins directory.

To uninstall the Clover IDEA Plugin:

1. shutdown any running instances of IDEA
2. delete the clover-idea4.jar file from its installation directory, either IDEA_HOME/config/plugins OR IDEA_HOME/plugins.
3. restart IDEA

Alternatively, you can uninstall the Clover IDEA Plugin via the "File | Settings | IDE | Plugins" interface. Just select the Clover IDEA Plugin from the list and click 'Uninstall Plugin'. The uninstall will take affect after you restart IDEA.

Add the clover jar to your 'project' classpath.

• Open the project properties "File | Settings | Project ".
• In the "Paths" section, select the "Libraries (Classpath)" tab. Remove any old clover jars and add a reference to clover-idea4.jar you must reference the clover-idea4.jar that you installed in IDEA_HOME/config/plugins).

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

1. Ensure that you have added the clover plugin jar 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. View the project coverage data by selecting the toolbar item.

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. This presents the data in a similar way to the existing Clover GUI Viewer. The upper portion of the Tool Window contains a class browser with inline coverage information:

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.
• Show Coverage Summary. With this selected, the Coverage metrics (see below) will be visible.
• Set Context Filter. Launches a dialog to set the context filter:
  
• Generate Clover Report. Launches the report generation wizard that will take you through the steps required to generate a Pdf, Html or XML report.
• Refresh. Reloads coverage data.
• Delete. Delete the current coverage database.

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

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.

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:

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.

Viewer options

The second Tab on the configuration panel provides viewing options;

Refresh Policy

The Refresh Policy controls how the Clover Plugin monitors the Coverage Database for new data. "Manual" is the default and means that you have to click button to refresh the coverage data. "Automatic" 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.

Source Highlighting

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

Filter Options

The third Tab on the configuration panel provides filter options;

Regexp Filters

The regexp filters 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 available, you need to delete the existing coverage database using the button and rebuild your project/module.

Block Filters

Allows you to specify contexts to ignore when viewing coverage information. For example, selecting the if context will remove if body (not the conditional) from the coverage reports.

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.

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

A: If you do not have "Auto Coverage Refresh" enabled, you will need to press the Refresh Button in the Clover Tool Window.

Q: When I compile with Clover instrumentation enabled, I get the following error: Error: line (31) package com_cenqua_clover does not exist

A: You need to add the clover-idea4.jar file 'each' of your modules classpaths.

Q: I have the Clover plugin enabled, but my files are not being instrumented.

A: As of v0.9.1, there is a toggle button on the main IDEA Toolbar for enabling and disabling instrumentation. You will need to ensure that this toggle button is enabled .

Q: When I compile my program I get the stack trace java.lang.IllegalArgumentException: Prefix string too short. Whats going on?

A:There is an known issue within IDEA that is triggered by the Clover integration. This issue relates to the size of the project name. If its less then 3 characters, then you see the exception that you are seeing. The only known 'workaround' for this issue is increasing the length of your project name.

Q: I have an enabled Regexp Filter that does not seem to be filtering.

A: Have you checked your regexp? It may be that your regexp is not matching the methods/statements that you expect. See Coverage Contexts for more information about Regexp Contexts.

A: Try reseting the current context filter and then re-enabling them. There is a known scenario where regexp filters are not being applied to the coverage data when they are enabled at activation time.