The Clover JBuilder Plugin allows you access the functionality of Clover from within your IDE. Clover will instrument your java source and show you your test coverage, highlighting areas of code that have not been executed.

To install the Clover JBuilder Plugin:

1. Locate your JBuilder installation directory. For the rest of this document, this directory will be referred to as JBUILDER_HOME.
2. Download the Clover JBuilder zip file, and extract it into a temporary directory.
3. Copy the lib\clover-jbuilder.jar file into the JBUILDER_HOME/lib/ext directory.
4. The next time you start JBuilder, Clover will be available.

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-jbuilder.jar file in the JBUILDER_HOME/lib/ext directory.

To uninstall the Clover JBuilder Plugin:

1. Shutdown any running instances of JBuilder.
2. Delete the clover-jbuilder.jar file from the JBUILDER_HOME/lib/ext directory.
3. Restart your JBuilder instance.

This quick start guide will take you through the steps required to generate a clover coverage report for your project.

1. Enable Clover, by selecting the 'Enable Clover' check box in the 'Project | Project Properties | Clover' properties page.
2. Add the clover plugin jar to your project library path.
3. Turn on clover instrumentation by clicking the toolbar item
4. Rebuild your project using any of the build mechanisms provided by JBuilder.
5. View the project coverage data by clicking the toolbar item.
6. Run your application or test cases. This will generate your Coverage data.
7. Refresh/load your coverage data by clicking the to see which parts of your application were covered.

Your most frequent interaction with Clover will be via the Clover Toolbar (shown below). All the functions available through the toolbar are also available in the 'Project' menu.

The Clover toolbar contains the following functions:

• Build with Clover. Toggles the use of the Clover Compiler when JBuilder compiles the current project.
• . Show Coverage. Toggles the display of coverage information in the Source editors.
• Refresh coverage button. Coverage data for the current project is reloaded from disk.
• Coverage summary bar. Displays the coverage level of the current project.
• Reset Coverage. Deletes the recorded coverage data for the current project.
• Delete Coverage. Deletes the recorded coverage data AND the coverage database for the current project.

In addition, the 'Project' menu contains additional functions:

• Generate Report.... Launches the report generation wizard that will take you through the steps required to generate a Pdf, Html or XML report.
• Filter Coverage.... Launches a dialog to set the context filter.

Java Source Editor

The Clover JBuilder plugin allows you to view the clover coverage data directly within the Java Source Editor (as seen below).

The coverage data is displayed in two ways:

• As a marker in the left hand gutter.
• As highlights within the Java Source Editor.

By default, coverage data is represented by three colours.

• Red indicates that the line of source is not fully covered.
• Green indicates that the line of source is fully covered.
• Yellow indicates that the coverage data being displayed is out of date. The source file has changed since the coverage data was generated, and will need to be re-instrumented.

Project Coverage Tree

The Clover Plugin allows you to view a coverage tree (see below) for the current project. This coverage tree is located in the Project Pane, on the left hand side of the IDE.

Clover Coverage Database File Type support

Clover provides support for viewing arbitrary coverage databases. Just add a coverage database file to your project and explore the coverage recordings. The default coverage database file extension is db. This can be modified as necessary via 'Tools | Preferences' and then 'Browser | File types' properties page.

The Clover Plugin configuration options are available through the 'Project | Project Properties' menu, or the project node (right click) context menu. Configuration is split into Compilation configuration and View configuration.

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. "Directed" is the default and means coverage data is written to disk when the JVM exists (or when your test cases finish). "Interval" allows you to specify that coverage data should be written out at regular intervals. "Threaded" will actively flush coverage data to disk at regular intervals. See Flush Policies.

Filtering

If you do not want all of your source instrumented, then you can control which this using these two Ant pattern sets. For example, you may prevent tests from being instrumented by using an "Excludes" value of **/*Test.java as shown.

Compiler

This allows you to select the java compiler used by clover to compile your java source once it has been instrumented.

Language Level

Allows you to specify which language features you would like Clover to support. If you use asserts within your code, you would need to select '1.4' or higher, if you use enums, then you need to select '1.5'.

View 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 to refresh the coverage data. "Automatic" means that the Clover Plugin will periodically check for new coverage data for you.

Inline View

Allow you to customize where coverage data is displayed within the JBuilder IDE. Gutter marks appear in the left hand gutter of the Java Source Editor. Inline highlights appear directly over your source code. The Coverage Tree is located within the IDEs project view, and provides a per file view of your project coverage.

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 marks.

Span

Allows you to configure the span used by Clover. See Spans for more information.

Filter Options

Block Filters

Allows you to specify contexts to ignore when viewing coverage information.

Regexp Filters

The regexp filters allow you to define custom contexts to ignore when viewing coverage information.

Working with regexp filters.

• Use group of button on the right hand side to Create, Delete, Edit or Copy 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 Delete Coverage menu item and rebuild your project.

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 "Tools | Project Properties | Clover | Filters".
• Select Add to create a new Regexp Context Filter.
• Select Edit to open up the Regexp Edit dialog.
• 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 Delete Coverage from the Clover menu and recompile your project. Once active, you will notice the private filter appears in the Context Filter Dialog. You will now be able to filter private methods out of your Clover coverage calulations and reports.

Q: Why does JBuilder prompt me to save a clover enabled project on exit when I have not changed any settings?

A: During the project build process, clover needs to modify the projects sourcepath to allow for various compiler optimizations. Although it only exist for the duration of the build, this configuration change is what triggers the project to be considered 'dirty', and hence the save upon exit dialog.