Testing OSGi applications and services has always been a difficult challenge. Despite the development of several frameworks such as OPS4J Pax Exam, or junit4osgi, writing tests requires a non-negligible amount of code to manage the OSGi aspect of the test. Indeed, waiting and getting the service under test or releasing the service requires dealing directly with the OSGi framework and so the OSGi API. The OSGi Helper library is a small collection of classes to let tests focus on the behavior to verify instead of drowning the code in the depths of the OSGi development model.

The OSGi Helper library was developed by the Innovation department of akquinet, and was contributed to the OW2 Chameleon project.

This post explains the benefits brought by the library in comparison to plain OSGi tests.

Plain OSGi testing

Let’s imagine the well-known Hello Service:

public interface HelloService {
    public String sayHello();
    public String sayHello(String name);
}

Let’s also imagine a really great implementation:

@Component
@Provides
@Instantiate
public class HelloServiceImpl implements HelloService {

    public String sayHello() {
        return "hello";
    }

    public String sayHello(String name) {
        return "hello " + name;
    }
}

This implementation is using the Apache Felix iPOJO component model, but you can imagine any other development model such as plain OSGi, SCR or Blueprint.

Now that we have our application, let’s look at a simple OSGi test for our Hello Service:

@Test
public void testWithoutHelpers() throws Exception {
    HelloService service = null;
    ServiceReference ref = null;
    for (int i = 0; service == null  && i < 10; i++) {
        ref = context
            .getServiceReference(
               HelloService.class.getName());
        if (ref == null) {
            // Wait until the service is there...
            Thread.sleep(10);
        } else {
            service = (HelloService) 
                context.getService(ref);
        }
    }

    Assert.assertNotNull(service);

    // We have the service object, run the test
    Assert.assertEquals("hello", service.sayHello());
    Assert.assertEquals("hello John", 
               service.sayHello("John"));

    context.ungetService(ref);
}

The above code uses Pax Exam, but the code would be pretty much the same if you use another testing framework.
Notice that this test contains more OSGi code than functional test.

Using the OSGi Helper Library

Let’s now see how our test looks like when using the library:

@Test
public void testWithHelpers() throws Exception {
    HelloService service = helper.waitForService(HelloService.class, null, 1000);
    Assert.assertEquals("hello", service.sayHello());
    Assert.assertEquals("hello John", service.sayHello("John"));
}

The complete code is available from here.

Thanks to the OSGi Helper, the test method focuses only on the functional behavior. The waitForService method is looking for the service. If the service is not available before the given timeout (in milliseconds), the test fails. Thanks to this simple method, getting the service to test is definitely simpler. Moreover, you don’t need to release the service. The OSGi helper does it for you.

OSGi Assertions

The OSGi Helper library also provides a couple of assertions to check the OSGi aspect of the application (deployed bundles, available services…). The following method gives you a short overview of such assertions:

@Test
public void testWithAssertions() throws Exception {
    OSGiAssert assertions = new OSGiAssert(context);

    assertions.assertServiceAvailable(HelloService.class, 1000);

    assertions.assertBundlePresent("hello-service-impl");
    Bundle bundle = helper.getBundle("hello-service-impl");
    bundle.stop();
    assertions
        .assertBundleState("hello-service-impl", Bundle.RESOLVED);

    assertions.assertServiceUnavailable(HelloService.class);

    bundle.start();
    assertions
        .assertBundleState("hello-service-impl", Bundle.ACTIVE);
    assertions.assertServiceAvailable(HelloService.class, 1000);
}

Conclusion

This blog post has presented a brief overview of the OSGi Helper library. This library contains more good stuff to test OSGi and iPOJO applications.
The code of this blog post is available from Github.

The OSGi Helper library was developed by the Innovation team of akquinet in order to improve the testability and the quality of OSGi applications. The library is now part of the OW2 Chameleon project and delivered under the Apache License 2.0.