Title: Using the OSGi Compliance Tests The OSGi Alliance provides Apache committers access to its Compliance Tests (CT). This page describes how to get access to the CTs and how to use them with Felix subprojects. ## Gaining Access to OSGi CTs The general process is to send a request to the jcp-open@apache.org mailing requesting access. Since redistributing the OSGi CTs is not allowed, you will need to submit an [NDA](http://www.apache.org/jcp/ApacheNDA.pdf) to be granted access to the [SVN repo](https://svn.apache.org/repos/tck/osgi-cts) containing the binaries. ## OSGi CT Overview The CT is delivered as three JAR files, one for the core CT, one of the enterprise CT and one for the compendium CT. Each JAR file is composed of several other JAR files, which are the actual compliance tests. Typically, there is one JAR per specification, except for the OSGi framework. The CT uses BND as its testing harness, which in turn uses the OSGi framework launching and embedding API to configure, launch, and install test bundles. Each test JAR file has an associated BND file which supplies the configuration BND needs to run the associated tests. ## Modifying the BND files Modifying the BND files is fairly straightforward. A typical BND file looks like this: :::plaintext # bnd pack for project org.osgi.test.cases.startlevel # Mon Aug 31 18:50:18 EDT 2009 build=. -target = \ jar/org.osgi.test.cases.startlevel-4.2.0.jar;version=file, -runpath = \ jar/org.eclipse.osgi-3.5.1.jar;version=file, \ jar/com.springsource.junit-3.8.2.jar;version=file;export="junit.framework;version=3.8" -runbundles -runproperties = \ report="true", \ osgi.compatibility.bootdelegation="false", \ osgi.resolverMode="strict" The important parts are the following settings: * `-target` specifies the bundles containing the tests. * `-runpath` specifies the class path used to run the tests. * `-runbundles` specifies the bundles to install for the tests. * `-runproperties` specifies configuration properties to pass into the framework. The following two examples show how to edit these files for the Felix framework and Felix bundle subprojects. ## Testing the Felix framework The Felix framework is tested against the core CT. The first thing to do is extract the core CT JAR file, which includes test suites for: ###Core functionality * Framework core (`org.osgi.test.cases.framework.bnd`) * Framework launching (`org.osgi.test.cases.framework.launch.bnd`) * Tracker Specification (`org.osgi.test.cases.tracker.bnd`) * URL Handlers (`org.osgi.test.cases.url.bnd`) While the Tracker and URL Handler specifications are optional as per the OSGi Specification, they are implemented by the Felix Framework and therefore the tests should be run and pass. The following CT tests from the Compendium/Enterprise CT also pass with the Felix framework: * XML Parser Specification (`org.osgi.test.cases.xml.bnd`) ###Security components OSGi Security components are optional. They are supported by Felix but require security support to be enabled. See the [Security][1] section below for more details. * Framework security (`org.osgi.test.cases.framework.secure.bnd`) * Framework launching security (`org.osgi.test.cases.framework.launch.secure.bnd`) * Permission Admin (`org.osgi.test.cases.permissionadmin.bnd`) * Conditional Permission Admin (`org.osgi.test.cases.condpermadmin.bnd`) With security correctly enabled in Felix all the above security CT suites should pass. ### Running the tests For each of the associated BND files, the `-runpath` needs to be edited to refer to the Felix framework. The easiest way to do this is by modifying the `shared.inc` file which is included by all BND files. It should look something like this after editing: :::plaintext -runpath = \ /path/to/felix/framework/org.apache.felix.framework-4.4.1.jar;version=file, \ jar/com.springsource.junit-3.8.2.jar;version=file;export="junit.framework;version=3.8" Typically, it is not necessary to change anything else in the BND files and it is normal that the `-runbundles` setting is empty, since there are no additional bundles associated with testing the framework. After editing the BND files, run the tests using: :::plaintext source runtests This will run all test suites for all BND files. To run a specific test suite, do the following: :::bash $ java -jar jar/bnd.jar runtests --title osgi.ct Where `` specifies one or more BND files associated with the desired test suites.
Be Aware Tests for native code loading will fail on Java 6, so do not use this JDK for testing the framework.
Reports for the tests suites are generated in the `reports/` subdirectory and are named after the appropriate test suite. ### Security ***TODO this section is unfinished.*** The exception to this is for the framework test suites for security. To test with security enabled, you will need to add the framework security provider in `-runbundles` like this: :::plaintext -runbundles = \ /path/to/felix/framework.security/org.apache.felix.framework.security-1.0.0.jar.jar;version=file ### Deviations #### Core R5 When running the Core R5 CT the following error appears: :::plaintext testEERequirement junit.framework.AssertionFailedError: Required Execution Environment is available: Unresolved constraint in bundle org.osgi.test.cases.framework.div.tb7a [214]: Unable to resolve 214.0: missing requirement [214.0] osgi.ee; (|(osgi.ee=div/tb7a)(osgi.ee=div/tb7b)) at org.osgi.test.support.OSGiTestCase.fail(OSGiTestCase.java:70) at org.osgi.test.cases.framework.junit.div.DivTests.testEERequirement(DivTests.java:253) This is a known deviation in the Core R5 CT and can be ignored. #### Core R6 When running the Core R6 CT the following error appears: :::plaintext testArrayServiceReferenceDTO junit.framework.AssertionFailedError: ServiceReferenceDTO[] for stopped bundle is null at junit.framework.Assert.fail(Assert.java:47) at junit.framework.Assert.assertTrue(Assert.java:20) at junit.framework.Assert.assertNotNull(Assert.java:217) at org.osgi.test.cases.framework.junit.dto.DTOTestCase.testArrayServiceReferenceDTO(DTOTestCase.java:429) This is a known deviation in the Core R6 CT and can be ignored. ## Testing a Felix bundle The core CT tests the framework implementation and its related services. The compendium CT tests the various non-framework-related specifications, which are implemented as bundles. For the most part, testing a bundle is similar to testing the framework. Extract the compendium CT JAR file to access the individual test suites. Since most compendium service specification test suites require security, it is necessary to use a framework implementation that supports security. For the Felix framework, you will have to add the security provider to the `-runbundles` to enable security. For example, to test Felix' Event Admin bundle, edit the `-runbundles` setting in `org.osgi.test.cases.event.bnd` to look something like this: :::plaintext -runbundles = \ /path/to/felix/eventadmin/org.apache.felix.eventadmin-1.0.0.jar;version=file,\ /path/to/felix/framework.security/org.apache.felix.framework.security-1.0.0.jar.jar;version=file After editing the BND files to refer to the appropriate bundles, run the tests using: :::plaintext source runtests This will run all test suites for all BND files. To run a specific test suite, do the following: :::bash $ java -jar jar/bnd.jar runtests --title osgi.ct Where `` specifies one or more BND files associated with the desired test suites. Reports for the tests suites are generated in the `reports/` subdirectory and are named after the appropriate test suite. ## Feedback For any questions or feedback, subscribe to the Felix developers mailing list by sending a message to [dev-subscribe@felix.apache.org](mailto:dev-subscribe@felix-apache-org); after subscribing, email questions or feedback to [dev@felix.apache.org](mailto:dev@felix.apache.org). [1]: #security