While the testing framework contains several classes that offer specific features, it is most likely that your test cases will extend org.springframework.osgi.test.AbstractConfigurableBundleCreatorTests (at least this is what we use in practice).

Let's extend this class and interact with the OSGi platform through the bundleContext field:

public class SimpleOsgiTest extends AbstractConfigurableBundleCreatorTests {

public void testOsgiPlatformStarts() throws Exception {
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_VENDOR));
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_VERSION));
	System.out.println(bundleContext.getProperty(Constants.FRAMEWORK_EXECUTIONENVIRONMENT));
	}
}

Simply execute the test as you normally do with any JUnit test. On Equinox 3.2.x, the output is similar to:

Eclipse
1.3.0
OSGi/Minimum-1.0,OSGi/Minimum-1.1,JRE-1.1,J2SE-1.2,J2SE-1.3,J2SE-1.4}

It is likely that you will see different log statements made by the testing framework during your own test execution, but these can be disabled as they only have an informative value and do not affect the actual execution.

Note that you did not have to create any bundle, write any MANIFEST or bother with imports or exports, let alone starting and shutting down the OSGi platform. The testing framework takes care of these automatically when the test is executed.

Let's do some quering and figure out what the environment in which the tests run is. A simple way to do that is to query the BundleContext for the installed bundles:

public void testOsgiEnvironment() throws Exception {
	Bundle[] bundles = bundleContext.getBundles();
	for (int i = 0; i < bundles.length; i++) {
		System.out.print(OsgiStringUtils.nullSafeName(bundles[i]));
		System.out.print(", ");
	}
	System.out.println();
}

The output should be similar to:

OSGi System Bundle, ObjectWeb ASM, log4j.osgi, spring-test, spring-osgi-test, spring-osgi-core, 
    spring-aop, spring-osgi-io, slf4j-api, 
spring-osgi-extender, etc... TestBundle-testOsgiPlatformStarts-com.your.package.SimpleOsgiTest, 

As you can see, the testing framework installs the mandatory requirements required for running the test such as the Spring, Spring DM, slf4j jars among others.

Besides the Spring DM jars and the test itself is highly likely that you depend on several libraries or your own code for the integration test.

Consider the following test that relies on Apache Commons Lang:

import org.apache.commons.lang.time.DateFormatUtils;
    ...
  	public void testCommonsLangDateFormat() throws Exception {
		System.out.println(DateFormatUtils.format(new Date(), "HH:mm:ssZZ"));
	}
}

Running the test however yields an exception:

java.lang.IllegalStateException: Unable to dynamically start generated unit test bundle
     ...
Caused by: org.osgi.framework.BundleException: The bundle could not be resolved. 
Reason: Missing Constraint: Import-Package: org.apache.commons.lang.time; version="0.0.0"
    ...
	... 15 more
	

The test requires org.apache.commons.lang.time package but there is no bundle that exports it. Let's fix this by installing a commons-lang bundle (make sure you use at least version 2.4 which adds the proper OSGi entries to the jar manifest).

One can specify the bundles that she wants to be installed using getTestBundlesNames or getTestBundles method. The first one returns an array of String that indicate the bundle name, package and versioning through as a String while the latter returns an array of Resources that can be used directly for installing the bundles. That is, use getTestBundlesNames when you rely on somebody else to locate (the most common case) the bundles and getTestBundles when you want to locate the bundles yourself.

By default, the test suite performs a lookup for artifacts, similar to the one used by Maven2, searching first the items as being relative to the current project and then falling back to the local repository. The locator expects the bundle String to be a comma separated values containing the artifact group, name, version and (optionally) type. It's likely that in the future, various other locators will be available. One can plug in their own locator through the org.springframework.osgi.test.provisioning.ArtifactLocator interface.

Let's fix our integration test by installing the required bundle (and some extra osgi libraries):

protected String[] getTestBundlesNames() {
	 return new String[] { "net.sourceforge.cglib, com.springsource.net.sf.cglib, 2.1.3",
	 	"javax.transaction, com.springsource.javax.transaction, 1.1.0",
	 	"commons-lang, commons-lang, 2.4" };
	 };
}

Rerunning the test should show that these bundles are now installed in the OSGi platform.

	Note
	The artifacts mentioned above have to exist in your local maven repository.

The testing framework allows a lot of customization to be made. This chapter details some of the existing hooks that you might want to know about. However, these are advanced topics as they increase the complexity of your test infrastructure.

protected Manifest getManifest() {
      // let the testing framework create/load the manifest
      Manifest mf = super.getManifest();
      // add Bundle-Classpath:
      mf.getMainAttributes().putValue(Constants.BUNDLE_CLASSPATH, ".,bundleclasspath/simple.jar");
      return mf;
}

protected String getManifestLocation() {
      return "classpath:com/xyz/abc/test/MyTestTest.MF";
}

Import-Package: junit.framework,
  org.osgi.framework,
  org.apache.commons.logging,
  org.springframework.util,
  org.springframework.osgi.service,
  org.springframework.osgi.util,
  org.springframework.osgi.test,
  org.springframework.context

Spring DM testing suite builds on top of Spring testing classes. To create an application context (OSGi specific), one should just override getConfigLocations[] method and indicate the location of the application context configuration. At runtime, an OSGi application context will be created and cached for the lifetime of the test case.

protected String[] getConfigLocations() {
   return new String[] { "/com/xyz/abc/test/MyTestContext.xml" };
}

The testing framework supports out of the box, three OSGi 4.0 implementations namely: Equinox, Knopflerfish and Felix. To be used, these should be in the test classpath. By default, the testing framework will try to use Equinox platform. This can be configured in several ways:

A built-in feature of the testing framework is the ability to wait until all dependencies are deployed before starting the test execution. Since the OSGi platforms are concurrent by nature, installing a bundle doesn't mean that all its services are running. By running a test before its dependency services are fully initialized can cause sporadic errors that pollute the test results. By default, the testing framework inspects all bundles installed by the user and, if they are Spring-powered bundles, waits until they are fully started (that is their application context is published as an OSGi service). This behaviour can be disabled by overriding shouldWaitForSpringBundlesContextCreation method. Consult AbstractSynchronizedOsgiTests for more details.

Considering all the functionality offered by the testing framework, one might wonder if this doesn't become a performance bottleneck. First, it's worth noting that all the work done automatically by the testing infrastructure has to be done anyway (such as creating the manifest or creating a bundle for the test or installing the bundles). Doing it manually simply does not work as it's too error prone and time consuming. In fact, the current infrastructure started as way to do efficient, automatic testing without worrying about deployment problems and redundancy.

As for the numbers, the current infrastructure has been used internally for the last half a year - our integration tests (around 120) run in about 3:30 minutes on a laptop. Most of this time is spent on starting and stopping the OSGi platform: the "testing framework" takes around 10% (as shown in our profiling so far). For example, the manifest generation has proved to take less then 0.5 seconds in general, while the jar creation around 1 second.

However, we are working on making it even faster and smarter so that less configuration options are needed and the contextual information available in your tests is used as much as possible. If you have any ideas or suggestion, feel free to use our issue tracker or/and forum.