5. Eclipse configuration options

 

 

The Clover Eclipse plugin's configuration can be accessed in three places:

  • From the "Clover" page of a project's properties dialog (Project > Properties > Clover).
  • From the "Clover" page of the workspace preferences (Window > Preferences > Clover).
  • From the "Annotations" page of the workspace preferences (Window > Preferences > General > Editors > Text Editors > Annotations)

Project Properties

Clover - Instrumentation

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.
      These options control the compilation of the instrumented source code that Clover generate.

 

  • Output Folder - This specifies where instrumented classes are placed after compilation.
    • "Copy instrumented class files to project output dir(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.
    • "Copy instrumented class files to a different project dir" will 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).
    • "Recreate original output folders" if checked, instrumented packages and classes will be placed in subfolders that mimic the original output folders relative to the project root

 

  • Miscellaneous - other settings
    • "Fully qualify instrumentation references to java.lang classes" - if checked, all classes from java.lang package will be referenced using their fully qualified name; this option avoids name conflicts in case your project contains classes named the same as those from java.lang package.
    • "Instrument and compile at: statement level / method level" - statement level instrumentation is more accurate but has a runtime performance penalty, method level instrumentation is less accurate but will run faster. We recommend using statement level unless you have a performance issue. (Since Clover 3.1.8).
    • "Instrument lambda functions" - whether Java 8 lambda functions shall be instrumented. If instrumented, they're treated like normal methods (they can be shown in HTML report and considered in code metrics, for example). Possible values:
      • none - do not instrument lambda functions,
      • expression - instrument lambdas in expression-like form, e.g. "(a, b) -> a + b",
      • block - instrument lambdas in code blocks, e.g. "(a, b) -> { return a + b; }",
      • all - instrument all lambda functions.
      (warning) Due to Clover's restrictions related with code instrumentation and javac compiler's type inference capabilities, you may get compilation errors when expression-like lambda functions are passed to generic methods or types. In such case disable instrumentation of expression-like form (i.e. use the none or block setting). See the Java 8 code instrumented by Clover fails to compile Knowledge Base article for more details. (Option available since Clover 3.3.0).


 

Clover - Contexts

Clover's coverage contexts allow you to filter out certain parts of your project's code when considering how much of your code is covered. This is useful when you do not have 100% code coverage yet don't feel the uncovered code is of sufficient importance to invest time to test. See Using Coverage Contexts for an in-depth discussion of contexts and how they are used.

Clover recognizes two main types of contexts - block contexts which are pre-defined by Clover, and custom contexts which are defined by you.

  • Block Contexts - these are pre-defined by Clover and refer to common Java coding constructs or idioms such as the body of if statements; static initializer blocks; or property style methods.
  • Custom Contexts -Are defined by you and and come in two flavors - 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.


 

Clover - Source Files

The Source Files tab let you select in detail what exactly should be instrumented. You can select one of the following:

  • A global pattern for including and/or excluding source files.
  • A per-source root selection (including per-source root includes/excludes).

This configuration window allows you to use Ant-style pattern sets. If there are only certain source files you want instrumented, then by using these Ant-style include and exclude pattern sets 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.

  • Look in all source folders and apply the following Ant-style pattern sets (relative to the project root) -
    Applies your pattern sets to all source folders.
  • Only look in these folders and apply their Ant-style pattern sets (relative to the project root) -
    Applies your pattern sets to all specified set of folders.

 

Clover - Test Classes

The Test classes tab lets you select how Clover should look for your tests. You can select from one of the following:

  • A global pattern for including and/or excluding source files.
  • A per-source root selection.
  • None (Clover makes no attempt to look for tests).

 

Global Preferences

Clover - 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 visualization should
    • Refresh automatically every Ns - 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 Coverage Data" button to see updated coverage data.
    • 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.
  • When changing the coverage context filter for a project - when you change context filter, Clover can perform full rebuild of a project or let you rebuild it manually; "Ask me each time" sets whether Clover should prompt about it
  • When changing the instrumentation source settings for a project - similar as above
  • Miscellaneous settings
    • When generating reports first initialize 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.
    • Annotate Package Explorer icons to show source Clover exclusions - If enabled, Clover will add small icons in the Package Explorer view for every source file, indicating whether it's included or excluded from instrumentation.
    • Clover plugin logging output level allows you to set the logging output of the plugin to one of four levels: info, verbose, debug or none. Output will be written to standard Eclipse log file (<eclipse_workspace>\.metadata\.log).

    • Automatically open Clover views when enabling Clover on a project
      When selected, Clover will automatically open four standards views ("Coverage Explorer", "Test Run Explorer", "Test Contributions", "Clover Dashboard") in the current perspective every time Clover is being enabled on a project (e.g. by right click on a project and selecting "Clover -> Enable/Disable on"). De-selecting this option is useful when you don't use some of Clover views and don't want to have them re-appearing

    • Preserve instrumented sources in temporary directory
      When enabled, Clover will keep a copy of every instrumented source file in the temporary directory (in Eclipse workspace). This allows to see the exact content of file which was passed to the compiler. Use this option for troubleshooting only, i.e. when you believe that code was incorrectly instrumented. There is no reason to have this option enabled during normal work. Files will not be automatically removed, so you'd have to clean temporary directory manually. Files are stored in a structure reflecting project layout. When you enable this option, the "Logging Level" will automatically switch to "Info". After every compilation you can find a message in Error Log view about location of instrumented files, for example:
      CLOVER: Instrumented sources have been preserved in <workspace>\.metadata\.plugins\org.eclipse.core.resources\.projects\Moneybags\com.cenqua.clover.core\CLOV_INSTR_SRC

 

Clover - 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 summarizes the nature of the currently-enabled Clover license.


Clover - Test Optimization

This page allows to view and change Test Optimization settings.

  • Show dialog when no tests need to be run - if enabled, Clover will show pop-up in case when due to test optimization no test case have been executed
  • Discard snapshot every N compiles - if enabled, Clover will delete test optimization file after N builds (thus causing that no tests will be optimized during next test run)
  • Minimize tests - if enabled, Clover will execute only these tests which have failed or these which are affected by code changes; otherwise all tests are executed
  • Test reordering
    • Do not reorder - no change in test execution order
    • Failing tests first - tests are first sorted by test result from previous run (failing first) and next by their execution time (shortest first)
    • Random order - tests are shuffled in random order; this option is good for detecting unwanted cross-test dependencies

 

Text Editors - Annotations

Code markers are as follows:

  • Clover: Code covered - code which has been covered during execution
  • Clover: Code covered (but not directly by test execution) - code which has been covered, but there is no related test case (e.g. from a call of the main() method)
  • Clover: Code covered (but not for all branches) - code with a partial branch coverage (caused when only one part of a branch has been covered)
  • Clover: Code covered (but only by failing tests) - code which has been covered, but all related test cases are failing
  • Clover: Code covered (filtered from view) - code which has been filtered out
  • Clover: Code not covered - code which has been never executed
  • Clover: Passed tests (at least one) - color for overview ruler marker stripe indicating that at least one passing test case is related with given line
  • Clover: Failed tests (all of them) - color for overview ruler marker stripe indicating that all tests related with given line are failing

 


Now you have tweaked and hacked Clover according to your developer needs. But you would like to share information about code coverage with you colleagues or present it to management? If yes, read next chapter: 6. Generating reports in Eclipse.

 

Last modified on May 26, 2016

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.