The SigTest product is a collection of tools that can be used to compare APIs and to measure the test coverage of an API. The tools were originally created to assist in the creation of Java technology compatibility test suites (TCKs), but are also useful in the creation of other types of test suites and in the software development process. The SigTest product consists of the following tools.
Signature Test tool makes it easy to compare the signatures of two different implementations or different versions of the same API. When it compares different implementations of the same API, the tool verifies that all of the members are present, reports when new members are added, and checks the specified behavior of each API member. When it compares different versions of the same API, the tool checks that the old version can be replaced by the new one without adversely affecting existing clients of the API.
API Coverage tool can be used to estimate the test coverage a test suite provides for an implementation of a specified API. It does this by determining how many public class members the test suite references within the API specification. The tool uses a signature file representation of the API specification as the source of specification analysis. It does not process a formal specification in any form.
API Check tool tracks API changes and roughly checks for source and binary compatibility. Much like Signature Test tool, it compares the reference implementation of an API recorded as golden signature file with a tested implementation. Unlike Signature Test tool, which requires that all classes (and the classes they depend on) be specified to the tool, API Check tool does not require dependencies to be specified. For that reason, API Check tool is faster than Signature Test tool, but less rigorous.
Part I of this manual describes how to use the Signature Test Tool, Part II describes how to use the API Coverage tool, Part III describes how to use the API Check tool, and Part IV contains two appendices that include step-by-step examples that show how to use the Signature Test tool and the rules used in the Signature Test API migration feature.
This section describes functionality that is available to all the tools and their commands.
All of the tools accept options from a option file as well as from the command line. Option files allow you to create complex command lines in a text editor and then reuse them.
The option file is specified on the tool command line using the “@” character as shown in the following example.
java -jar sigtest.jar test @file
In this case, file is the path to a option file. You can use a combination of option files and command-line options as shown in the following example.
java -jar sigtest.jar test @file -package com.acme.api.printing.color
In addition to options and their arguments, option files can also contain “set” commands that you can use to set variables for use within the option file. The option file syntax is demonstrated in Example 1-1.
Example 1-1 Option File
#-------------------------------------------------- #This option file checks the API against JRE 1.6 #-------------------------------------------------- set HOME=/home/ersh set JRE=/opt/java/jre16 set AMCE_HOME=$(HOME)/projects/release set API=$(ACME_HOME)/lib/ams.jar static backward classpath=$(JRE)/lib/rt.jar:$(API) filename=$(ACME_HOME)/misc/reference.sig
This option file is equivalent to the following command line.
java -jar sigtest.jar test -static -backward -classpath /opt/java/jre16/lib/rt.jar:/home/ersh/projects/release/lib/ams.jar -filename /home/ersh/projects/acmesystem/msc/reference.sig -package com.acme.api.printing.color
All of the tools and commands support the
-version option as a way to display information about the tools and will list which signature files they are compatible with. In addition, you can specify the
-version option as an argument directly to the JAR file as well as shown here.
java -jar sigtest.jar -version