Using Coverage Contexts

Clover defines a Context as a part of source code that matches a specified structure or pattern. Contexts are either pre-defined or user-defined at instrumentation time. Each context must have a unique name. At report time, you can specify which contexts you would like to exclude in the coverage report.

Clover's context feature currently does not support Groovy.

Block Contexts

Block Contexts are pre-defined by Clover. They represent 'block' syntatic constructs in the Java language. A full list of supported Block Contexts is shown below.

Method Contexts

A Method Context represents the set of methods whose signature matches a given pattern. Clover provides several pre-defined method contexts:

A method signature includes all annotations, modifiers (public, static, final etc), the return type, the method name, parameter types and names, the throws clause and exceptions.

Note When matching method signatures against context regexps, whitespace is normalised and comments are ignored.

You can define your own method contexts via the <methodContext> sub-element of <clover-setup>, or via the configuration panel of your Clover IDE Plugin.

Note Contexts are matched against your source at instrumentation-time. This means you need to re-instrument your code after defining a new context.

Method Contexts with Groovy code

While Groovy syntax is flexible in nature, the regular expressions defined in the regexp parameters of <methodContext> elements must match a 'normalised' method signature.

Bear in mind that this is not necessarily how you would define the method in your Groovy source code.

For example, in Groovy code, a method defined via the 'def' keyword is always 'public'. This means that your regexp must actually match "public def". Hence, if you wanted to create a regexp that matched the following Groovy method:

Your regexp must assume a match against:

Normalised method signature rules for defining regexp parameters:

The following list illustrates the normalised form of the method signature (and hence, order) in which your regexp must be defined to match specific methods in your Groovy source code:

1. Modifiers – in the following order:
   1. public
   2. protected
   3. private
   4. abstract
   5. static
   6. final
   7. transient
   8. volatile
   9. synchronized
   10. native
   11. strictfp
   12. interface
       (Refer to Sun Java's documentation for more information.)
2. Type Parameters (optional) – for example, <T>, <E extends Object>
3. Return Type – for example, void, int, String, Object[]
4. Name – for example, myMethod
5. Parameter List – for example, (String arg1, int arg2)
6. Throws – for example, throws Exception1, Exception2

Statement Contexts

A Statement Context represents the set of statements that match a given pattern. For example, you might want to set up a statement context to allow you to filter out 'noisy' statements (such as logging calls) by defining a statement context regexp .*LOG\.debug.*.

Using Context Filters

Note This section describes using context filters with Ant. For details of using filters with the IDE plugins, see the individual documentation for the plugin.

Filtering catch blocks

In some cases you may not be interested in the coverage of statements inside catch blocks. To filter them, you can use Clover's predefined catch context to exclude statements inside catch blocks from a coverage report:

This generates a source-level HTML report that excludes coverage from statements inside catch blocks.

Filtering logging statements

To remove logging statements for coverage reports, you will need to define one or more statement contexts that match logging statements in your source:

This defines two statement contexts and one method context. The first matches statements that start with 'LOG.' while the second matches statements that start with  'if (LOG.', which is designed to match conditional logging statements such as:

The second matches all 'main' methods that have a String Array named 'args' in the constructor:

After defining these contexts, you now need to re-compile with Clover and then re-run your tests. You can then generate a report that excludes logging statements:

This generates a source-level HTML report that excludes coverage from logging statements.