6.2. Coverage filters

6.2. Coverage filters
	6. Defining the instrumentation set

Wildcards. EMMA coverage filters are lists of familiar *,?-wildcard class name patterns:

full Java class names are implied, with “.”'s (dots) as Java package separators;
a “*” in a pattern stands for zero or more class name characters;
a “?” in a pattern stands for exactly one class name character

Filters work "across directories"

You should not think of coverage filters as applying at the file level. Instead, think of them as applying at the classpath level. Thus, if you exclude “*Test*”, for example, it will have effect on all application classes that are subject to instrumentation, no matter from how many classpath directories and/or .jars they come.

Inclusions and exclusions. Sometimes all you want is to zoom in to a particular Java package and don't want to specify a long list of exclusion patterns (that also needs to be updated each time someone on your team adds a new Java package to the application). Other times, you do want to include all of the application's classes but would like to exclude just a few packages or name patterns (e.g., your testcases or perhaps a package that is well-tested and can be excluded from coverage analysis).

EMMA coverage filters support all such scenarios and more, in a reasonably concise and intuitive fashion. Each coverage filter pattern is either an inclusion or an exclusion pattern:

By default, a pattern is an inclusion pattern. This can also be made explicit by prefixing it with a “+” (plus sign).
A pattern is an exclusion pattern if it is prefixed with a “-” (minus sign).

Informally, the way inclusions and exclusions work can be summarized as follows: a class name is in the instrumentation set if it is included and not excluded. An empty list of inclusion patterns implicitly includes everything (i.e., it is like “+*”) and an empty list of exclusion patterns implicitly excludes nothing. Furthermore, a class name is included if it matches at least one of the inclusion patterns and not excluded by any exclusion pattern. It is best to show the formal matching rule via pseudocode, followed by some examples:

Inclusion/exclusion matching algorithm.

    if (inclusions is not empty)
    {
        boolean included = false;
                
        foreach (pattern in inclusions)
        {
            if (pattern matches classname)
            {
                included = true;
                break;
            }
        }
                
        if (not included) return classname_is_excluded;
    }

    if (exclusions is not empty)
    {
        foreach (pattern in exclusions)
        {
            if (pattern matches classname) return classname_is_excluded;
        }
    }

    return classname_is_included;

6.2.1. filter syntax: ANT

EMMA ANT (sub)tasks that can take instrumentation filter strings either as a filter attribute or as <filter> nested elements follow the same specification syntax:

filter attribute. The attribute value is a filter string, which is a list of inclusion/exclusion patterns, separated with white space and/or commas. Each inclusion/exclusion pattern is a *,?-wildcard class name mask, prefixed with + and - for inclusion and exclusion, respectively. It is legal to omit a prefix, in which case the inclusion prefix, +, is implied.

It is also possible to specify a list of inclusion/exclusion patterns to be loaded from an external file. To do so, you can set the filter attribute to an @-prefixed file name. The file should contain a list of inclusion/exclusion patterns, one per line (empty lines and lines starting with a “#” are ignored).

<filter> nested element. This nested element can be configured through a combination of the following attributes:

Attribute	Description
`value`	Specifies a list of inclusion/exclusion patterns, separated with white space and/or commas. Each inclusion/exclusion pattern is a `*`,`?`-wildcard class name mask, prefixed with `+` and `-` for inclusion and exclusion, respectively. It is legal to omit a prefix, in which case the inclusion prefix, `+`, is implied. Note that this attribute allows you to specify a mixed list of inclusions and exclusions.
`includes`	Specifies a list of patterns, separated with white space and/or commas. Each pattern is a `*`,`?`-wildcard class name mask, interpreted as an inclusion pattern. All explicit `+`/`-` prefixes are ignored.
`excludes`	Specifies a list of patterns, separated with white space and/or commas. Each pattern is a `*`,`?`-wildcard class name mask, interpreted as an exclusion pattern. All explicit `+`/`-` prefixes are ignored.
`file`	Specifies a list of patterns to be loaded from a file with a given name. The file should contain a list of inclusion/exclusion patterns, one per line (empty lines and lines starting with a “`#`” are ignored). Each inclusion/exclusion pattern is a `*`,`?`-wildcard class name mask, prefixed with `+` and `-` for inclusion and exclusion, respectively. It is legal to omit a prefix, in which case the inclusion prefix, `+`, is implied. Note that such a file can contain a mixed list of inclusions and exclusions.

ANT tip

Note that if any of these attributes is set to an empty string it is ignored. This is convenient for providing team-wide ANT filter "hooks" that are overridden differently by individual developers using ANT command line (-Demma.filter=..., etc).

Examples

Note that all these different ways of specifying instrumentation filters can be used in a combination. The result is a union of all specified patterns. The following examples all specify the same set of inclusion/exclusion patterns:

  <filter includes="com.foo.*" excludes="com.foo.test.*, com.foo.*Test*" />

  <filter includes="com.foo.*" />
  <filter excludes="com.foo.test.*, com.foo.*Test*" />

  <filter value="+com.foo.*, -com.foo.test.*, -com.foo.*Test*" />

  <filter excludes="com.foo.*Test*" file="myfilters.txt" />

where myfilters.txt file contains these lines:

-com.foo.test.*
+com.foo.*

6.2.2. filter syntax: command line

EMMA command line tools that can accept instrumentation filter strings do it via the -ix option. This repeatable option should be set to a list of inclusion/exclusion patterns, separated with white space and/or commas. Each inclusion/exclusion pattern is a *,?-wildcard class name mask, prefixed with + and - for inclusion and exclusion, respectively. It is legal to omit a prefix, in which case the inclusion prefix, +, is implied.

It is also possible to specify a list of inclusion/exclusion patterns to be loaded from an external file. To do so, you can set the option value to point to an @-prefixed file name. The file should contain a list of inclusion/exclusion patterns, one per line (empty lines and lines starting with a “#” are ignored).

Examples

>java emma ... -ix +com.foo.*,-com.foo.test.*,-com.foo.*Test* ...

>java emma ... -ix com.foo.* -ix -com.foo.test.*,-com.foo.*Test* ...

>java emma ... -ix -com.foo.*Test* -ix @myfilters.txt ...

where myfilters.txt file contains these lines:

-com.foo.test.*
+com.foo.*


6. Defining the instrumentation set		7. Common ANT task and command line options