OSGi Mocks
Mock implementation of selected OSGi APIs for easier testing.
Maven Dependency
For JUnit 5:
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.testing.osgi-mock.junit5</artifactId>
</dependency>
For JUnit 4:
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.testing.osgi-mock.junit4</artifactId>
</dependency>
See latest version on the downloads page.
There are two major version ranges available:
- osgi-mock 1.x: compatible with OSGi R4 and above, JUnit 4
- osgi-mock 2.x: compatible with OSGi R6 and above, JUnit 4 and JUnit 5
Implemented mock features
The mock implementation supports:
- Instantiating OSGi
Bundle
,BundleContext
andComponentContext
objects and navigate between them. - Register OSGi SCR services and get references to service instances
- Supports reading OSGi SCR metadata from
/OSGI-INF/<pid>.xml
and from/OSGI-INF/serviceComponents.xml
- Apply service properties/component configuration provided in unit test and from SCR metadata
- Inject SCR dependencies - static and dynamic
- Call lifecycle methods for activating, deactivating or modifying SCR components
- Service and bundle listener implementation
- Mock implementation of
LogService
which logs to SLF4J in JUnit context - Mock implementation of
EventAdmin
which supportsEventHandler
services - Mock implementation of
ConfigAdmin
- Context Plugins
Since osgi-mock 2.0.0:
- Support OSGi R6 and Declarative Services 1.3: Field-based reference bindings and component property types
Usage
The OsgiContext
object provides access to mock implementations of:
- OSGi Component Context
- OSGi Bundle Context
Additionally it supports:
- Registering and activating OSGi services and inject dependencies
JUnit 5: OSGi Context JUnit Extension
The OSGi mock context can be injected into a JUnit test using a custom JUnit extension named OsgiContextExtension
. This extension takes care of all initialization and cleanup tasks required to make sure all unit tests can run independently (and in parallel, if required).
Example:
@ExtendWith(OsgiContextExtension.class)
public class ExampleTest {
private final OsgiContext context = new OsgiContext();
@Test
public void testSomething() {
// register and activate service with configuration
MyService service1 = context.registerInjectActivateService(new MyService(),
"prop1", "value1");
// get service instance
OtherService service2 = context.getService(OtherService.class);
}
}
It is possible to combine such a unit test with a @ExtendWith
annotation e.g. for Mockito JUnit Jupiter Extension.
JUnit 4: OSGi Context JUnit Rule
The OSGi mock context can be injected into a JUnit test using a custom JUnit rule named OsgiContext
. This rule takes care of all initialization and cleanup tasks required to make sure all unit tests can run independently (and in parallel, if required).
Example:
public class ExampleTest {
@Rule
public final OsgiContext context = new OsgiContext();
@Test
public void testSomething() {
// register and activate service with configuration
MyService service1 = context.registerInjectActivateService(new MyService(),
"prop1", "value1");
// get service instance
OtherService service2 = context.getService(OtherService.class);
}
}
It is possible to combine such a unit test with a @RunWith
annotation e.g. for Mockito JUnit Runner.
Getting OSGi mock objects
The factory class MockOsgi
allows to instantiate the different mock implementations.
Example:
// get bundle context
BundleContext bundleContext = MockOsgi.newBundleContext();
// get component context with configuration
BundleContext bundleContext = MockOsgi.newComponentContext(properties,
"prop1", "value1");
It is possible to simulate registering of OSGi services (backed by a simple hash map internally):
// register service
bundleContext.registerService(MyClass.class, myService, properties);
// get service instance
ServiceReference ref = bundleContext.getServiceReference(MyClass.class.getName());
MyClass service = bundleContext.getService(ref);
Activation and Dependency Injection
It is possible to simulate OSGi service activation, deactivation and dependency injection and the mock implementation tries to to its best to execute all as expected for an OSGi environment.
Example:
// get bundle context
BundleContext bundleContext = MockOsgi.newBundleContext();
// create service instance manually
MyService service = new MyService();
// inject dependencies
MockOsgi.injectServices(service, bundleContext);
// activate service
MockOsgi.activate(service, props);
// operate with service...
// deactivate service
MockOsgi.deactivate(service);
Please note:
- You should ensure that you register you services in the correct order of their dependency chain. Only dynamic references will be handled automatically independent of registration order.
- The injectServices, activate and deactivate Methods can only work properly when the SCR XML metadata files are preset in the classpath at
/OSGI-INF
. They are generated automatically by the Maven SCR plugin, but might be missing if your clean and build the project within your IDE (e.g. Eclipse). In this case you have to compile the project again with maven and can run the tests - or use a Maven IDE Integration like m2eclipse.
Provide your own configuration via ConfigAdmin
If you want to provide your own configuration to an OSGi service that you do not register and activate itself in the mock context you can provide your own custom OSGi configuration via the mock implementation of the ConfigAdmin
service.
Example:
ConfigurationAdmin configAdmin = context.getService(ConfigurationAdmin.class);
Configuration myServiceConfig = configAdmin.getConfiguration(MY_SERVICE_PID);
Dictionary<String, Object> props = new Hashtable<String, Object>();
props.put("prop1", "value1");
myServiceConfig.update(props);
Context Plugins
OSGi Mocks supports "Context Plugins" that hook into the lifecycle of each test run and can prepare test setup before or after the other setUp actions, and execute test tear down code before or after the other tearDown action.
To define a plugin implement the org.apache.sling.testing.mock.osgi.context.ContextPlugin<OsgiContextImpl>
interface. For convenience it is recommended to extend the abstract class org.apache.sling.testing.mock.osgi.context.AbstractContextPlugin<OsgiContextImpl>
. These plugins can be used with OSGi Mock context, but also with context instances deriving from it like Sling Mocks and AEM Mocks. In most cases you would just override the afterSetUp
method. In this method you can register additional OSGi services or do other preparation work. It is recommended to define a constant pointing to a singleton of a plugin instance for using it.
To use a plugin in your unit test class, use the OsgiContextBuilder
class instead of directly instantiating the OsgiContext
class. This allows you in a fluent style to configure more options, with the plugin(...)
method you can add one or more plugins.
Example:
OsgiContext context = new OsgiContextBuilder().plugin(MY_PLUGIN).build();
More examples: