Wednesday, October 14, 2009

OSGi Unit Testing

With this post I'd like to give a little more background on OSGi unit testing. There will be coverage of
  • Basic problem of OSGi bundle testing
  • Running a unit test inside an OSGi Framework
  • Interaction between a test runner and the OSGi Framework

One of the main characteristics of an OSGi environment is its high dynamicity. Services come and go at any time or get updated by newer versions. To verify that functionality provided by an OSGi Bundle does indeed behave as expected, you need good test coverage of that functionality. This of course is a general truth that is not limited to OSGi alone.

The benefit of unit testing is to isolate functionality and show that it behaves as expected. A unit test provides a strict, written contract that the piece of code must satisfy.

The basic problem in OSGi is that you cannot access the artefacts that you deploy in a bundle directly from the test case that runs external to the OSGi Framework. The test case is loaded from different classloader than the artefacts contained in the bundle.

Embedded OSGi Framework

This is probably the most common usage. A test or a wrapper around a collection of tests bootstraps the OSGi Framework installs a number of bundles and verifies their correct behaviour. Husky test cases leverage the OSGi Framework Launch API. Framework launching should not require prior knowledge of the actual framework implementation. OSGi Framework and test runner share the same VM. From the perspective of the test runner, the test can be executed like an ordinary unit test, which gives the developer the freedom of choice with respect to the runner (i.e. Eclipse, IntelliJ, Maven, Ant). The test reports results back to the runner like an ordinary unit test, which preserves the runner's test report functionality.

Remote OSGi Framework

In an enterprise scenario the OSGi Framework is more often than not a standalone container. The same test as above should be deployable in a remote framework that is already running. It is a configuration option of the test environment of whether the test gets installed into an embedded OSGi Framework or deployed to a remote framework instance. OSGi Framework and test runner do not share the same VM. From the perspective of the test runner, the test can still be executed like an ordinary unit test and it is completely transparent that the test gets actually executed in a remote environment. Conceptually, this is similar to what Apache Cactus is about.

  1. The solution MUST support plain JUnit4 POJO test cases
  2. There SHOULD be no requirement to extend a specific test base class
  3. There MUST be no requirement on a specific test runner
  4. There SHOULD be a minimum test framework leakage into the test case
  5. The test framework MUST support embedded and remote OSGi Runtimes with no change required to the test
  6. The same test case MUST be executable from outside as well as from within the OSGi Framework
  7. There SHOULD be a pluggable communication layer from the test runner to the OSGi Framework
  8. The test framework MUST NOT depend on OSGi Framework specific features
  9. There MUST be no automated creation of test bundles required by the test framework

JBoss OSGi Husky has client side interceptor that fields the test request to an embedded/remote OSGi Framework where the test case is then actually executed.

How does it work
  1. A Bridge intercepts a test and determines the FQN of the test case and the test method from the call stack. It then delegates the execution to the same (or another) test in and isolated test environment. An isolated test environment is one that does not have the same class loading space as the test itself.
  2. A Bridge is associated with an Invoker. Invokers may be arbitarily complex. Local 'in proccess' invokers are possible just as well as remote invokers.
  3. The Invoker sends the Request to a Connector in the isolated test environment.
  4. A Connector has associated PackageListeners that are responsible for processing test cases for their respective test packages.
  5. A PackageListeners delegates the Request to a test Runner, typicaly this would be a JUnitRunner.
  6. The Runner injects the Context into the test case and returns a Response, which the Connector returns to the Invoker.
  7. The Bridge finally translates potential Failures that may be contained in the Result, to test failures on the client side.
The JBoss OSGi jboss-osgi-husky.jar bundle registers the Connectors. The JMXConnector is always registered. The SocketConnector is registered when the appropriate configuration options are set. It then registers the HuskyExtender, which is a BundleListener that inspects every incomming bundle for the Test-Package manifest header. The Extender creates a PackageListener for every package in the 'Test-Package' manifest header and registers them with the available Connectors.


In the target OSGi Framework, which is the one that has the jboss-osgi-husky.jar bundle installed, you set these properties.
# Husky socket connector properties
Both properties must be set for the SocketConnector to be available.

On the client side, you configure the Invoker that you want to use.
# Husky invoker properties

This particular invoker will also look for the host and port properties and if availbale will use socket invocation.

Writing Husky Tests

In a typical Husky test you have
  • A discriminator to distinguish between client and 'in container' execution
  • An interceptor that delegates the call to an Invoker
For OSGi, the "discriminator" would be the BundleContext that gets injected by the 'in container' test Runner. The "interceptor" would be a call to one of the variants.

public class SimpleHuskyTestCase
public BundleContext context;


public void testSimpleBundle() throws Exception
// Tell Husky to run this test method within the OSGi Runtime
if (context == null)

// Stop here if the context is not injected

// Get the SimpleService reference
ServiceReference sref = context.getServiceReference("SimpleService");
assertNotNull("SimpleService Not Null", sref);

// Access the SimpleService
SimpleService service = (SimpleService)context.getService(sref);
assertEquals("hello", service.echo("hello"));

The bundle that contains the test case must have the Test-Package manifest header configured.
Bundle-SymbolicName: example-simple-husky

# Export the package that contains the test case
Export-Package: org.jboss.test.osgi.example.simple

# Tell Husky that there are test cases in this package
Test-Package: org.jboss.test.osgi.example.simple
That's it for now. JBoss OSGi 1.0.0.Beta4 is ready and waiting for the files to show up on Sourceforge. In a follow up post you can read about our new native OSGi Framework implementation that is based on the JBoss Microcontainer and how JBoss OSGi uses Pax Web to provide support for OSGi WebApps.

May this be useful


  1. Hi Thomas,

    Very interesting indeed. But what if the test requires several other bundles to be started before the test can execute?

    I guess this topic covers unit testing, not integration testing?

  2. Hi Thomas,

    Have you seen Pax Exam?


  3. Frederic,

    JBossOSGi Testing + Husky is indeed about integration testing. Over the next few days you should see a blogpost that explores that in more detail.

    Some of it has already been discussed here

  4. To ease integration testing, the Spring Dynamic Modules project provides a test class hierarchy (based on org.springframework.osgi.test.AbstractOsgiTests) that provides support for writing regular JUnit test cases that are then automatically executed in an OSGi environment.

    In general, the scenario supported by Spring-DM testing framework is:
    1. start the OSGi framework
    2. Install and start any specified bundles required for the test
    3. Package the test case itself into a on the fly bundle, generate the manifest and install it in the OSGi framework.
    4. Execute the test case inside the OSGi framework
    5. Shut down the framework
    6. Passes the test results back to the originating test case instance that is running outside of OSGi.

    ceylon tee