Using OSGi declarative services in the context of a JUnit test

Question

I'm trying to figure out how to implement multi-bundle integration test in OSGi using JUnit.

With integration test, I mean instantiating a subset of the bundles to automatically validate functionality in that subsystem.

We're running Equinox and using Eclipse as toolchain. Eclipse offers the "Run as JUnit Plug-in" option which brings the OSGi framework up and instantiates the configures bundles, so I guess this is the path to follow, but I don't find a way to inject DS references into my tests. I've seen the use of the ServiceTracker as a programmatic means to access the different service bundles, but that beats the purpose of having DS, isn't it?

I am just getting started with OSGI, so I figure I'm just missing some piece of the puzzle that would let me put my multi-bundle tests together.

Any ideas?

Thanks, Gerard.

* EDIT : SOLUTION *

After looking further into this issue, I finally figured out how to put this mult-bundle integration tests in place using the JUnit plug-in feature:

For the dynamic services injection to work, one must create a service definition file where the injected dependencies must be declared, as it's usually done when working with DS. This file goes (typically) under the OSGI-INF/ directory. e.g. OSGI-INF/service.xml

service.xml must declare the required dependencies for this test, but does not offer a service of its own:

service.xml
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="MyTest" activate="startup" deactivate="shutdown">

   <implementation class="com.test.functionaltest.MyTester"/>
   <reference name="OtherService" interface="com.product.service.FooService" policy="static" cardinality="1..1" bind="onServiceUp" unbind="onServiceDown"/>

</scr:component>

This will instruct DS to inject the dependency on FooService using the declared onServiceUp method. onServiceDown must be implemented as it's called during the OSGi shutdown phase after the tests are run.

com.test.functionaltest.MyTester contains the test methods to be executed, following the typical JUnit practices.

Up to here, it's all 'by the book'. Yet, if the Junit is run, it will throw NullPointerException when accessing a reference to FooService. The reason for that is that the OSGi framework is in a race condition with the JUnit tests runner context, and usually, the Junit test runner wins that race, executing the tests before the reference to the required service is injected.

To solve this situation, it's required to make the Junit test to wait for the OSGi runtime to do its work. I addressed this issue by using a CountDownLatch, that is initialized to the number of dependent services required in the test. Then every dependency injection method counts down and when they are all done, the test will start. The code looks like this:

private static CountDownLatch dependencyLatch = new CountDownLatch(1);// 1 = number of dependencies required    
static FooService  fooService = null;   
public void onFooServiceUp(FooService service) {
  fooService = service;
  dependencyLatch.countDown();
}

Note that the fooService reference needs to be static to allow sharing the service reference between the OSGi and the JUnit execution contexts. The CountDownLatch provides a high-level synchronization mechanism for safe publication of this shared reference.

Then, a dependency check should be added before the test execution:

@Before
public void dependencyCheck() {
  // Wait for OSGi dependencies
    try {
      dependencyLatch.await(10, TimeUnit.SECONDS); 
      // Dependencies fulfilled
    } catch (InterruptedException ex)  {
      fail("OSGi dependencies unfulfilled");
    }
}

This way the Junit framework waits for the OSGi DS service to inject the dependencies or fails after the timeout.

It took me quite some time to completely figure this one out. I hope it saves some headache to fellow programmers in the future.

Answer 1

* EDIT : SOLUTION *

After looking further into this issue, I finally figured out how to put this mult-bundle integration tests in place using the JUnit plug-in feature:

For the dynamic services injection to work, one must create a service definition file where the injected dependencies must be declared, as it's usually done when working with DS. This file goes (typically) under the OSGI-INF/ directory. e.g. OSGI-INF/service.xml

service.xml must declare the required dependencies for this test, but does not offer a service of its own:

service.xml
<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="MyTest" activate="startup" deactivate="shutdown">

   <implementation class="com.test.functionaltest.MyTester"/>
   <reference name="OtherService" interface="com.product.service.FooService" policy="static" cardinality="1..1" bind="onServiceUp" unbind="onServiceDown"/>

</scr:component>

This will instruct DS to inject the dependency on FooService using the declared onServiceUp method. onServiceDown must be implemented as it's called during the OSGi shutdown phase after the tests are run.

com.test.functionaltest.MyTester contains the test methods to be executed, following the typical JUnit practices.

Up to here, it's all 'by the book'. Yet, if the Junit is run, it will throw NullPointerException when accessing a reference to FooService. The reason for that is that the OSGi framework is in a race condition with the JUnit tests runner context, and usually, the Junit test runner wins that race, executing the tests before the reference to the required service is injected.

To solve this situation, it's required to make the Junit test to wait for the OSGi runtime to do its work. I addressed this issue by using a CountDownLatch, that is initialized to the number of dependent services required in the test. Then every dependency injection method counts down and when they are all done, the test will start. The code looks like this:

private static CountDownLatch dependencyLatch = new CountDownLatch(1);// 1 = number of dependencies required    
static FooService  fooService = null;   
public void onFooServiceUp(FooService service) {
  fooService = service;
  dependencyLatch.countDown();
}

Note that the fooService reference needs to be static to allow sharing the service reference between the OSGi and the JUnit execution contexts. The CountDownLatch provides a high-level synchronization mechanism for safe publication of this shared reference.

Then, a dependency check should be added before the test execution:

@Before
public void dependencyCheck() {
  // Wait for OSGi dependencies
    try {
      dependencyLatch.await(10, TimeUnit.SECONDS); 
      // Dependencies fulfilled
    } catch (InterruptedException ex)  {
      fail("OSGi dependencies unfulfilled");
    }
}

This way the Junit framework waits for the OSGi DS service to inject the dependencies or fails after the timeout.

It took me quite some time to completely figure this one out. I hope it saves some headache to fellow programmers in the future.

Answer 2

I'm not familiar with the Eclipse tools that you mention, but we've been successfully using Pax Exam for integration testing in Apache Sling. If you are familiar with Maven, the POM at https://svn.apache.org/repos/asf/sling/trunk/installer/it/pom.xml might help you in getting started, and https://github.com/tonit/Learn-PaxExam looks like a good starting point as well.

The Sling testing tools can also help in this context by allowing bundles to contribute JUnit tests to an OSGi framework at runtime, which is useful if your project generates a runnable jar that can be used for testing.

Answer 3

You set it up using the tabs on the run configuration.

So right click, select "run as", select "run configurations...", double click "JUnit Plug-in Test", then add your dependencies on the plugins tab - pretty much the same as the normal launcher

Some links: http://publib.boulder.ibm.com/infocenter/ratdevz/v8r0/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/junit_launcher.htm and http://publib.boulder.ibm.com/infocenter/ratdevz/v8r0/index.jsp?topic=/org.eclipse.pde.doc.user/guide/tools/launchers/junit_main.htm

Answer 4

I guess it would be a bit cleaner to get hold of the org.apache.felix.scr.ScrService and actively wait for the component to become ACTIVE. This interface is implemented by both equinox and felix.

Java doc and API Usage.

Answer 5

I think that in the the above solution the CountDownLatch is not necessary.

The problem is that JUnit in DS Context instantiates a JUnitTest class each for his own. First DS Context instantiates your JUnitTest class and call the binding onFooServiceUp for FooService, but after this JUnit instantiates his own JUnitTest class without calling the binding method onFooServiceUp. In this case the FooService is in the JUnitTest not available.

If you declare the FooService as static (as you have done) and assign in the method onFooServiceUp you don't need the construction with the CountDownLatch.