netbeans.apache.org/src/content/wiki/SigTest.asciidoc - netbeans-website - Git at Google

 //
 //     Licensed to the Apache Software Foundation (ASF) under one
 //     or more contributor license agreements.  See the NOTICE file
 //     distributed with this work for additional information
 //     regarding copyright ownership.  The ASF licenses this file
 //     to you under the Apache License, Version 2.0 (the
 //     "License"); you may not use this file except in compliance
 //     with the License.  You may obtain a copy of the License at
 //
 //       http://www.apache.org/licenses/LICENSE-2.0
 //
 //     Unless required by applicable law or agreed to in writing,
 //     software distributed under the License is distributed on an
 //     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 //     KIND, either express or implied.  See the License for the
 //     specific language governing permissions and limitations
 //     under the License.
 //

 = SigTest
 :jbake-type: wiki
 :jbake-tags: wiki, devfaq, needsreview
 :jbake-status: published
 :syntax: true
 :description: New Home
 :icons: font
 :source-highlighter: pygments
 :toc: left
 :toc-title:
 :experimental:

 `SigTest` is the tool behind NetBeans link:SignatureTest.asciidoc[signature
 testing] infrastructure. It checks for incompatibilities between different
 versions of the same API.

 [[New_Home]]
 == New Home

 Please continue at link:https://github.com/jtulach/netbeans-apitest#readme[https://github.com/jtulach/netbeans-apitest#readme]
 that is the new home since NetBeans migrated to Apache.


 [[Old_Content_Follows]]
 == Old Content Follows

 NetBeans uses the link:APITest.asciidoc[APITest] tool as an Ant task to check
 for binary backward compatibility and mutual signature compatibility. There is
 however also a version released as a
 link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin]
 ready for use in your own project. The
 link:https://github.com/jtulach/netbeans-apitest[sources] were converted to
 GitHub repository and are available under GPL version 2.

 [[Use_in_Maven]]
 == Use in Maven

 The sigtest Maven Plugin is available on link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin at Maven Central]
 thus it is easily embeddable it into your own project.

 [[Generate_the_Signature_File]]
 === Generate the Signature File

 The first thing to do is to generate snapshot of API of your library - e.g. the
 signature file.

 Just add following into your own `pom.xml` file:

 [source,xml]
 ----
 <plugin>
   <groupId>org.netbeans.tools</groupId>
   <artifactId>sigtest-maven-plugin</artifactId>
   <version>1.2</version>
   <executions>
     <execution>
       <goals>
         <goal>generate</goal>
       </goals>
     </execution>
   </executions>
   <configuration>
     <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
   </configuration>
 </plugin>
 ----

 with just this change the API of your classes in the listed packages is going
 to be recorded into a `.sigtest` file and included as an artefact of your
 project when you invoke `mvn install`.

 For example libraries of Html4Java NetBeans API
 link:https://repo1.maven.org/maven2/org/netbeans/html/net.java.html.json/1.3/[have the sigtest file]
 attached in Maven central with link:http://hg.netbeans.org/html4j/rev/833829b33779[this changeset].


 [[Check_Against_Signature_File_in_a_Repository]]
 === Check Against Signature File in a Repository

 Once the `sigfile` is part of a Maven repository, you want to check your new
 APIs against that API _snapshot_ to make sure you are not making incompatible
 changes. Try the following:

 [source,xml]
 ----

 <plugin>
   <groupId>org.netbeans.tools</groupId>
   <artifactId>sigtest-maven-plugin</artifactId>
   <version>1.2</version>
   <executions>
     <execution>
       <goals>
         <goal>check</goal>
       </goals>
     </execution>
   </executions>
   <configuration>
     <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
     <releaseVersion>1.3</releaseVersion>
   </configuration>
 </plugin>

 ----

 The difference is the goal - e.g. *check* and also the need to specify
 *releaseVersion* - that is the identification of the previously released
 version of your library that you want to check compatibility against.

 And that is all! To verify the setup is correct, try to remove a method or do
 some other incompatible change.

 When I tried and executed `mvn install` I got a build failure:

 [source]
 ----
 SignatureTest report
 Base version: 1.3
 Tested version: 2.0-SNAPSHOT
 Check mode: bin [throws removed]
 Constant checking: on

 Class net.java.html.json.Models
   "E1.2 - API type removed" : method public final static void net.java.html.json.Models.applyBindings(java.lang.Object,java.lang.String)


 target/surefire-reports/sigtest/TEST-json-2.0-SNAPSHOT.xml: 1 failures in /.m2/repository/json/1.3/json-1.3.sigfile
  ------------------------------------------------------------------------
 BUILD FAILURE
 ----

 This is the way Html4Java enabled signature testing: see link:http://hg.netbeans.org/html4j/rev/031e46d048d8[changeset] mixing both goals together.


 [[Fail_on_Error]]
 ==== Fail on Error

 You may want to control whether a failure in signature test should be fatal or not. Do it with:

 [source,xml]
 ----

   <configuration>
     <failOnError>false</failOnError>

     <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
     <releaseVersion>1.3</releaseVersion>
   </configuration>

 ----

 With this configuration the test will be performed and output printed, but the build will go on. This may be useful when one needs to do an incompatible change and wants to disable the check until next version is published.


 [[Prevent_Any_Change]]
 ==== Prevent Any Change

 By default the plugin verifies there are no *incompatible* changes. However compatible changes are allowed. Sometimes it is useful to prevent any changes altogether (when creating a bugfix release, for example), then try:

 [source,xml]
 ----

   <configuration>
     <action>strictcheck</action>

     <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
     <releaseVersion>1.3</releaseVersion>
   </configuration>

 ----

 with the *action* option set to _strictcheck_ the plugin will detect any API change and fail even if it is compatible.


 [[Whos_Using_SigTest]]
 == Who's Using SigTest

 NetBeans SigTest is used by:

 * NetBeans uses it as an Ant task
 * Html4Java APIs use it as Maven plugin
 * Oracle Labs link:https://github.com/graalvm/truffle[Truffle project] integrates it into link:http://wiki.apidesign.org/wiki/TruffleSigTest[their own build tool].
 * link:http://dukescript.com[DukeScript] project for its link:https://github.com/dukescript/DefinitelyTyped[Definitely Typed Java API] for all JavaScript libraries


 [[Develop]]
 == Develop

 Binary Builds are available from our link:http://deadlock.netbeans.org/hudson/job/apitest/[hudson builder]. Get the sources with

 [source,bash]
 ----
 hg clone http://hg.netbeans.org/apitest/
 cd apitest
 ant jar test
 # open in NetBeans
 ----

 Contact the developer via email jtulach (at) netbeans.org - and don't forget to
 read link:http://wiki.apidesign.org/wiki/TheAPIBook[Practical API Design] book.


 [NOTE]
 ====

 The content in this page was kindly donated by Oracle Corp. to the
 Apache Software Foundation.

 This page was exported from link:http://wiki.netbeans.org/SigTest[http://wiki.netbeans.org/SigTest] ,
 that was last modified by NetBeans user Jtulach
 on 2019-04-10T05:59:08Z.


 This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
 ====
	//
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.
	//

	= SigTest
	:jbake-type: wiki
	:jbake-tags: wiki, devfaq, needsreview
	:jbake-status: published
	:syntax: true
	:description: New Home
	:icons: font
	:source-highlighter: pygments
	:toc: left
	:toc-title:
	:experimental:

	`SigTest` is the tool behind NetBeans link:SignatureTest.asciidoc[signature
	testing] infrastructure. It checks for incompatibilities between different
	versions of the same API.

	[[New_Home]]
	== New Home

	Please continue at link:https://github.com/jtulach/netbeans-apitest#readme[https://github.com/jtulach/netbeans-apitest#readme]
	that is the new home since NetBeans migrated to Apache.


	[[Old_Content_Follows]]
	== Old Content Follows

	NetBeans uses the link:APITest.asciidoc[APITest] tool as an Ant task to check
	for binary backward compatibility and mutual signature compatibility. There is
	however also a version released as a
	link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin]
	ready for use in your own project. The
	link:https://github.com/jtulach/netbeans-apitest[sources] were converted to
	GitHub repository and are available under GPL version 2.

	[[Use_in_Maven]]
	== Use in Maven

	The sigtest Maven Plugin is available on link:https://search.maven.org/search?q=a:sigtest-maven-plugin[sigtest-maven-plugin at Maven Central]
	thus it is easily embeddable it into your own project.

	[[Generate_the_Signature_File]]
	=== Generate the Signature File

	The first thing to do is to generate snapshot of API of your library - e.g. the
	signature file.

	Just add following into your own `pom.xml` file:

	[source,xml]
	----
	<plugin>
	<groupId>org.netbeans.tools</groupId>
	<artifactId>sigtest-maven-plugin</artifactId>
	<version>1.2</version>
	<executions>
	<execution>
	<goals>
	<goal>generate</goal>
	</goals>
	</execution>
	</executions>
	<configuration>
	<packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
	</configuration>
	</plugin>
	----

	with just this change the API of your classes in the listed packages is going
	to be recorded into a `.sigtest` file and included as an artefact of your
	project when you invoke `mvn install`.

	For example libraries of Html4Java NetBeans API
	link:https://repo1.maven.org/maven2/org/netbeans/html/net.java.html.json/1.3/[have the sigtest file]
	attached in Maven central with link:http://hg.netbeans.org/html4j/rev/833829b33779[this changeset].


	[[Check_Against_Signature_File_in_a_Repository]]
	=== Check Against Signature File in a Repository

	Once the `sigfile` is part of a Maven repository, you want to check your new
	APIs against that API _snapshot_ to make sure you are not making incompatible
	changes. Try the following:

	[source,xml]
	----

	<plugin>
	<groupId>org.netbeans.tools</groupId>
	<artifactId>sigtest-maven-plugin</artifactId>
	<version>1.2</version>
	<executions>
	<execution>
	<goals>
	<goal>check</goal>
	</goals>
	</execution>
	</executions>
	<configuration>
	<packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
	<releaseVersion>1.3</releaseVersion>
	</configuration>
	</plugin>

	----

	The difference is the goal - e.g. check and also the need to specify
	releaseVersion - that is the identification of the previously released
	version of your library that you want to check compatibility against.

	And that is all! To verify the setup is correct, try to remove a method or do
	some other incompatible change.

	When I tried and executed `mvn install` I got a build failure:

	[source]
	----
	SignatureTest report
	Base version: 1.3
	Tested version: 2.0-SNAPSHOT
	Check mode: bin [throws removed]
	Constant checking: on

	Class net.java.html.json.Models
	"E1.2 - API type removed" : method public final static void net.java.html.json.Models.applyBindings(java.lang.Object,java.lang.String)



	target/surefire-reports/sigtest/TEST-json-2.0-SNAPSHOT.xml: 1 failures in /.m2/repository/json/1.3/json-1.3.sigfile
	------------------------------------------------------------------------
	BUILD FAILURE
	----

	This is the way Html4Java enabled signature testing: see link:http://hg.netbeans.org/html4j/rev/031e46d048d8[changeset] mixing both goals together.


	[[Fail_on_Error]]
	==== Fail on Error

	You may want to control whether a failure in signature test should be fatal or not. Do it with:

	[source,xml]
	----

	<configuration>
	<failOnError>false</failOnError>

	<packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
	<releaseVersion>1.3</releaseVersion>
	</configuration>

	----

	With this configuration the test will be performed and output printed, but the build will go on. This may be useful when one needs to do an incompatible change and wants to disable the check until next version is published.


	[[Prevent_Any_Change]]
	==== Prevent Any Change

	By default the plugin verifies there are no incompatible changes. However compatible changes are allowed. Sometimes it is useful to prevent any changes altogether (when creating a bugfix release, for example), then try:

	[source,xml]
	----

	<configuration>
	<action>strictcheck</action>

	<packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
	<releaseVersion>1.3</releaseVersion>
	</configuration>

	----

	with the action option set to _strictcheck_ the plugin will detect any API change and fail even if it is compatible.


	[[Whos_Using_SigTest]]
	== Who's Using SigTest

	NetBeans SigTest is used by:

	* NetBeans uses it as an Ant task
	* Html4Java APIs use it as Maven plugin
	* Oracle Labs link:https://github.com/graalvm/truffle[Truffle project] integrates it into link:http://wiki.apidesign.org/wiki/TruffleSigTest[their own build tool].
	* link:http://dukescript.com[DukeScript] project for its link:https://github.com/dukescript/DefinitelyTyped[Definitely Typed Java API] for all JavaScript libraries


	[[Develop]]
	== Develop

	Binary Builds are available from our link:http://deadlock.netbeans.org/hudson/job/apitest/[hudson builder]. Get the sources with

	[source,bash]
	----
	hg clone http://hg.netbeans.org/apitest/
	cd apitest
	ant jar test
	# open in NetBeans
	----

	Contact the developer via email jtulach (at) netbeans.org - and don't forget to
	read link:http://wiki.apidesign.org/wiki/TheAPIBook[Practical API Design] book.


	[NOTE]
	====

	The content in this page was kindly donated by Oracle Corp. to the
	Apache Software Foundation.

	This page was exported from link:http://wiki.netbeans.org/SigTest[http://wiki.netbeans.org/SigTest] ,
	that was last modified by NetBeans user Jtulach
	on 2019-04-10T05:59:08Z.


	This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed.
	====