6 Using the API Coverage Tool

API Coverage tool requires these environmental settings and components:

A properly configured certified Java Platform, Standard Edition (”Java SE platform”) runtime version 1.4 or later
One of the following JAR files in your class path:
- sigtestdev.jar
- sigtest.jar
The API Coverage tool Main class is contained in both JAR files.

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:

The test suite being tested for its coverage, represented by a set of test class files
A signature file that forms a text representation of the public members of an API that must be tested by the test suite

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

6.1 Running API Coverage Tool

API Coverage tool command synopsis:

% java -jar apicover.jar [options]
or
% java com.sun.tdk.apicover.Main [options]

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

Note:

Arguments to options marked with an asterisk (*) in Table 6-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 6-1 API Coverage Tool Command Options

Options	Description
`-help`	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. "Exclude List" describes the exclude list format.
`-excludeInterfaces`	Optional. Exclude all interface classes. This option is superfluous if used with `-excludeAbstractClasses.`
`-excludeAbstractClasses`	Optional. Exclude all abstract classes including interfaces.
`-excludeAbstractMethods`	Optional. Exclude all abstract methods from all classes and interfaces
`-excludeFields`	Optional. Exclude all fields from all classes and interfaces. cannot be used with the `-includeConstantField` option.
`-includeConstantFields`	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 4.
`-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 \| 5]`	Optional. Specifies the level of report detail as an integer from 0–5. Defaults to 2. See Table 6-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.
`-version`	Optional. Displays version information.

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

Table 6-2 Report File Contents for Levels of Detail

Detail Setting	Package Summary	Class Summary	Members Not Covered	Covered Members	Reference Count
0	X
1	X	X
2	X	X	X
3	X	X		X
4	X	X	X	X
5	X	X		X	X

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

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

Note:

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

6.2 Merging API Coverage XML Reports

The API Coverage Tool Merge command merges multiple API Coverage reports in XML format into a single report. Synopsis:

% java com.sun.tdk.apicover.CMerge [options]

The rules described in "Case Sensitivity of Option Arguments" apply to the Merge command. Table 6-3 lists the Merge command options.

Table 6-3 Merge Command Options

Option	Description
`-Files`	Required. Specifies the names of the API coverage XML report files to be merged. The file name are separated by a colon (:) o Unix systems, and by a semicolon (;) on Microsoft Windows systems.
`-Write`	Required. Specifies the merged output report file..
`-Strict`	Optional. Requires identical set of members for the same classes.
`-Version`	Optional. Displays version information, then exits.
`-Help`	Optional. Displays usage information for available command options, then exits.