The Apache Maven SigTest plug-in (sigtest-plugin
) makes the functionality of the Sigtest, Setup and Merge commands available from Maven 2 build scripts. The Maven APICover plug-in (apicover-plugin
) makes the functionality of the APICover tool available to Maven 2 build scripts. All goals are bound by default to the ”test” life cycle phase.
The the four sigtest-plugin
goals are described in Table F-1:
Table F-1 The sigtest-plugin
Goals
Goal | Description |
---|---|
|
Provides |
|
Provides static mode SignatureTest functionality to Maven 2 build scripts. Compares the reference API represented in the signature file to the API under test and produces a report. |
|
Provides Merge functionality to Maven 2 build scripts. Creates a combined signature file from several signature files representing different Java platform APIs in one Java runtime environment according to the JSR 68 rules. |
|
Provides API Coverage tool functionality to Maven 2 build scripts, This goal is used to estimate the test coverage that a test suite under development affords to implementations of its related API specification. |
The following sections describe the requirements and parameters for each of the goals listed in Table F-1. An example follows each section.
The setup
goal accepts a reference implementation of an API as input. The command processes API input in order to generate a signature file that represents the API to be used as a reference for comparison during signature testing.
Full name: com.sun.tdk:sigtest-plugin:2.2:setup
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test
Table F-2 Required Parameters (sigtest-plugin:setup
)
Name | Type | Corresponding Setup Command Option | Description |
---|---|---|---|
fileName |
String |
-filename |
Specifies the name of the signature file to be created. |
pathElements |
List |
-classpath |
Specifies the path to one or more APIs that generate the signature file. Can contain multiple directories, Zip files or JAR files. |
packages |
List |
-package |
Specifies classes or packages to be included in the signature file including its subpackages if a package is specified. |
Table F-3 Optional Parameters (sigtest-plugin:setup
)
Name | Type | Corresponding Setup Command Option | Default Value | Description |
---|---|---|---|---|
excludes |
List |
-exclude |
Specifies a package or class to be excluded from the signature file, including its subpackages. |
|
nonClosedFile |
boolean |
-NonClosedFile |
FALSE |
Causes direct and indirect superclasses and superinterfaces of tested classes not to be included in the signature file. This eliminates cases where they do not belong to the scope defined by ”packages” parameters. |
apiVersion |
String |
-apiVersion |
Specifies the API version string to be recorded in the second line of the signature file. |
|
failOnError |
boolean |
TRUE |
Stops the build process if the command exits with an error. |
|
negative |
boolean |
FALSE |
Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests. |
Example F-1 Sample Plugin Configuration (pom.xml
)
<project> . . . <build> . . . <plugins> <plugin> . . . <groupId>com.sun.tdk</groupId> <artifactId>sigtest-plugin</artifactId> <configuration> <fileName>java-awt-lang-math.sig</fileName> <packages> <package>java.awt</package> <package>java.lang</package> <package>java.math</package> </packages> <excludes> <exclude>java.lang.Math</exclude> <exclude>java.lang.ref</exclude> </excludes> <pathElements> <pathElement>${ref.jhome}/jre/lib/rt.jar</pathElement> </pathElements> <apiVersion>Java Six</apiVersion> </configuration> </plugin> . . . </plugins> . . . </build> . . </project>
The test
goal compares the reference API (represented in a signature file) to the API under test and produces a report. Unlike the SignatureTest command it only supports static mode—reflection is not supported
Full name: com.sun.tdk:sigtest-plugin:2.2:test
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test
Table F-4 Required Parameters (sigtest-plugin:test
)
Name | Type | Corresponding Setup Option | Description |
---|---|---|---|
fileName |
String |
-filename |
Specifies the name of the signature file to be created. |
pathElements |
List |
-classpath |
Specifies the path to one or more APIs that generate the signature file. Can specify multiple directories, Zip files or JAR files. |
packages |
List |
-package |
Specifies classes or packages to be included in the signature file, including its subpackages if a package is specified. |
Table F-5 Optional Parameters (sigtest-plugin:test
)
Name | Type | Corresponding SignatureTest Option | Default Value | Description |
---|---|---|---|---|
excludes |
List |
-exclude |
Specifies a package or class to be excluded from the signature file, including its subpackages. |
|
apiVersion |
String |
-apiVersion |
Specifies the API version string to be recorded in the second line of the signature file. |
|
binary |
boolean |
-mode bin |
FALSE |
Specifies that binary mode be used during the signature test instead of the source code compatibility mode. |
backward |
boolean |
-Backward |
FALSE |
Specifies migration instead of mutual compatibility check mode. |
human |
boolean |
-FormatHuman |
FALSE |
Specifies the human-readable report output format. |
errorAll |
boolean |
-ErrorAll |
FALSE |
Specifies that the signature test be made stricter by upgrading certain warnings to errors. |
debug |
boolean |
-debug |
FALSE |
Enables printing of the stack trace for debugging purposes if SignatureTest fails. |
failOnError |
boolean |
TRUE |
Stops the build process if the command exits with an error. |
|
negative |
boolean |
FALSE |
Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests. |
Example F-2 Sample Plugin Configuration (pom.xml
)
<project> . . . <build> . . . <plugins> <plugin> . . . <groupId>com.sun.tdk</groupId> <artifactId>sigtest-plugin</artifactId> <configuration> <fileName>java-awt-lang-math.sig</fileName> <packages> <package>java.awt</package> <package>java.lang</package> <package>java.math</package> </packages> <excludes> <exclude>java.lang.Math</exclude> <exclude>java.lang.ref</exclude> </excludes> <pathElements> <pathElement>${ref.jhome}/jre/lib/rt.jar</pathElement> </pathElements> <apiVersion>Java Six</apiVersion> <failOnError>false</failOnError> <human>true</human> <backward>true</backward> <out>report.txt</out> <debug>true</debug> </configuration> </plugin> . . . </plugins> . . . </build> . . </project>
The merge
goal command combines (merges) a number of input signature files into a single signature file.
Full name: com.sun.tdk:sigtest-plugin:2.2:merge
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test
Table F-6 Required Parameters (sigtest-plugin:merge
)
Name | Type | Corresponding Merge option | Description |
---|---|---|---|
write |
String |
-Write |
Specifies the resulting output signature file. |
files |
List |
-Files |
Specifies the names of the signature files to be merged. |
Table F-7 Optional Parameters (sigtest-plugin:merge
)
Name | Type | Corresponding Merge Option | Default Value | Description |
---|---|---|---|---|
binary |
boolean |
-Binary |
FALSE |
Specifies that binary mode be used during the signature test instead of the source code compatibility mode. |
failOnError |
boolean |
TRUE |
Stops the build process if the command exits with an error. |
|
negative |
boolean |
FALSE |
Treats tests that do not succeed as having passed, and tests that do succeed as having failed. Used for negative tests. |
Example F-3 Sample Plugin Configuration (pom.xm)
<project> . . . <build> . . . <plugins> . . . <plugin> . . . <groupId>com.sun.tdk</groupId> <artifactId>sigtest-plugin</artifactId> <configuration> <files> <file>baseAPI.sig</file> <file>optionalAPI1.sig</file> <file>optionalAPI2.sig</file> </files> <write>result.sig</write> <failOnError>false</failOnError> </configuration> </plugin> . . . </plugins> . . . </build> . . . </project>
The apicover-plugin:apicover
goal is used to estimate the test coverage that a test suite under development affords to implementations of its related API specification. It does this by determining how many public class members the test suite references within the API specification that it is designed to test against. The tool uses a signature file representation of the API specification as the basis of its specification analysis.
Full name: com.sun.tdk:apicover-plugin:2.2:apicover
Requires a Maven 2.0 project to be executed.
Binds by default to the life cycle phase: test
Table F-8 Required Parameters (apicover-plugin:apicover
)
Name | Type | Corresponding APICover Option | Description |
---|---|---|---|
tests |
List |
-ts |
Specifies the path to the test suite classes to be analyzed. Also accepts a JAR file. |
api |
String |
-api |
Specifies the location of the signature file representing the API under examination. |
Table F-9 Optional Parameters (apicover-plugin:apicover
)
Name | Type | Corresponding APICover Option | Default Value | Description |
---|---|---|---|---|
tsIncludes |
List |
-tsInclude |
Recursively includes classes from the specified test suite package. |
|
tsIncludeWs |
List |
-tsIncludeW |
Includes classes from the specified test suite package without subpackages. |
|
tsExcludes |
List |
-tsExclude |
Recursively excludes classes from the specified test suite package. |
|
apiIncludes |
List |
-apiInclude |
Recursively includes classes from the specified API package. |
|
apiIncludeWs |
List |
-apiIncludeW |
Includes classes from the specified API package without subpackages. |
|
apiExcludes |
List |
-apiExclude |
Recursively excludes classes from the specified API package. |
|
excludeLists |
List |
-excludeList |
Specifies the file name of an exclude list that contains API elements to be excluded from the coverage calculation. |
|
excludeInterfaces |
boolean |
-excludeInterfaces |
FALSE |
Excludes all interface classes. |
excludeAbstractClasses |
boolean |
-excludeAbstractClasses |
FALSE |
Excludes all abstract classes including interfaces. |
excludeAbstractMethods |
boolean |
-excludeAbstractMethods |
FALSE |
Excludes all abstract methods from all classes and interfaces |
excludeFields |
boolean |
-excludeFields |
FALSE |
Excludes all fields from all classes and interfaces. |
includeConstantFields |
boolean |
-includeConstantFields |
FALSE |
Specifies the inclusion of all final fields of any type in the coverage calculation. |
mode |
String |
-mode |
w (worst case) |
Specifies the mode of coverage calculation as ”w” which represents the worst case or ”r” which represents the real world. |
detail |
String |
-detail |
2 |
Specifies the level of report detail as an integer from 0-4 |
format |
String |
-format |
plain |
Specifies the report format as plain text or XML. The values can be ”plain” or ”xml”. Note that an example of the XML output is available in SIGTEST_HOME |
report |
String |
-report |
See the description. |
Specifies the location of the generated report file. The path argument defaults to the working directory when only a file name is specified. If a file name is not specified, it defaults to the Maven logger |
out |
String |
-out |
See the description |
Generates a specially formatted report file for use by other applications and places it at the specified location/file name. The path defaults to the working directory. |
Example F-4 Sample Plugin Configuration (pom.xml
)
<project> . . . <build> . . . <plugins> . . . <plugin> . . . <groupId>com.sun.tdk</groupId> <artifactId>apicover-plugin</artifactId> <configuration> <api>publicAPIv3.sig</api> <tests> <test>${ts.path}/testSet1.jar</test> <test>${ts.path}/testSet2.jar</test> <test>${ts.path}/testSet3.jar</test> </tests> <apiIncludes> <apiInclude>com.acme.api</apiInclude> </apiIncludes> <mode>r</mode> <detail>4</detail> <format>plain</format> <report>${report.path}/covrep_real.txt</report> </configuration> . . . </plugin> . . . </plugins> . . . </build> . . . </project>