Skip Headers
SigTest User's Guide
Version 2.2
  Go To Table Of Contents
Go To Index


5 Using the API Coverage Tool

API Coverage tool requires these environmental settings and components:

The API Coverage tool is a command-line utility that executes in a Java application environment. It generates static API test coverage reports in either plain text or XML format based on the following two input items:

You can use the Setup command of the Signature Test tool to create the appropriate signature file for use by the API Coverage tool. The Setup command is described in Chapter 3.

5.1 Running API Coverage Tool

API Coverage tool command synopsis:

% java -jar apicover.jar [options]
% java [options]

The second alternative assumes that apicover.jar is on the class path. The rules described in Section 3.3.2, "Case Sensitivity of Option Arguments" apply. Table 5-1 lists the available options.


Arguments to options marked with an asterisk (*) in Table 5-1 can be specified multiple times. For example, if you want to specify filtering for the java.awt, java.lang, and java.math packages, you can specify the three arguments separated by a file separator character as shown in the following example:. -tsInclude java.awt:java.lang:java.math On Unix operating systems the separator character is “:” and on Microsoft Windows it is “;”.

Table 5-1 API Coverage Tool Command Options

Options Description


Optional. Displays usage information for available command options and exits.

-ts path

Required. Cannot be repeated. Path to the test suite classes to be analyzed. Also accepts a JAR file.

-tsInclude package_name*

Optional. Can be repeated. Recursively include classes from the specified test suite package.

-tsIncludeW package_name*

Optional. Can be repeated. Include classes from the specified test suite package without subpackages.

-tsExclude package_name*

Optional. Can be repeated. Recursively exclude classes from the specified test suite package.

-excludeList filename

Optional. Can be repeated. Specifies the file name of an exclude list which contains API elements to be excluded from the coverage calculation. Section 5.1.2, "Exclude List" describes the exclude list format.


Optional. Exclude all interface classes. This option is superfluous if used with -excludeAbstractClasses.


Optional. Exclude all abstract classes including interfaces.


Optional. Exclude all abstract methods from all classes and interfaces


Optional. Exclude all fields from all classes and interfaces. cannot be used with the -includeConstantField option.


Optional. Specifies to include all final fields of any type in the coverage calculation. cannot be used with the -excludeFields option. The default, without this option, is to remove from the coverage calculation all final fields of primitive types and type java.lang.String.

Constant fields such as final fields of primitive and String types are initialized at compile-time with a constant expression. The Java technology-based compiler usually optimizes them and replaces them with their values. In such cases, test suite classes does not contain a reference to the field, even if the field were used/referenced in the test suite. For this reason, the tool removes all constant fields from the calculation by default to make coverage calculations more consistent. The -includeConstantFields option provides a means for changing this behavior.

-api path/filename

Required. Cannot be repeated. Specifies the location of the signature file representing the API under examination. The path defaults to the working directory. Accepts v1 and v2 format signature files generated by the Signature Test Tool Setup command, and rejects v0. See the -FileFormat option description in Chapter 3.

-apiInclude package_name*

Optional. Can be repeated. Recursively include classes from the specified API package.

-apiIncludeW package_name*

Optional. Can be repeated. Include classes from the specified API package without subpackages.

-apiExclude package_name*

Optional. Can be repeated. Recursively excludes classes from the specified API package.

-mode [w | r]

Optional. Specifies the mode of coverage calculation as w for worst case or r for real world. Defaults to worst case.

-detail [0 | 1 | 2 | 3 | 4]

Optional. Specifies the level of report detail as an integer from 0–4. Defaults to 2. See Table 5-2.

-format [plain | xml]

Optional. Specifies the report format as plain text or XML. Defaults to plain. Note that an example of the XML output is available in SIGTEST_HOME/msc.

-report path/filename

Optional. Where to place the generated report file. The path argument defaults to the working directory when only a file name is specified; otherwise, defaults to standard out.


Optional. Displays version information.

Table 5-2 describes the reporting levels resulting from the five settings available with the -detail option.

Table 5-2 Report File Contents for Levels of Detail

Detail Setting Package Summary Class Summary Members Not Covered Covered Members



















5.1.1 Special Report File

The special report file specified with the -out option contains the same coverage data that the standard report file contains. The main difference is that this format is easier for other applications to parse.

The special report file is essentially a table with these two columns delimited by a tab character:

  • The left column provides the coverage counter value which can be zero.

  • The right column provides the fully qualified name of the corresponding API member: a class, constructor, method, or field.

The -mode option affects the special report file, while the -detail setting has no effect on it.

5.1.2 Exclude List

In some cases a test suite either cannot or should not test certain elements of an API, whether they be a class, a method, or field. In this case you can use the -excludeList filename option (described in Table 5-1) to make the coverage calculation more accurate by excluding the elements listed in the specified exclude list file(s).

The exclude list is a text file that specifies each entry for exclusion on a separate line, as follows:

  • Package name specified to recursively exclude all classes of the package

  • Class name specified as a fully qualified class name

  • Field name specified using a fully qualified class name: classname.fieldname

  • Method name specified using a fully qualified class name: classname.methodname (parameters)

Exclude list processing follows these rules:

  • Regards a line starting with the # character as a comment.

  • Ignores empty lines.

  • Silently ignores an entry if it is not found in the API.


    Each entry specified for exclusion should match its appearance in a report file. For example, you must specify an inner class with the $ character prepended to its name, like this: Outer$Inner