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.
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 |
Table 6-1 API Coverage Tool Command Options
Options | Description |
---|---|
|
Optional. Displays usage information for available command options and exits. |
|
Required. Cannot be repeated. Path to the test suite classes to be analyzed. Also accepts a JAR file. |
|
Optional. Can be repeated. Recursively include classes from the specified test suite package. |
|
Optional. Can be repeated. Include classes from the specified test suite package without subpackages. |
|
Optional. Can be repeated. Recursively exclude classes from the specified test suite package. |
|
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. |
|
Optional. Exclude all interface classes. This option is superfluous if used with |
|
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 |
|
Optional. Specifies to include all final fields of any type in the coverage calculation. cannot be used with the 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 |
|
Required. Cannot be repeated. Specifies the location of the signature file representing the API under examination. The path defaults to the working directory. Accepts |
|
Optional. Can be repeated. Recursively include classes from the specified API package. |
|
Optional. Can be repeated. Include classes from the specified API package without subpackages. |
|
Optional. Can be repeated. Recursively excludes classes from the specified API package. |
|
Optional. Specifies the mode of coverage calculation as |
|
Optional. Specifies the level of report detail as an integer from 0–5. Defaults to 2. See Table 6-2. |
|
Optional. Specifies the report format as plain text or XML. Defaults to |
|
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 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 |
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.
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 |
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 |
---|---|
|
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. |
|
Required. Specifies the merged output report file.. |
|
Optional. Requires identical set of members for the same classes. |
|
Optional. Displays version information, then exits. |
|
Optional. Displays usage information for available command options, then exits. |