Testing Java OSGi bundles with the PAX Exam framework
OSGi turns a Java application into a set of modules called bundles, each with its own lifecycle, class loader and declared package dependencies. A unit test can prove that a pricing class calculates correctly, but it cannot show whether the bundle resolves, starts, registers a service or receives configuration in a live service registry. Those contracts sit at the boundary where integration failures tend to appear.
PAX Exam is a JUnit-oriented test harness for container-based integration testing. It can provision an OSGi runtime, commonly Apache Felix or Eclipse Equinox, run test code against it and inject framework objects such as a bundle context. Probes and fixtures can supply configuration, services and test dependencies, allowing a team to exercise real bundle activation without starting the entire production platform.
This approach is particularly relevant in Australia, where Java and OSGi deployments remain common in banking, telecommunications, logistics and mining systems, including platforms supported from Sydney, Melbourne and Brisbane. A small, repeatable runtime gives engineers working across these locations a more dependable release signal than relying only on mocked interfaces or a developer’s long-running workstation.
How PAX Exam fits an OSGi test strategy
PAX Exam occupies the space between fast unit tests and costly end-to-end environment tests. Choose it when the behaviour under risk comes from OSGi mechanics: mandatory imports, class-loader visibility, Declarative Services activation, service lookup, configuration policies or clean shutdown.
| Test approach | Runtime | OSGi behaviour covered | Typical use |
|---|---|---|---|
| Plain JUnit | Application class path | Little or none | Pure business logic |
| Mockito | Application class path | Mocked interfaces only | Collaborator branches |
| PAX Exam | Provisioned OSGi framework | Resolution, lifecycle, registry and wiring | Bundle integration |
| Custom Felix harness | Hand-built framework | Potentially broad | Legacy suites needing control |
The distinction is not simply “more realistic”. A plain JUnit test is better when the OSGi framework is irrelevant, while a full staging system is better reserved for workflow and deployment checks. PAX Exam targets the missing layer: a real framework with a small, controlled fixture. That keeps feedback comparatively quick while exposing defects that mocks can conceal.
Use PAX Exam for the public contracts your consumers rely on. Keep algorithm tests as ordinary unit tests, and avoid turning every test class into a framework boot. This balance preserves speed and makes failures easier to classify.
Building a reproducible PAX Exam harness
A separate test-bundle module is usually cleaner than hiding integration fixtures inside the production bundle. The Maven build can produce a normal OSGi manifest with maven-bundle-plugin, then add the PAX Exam artifacts and the JUnit adapter appropriate to the pinned release. Surefire or Failsafe can own the execution phase, but both the production bundle and its fixture bundles must reach the same runtime.
Pin the Java version, Maven plugins, PAX Exam version, OSGi framework and framework configuration. Reuse one dependency-resolution policy for local and CI builds, and seed the runtime from a dedicated local repository rather than relying on whatever happens to be installed on a laptop. A clean command such as mvn clean verify should create the framework, execute the tests and remove temporary state. If the test needs a particular framework distribution or bundle URL, make that an explicit Maven property instead of an undocumented machine setting.
PAX Exam’s test execution and dependency injection provide access to BundleContext, while probes can expose configuration or controlled collaborators. A typical fixture bundle contains only the components needed by the scenario: a producer service, a consumer component or a policy file. Assert framework state through injected framework APIs rather than by inspecting private fields. This approach keeps the test aligned with the same abstractions used in production.
Testing bundle wiring and lifecycle
Begin with a resolution test. Install the candidate bundle and every mandatory dependency into the runtime, then verify that the bundle reaches RESOLVED and, after activation, ACTIVE. A useful failure message should list missing mandatory imports and unsatisfied capabilities. This single check catches packaging errors that may remain invisible when application code is loaded directly from the class path.
Next, test service publication and consumption through the OSGi service registry. The whiteboard pattern is common: one component publishes a service under a stable interface, and another looks it up through ServiceTracker or an injected reference. Declarative Services activation can be asynchronous, so use a bounded polling utility or event-driven callback and fail with the observed component state. Fixed sleeps make builds slow and still fail intermittently when a CI machine is under load.
Class-loader boundaries deserve equal attention. A bundle must import packages explicitly, while exported packages should be limited to an intentional API. Test that a consumer cannot see an implementation-only package and that removing a required export prevents accidental linkage. Also cover start, stop and restart behaviour, ensuring registrations are withdrawn and no stale service remains after a component is disabled.
Controlling dependencies, data and side effects
Mocking remains useful, but place it at the business boundary rather than around the OSGi lifecycle. Register a small fake implementation in the service registry when a consumer only needs a specific response. Use Mockito for plain value objects and isolated decision logic, while allowing real bundle activation, dependency injection and service lookup to run inside the framework. Mocking BundleContext itself can produce green tests that say little about actual OSGi behaviour.
External effects need controlled substitutes. Use a temporary directory for files, an HTTP stub such as WireMock for HTTP calls, and a disposable database or container for persistence. Give each test unique ports and storage paths so it can run in parallel. Containers such as Testcontainers can suit CI, but the build image must support its runtime, including Docker access and enough memory for the container and the OSGi framework together.
Test data should be synthetic and minimal. Where the Privacy Act 1988 and Australian Privacy Principles apply, customer identifiers, addresses and account histories must not leak into source control, reports or CI artefacts. Generate records with clearly fictional values and redact captured logs. Clock and locale behaviour also needs deliberate coverage: Australia/Sydney changes offset during daylight saving, while Australia/Brisbane remains on UTC+10. A fixed instant and explicit time zone prevent seasonal failures in Australian deployments.
Running the suite in continuous delivery
Run the integration suite as a required stage in the delivery pipeline, commonly through mvn clean verify, and preserve its reports as build artefacts. Collect framework logs alongside JUnit output because bundle-resolution errors often appear before an assertion runs. Label failures by phase—resolution, activation, service discovery or behaviour—so an engineer can distinguish a packaging defect from a changed contract without reproducing everything locally.
A small compatibility matrix creates useful confidence. Run the critical scenarios on the Java versions supported by customers, such as 17 and 21, and on the OSGi framework implementation used in production. Pin every version in the build definition, and separate environment-specific configuration from test logic. Avoid parallel execution only when suites share fixed resources; isolated directories and dynamically assigned ports usually make safe parallelism practical.
Reproducibility matters when teams are distributed across Australian cities or work with offshore support partners. Store dependency downloads in the normal build cache, but never cache mutable framework storage between jobs. Give each CI worker a clean temporary directory and publish the exact commit, dependency resolution data and test reports. That evidence makes an intermittent failure reproducible in another timezone and protects release decisions from assumptions based on one workstation.
A practical PAX Exam checklist
A maintainable bundle suite depends on a few disciplined checks rather than a large collection of framework-specific tricks.
- Pin PAX Exam, the OSGi framework, Java and build-plugin versions in one reviewed build definition.
- Assert bundle resolution, activation, service registration and shutdown through observable OSGi contracts.
- Replace fixed delays with bounded waits that report component and service state on timeout.
- Keep external systems replaceable, test data synthetic and temporary resources isolated.
- Archive framework logs and JUnit reports with the build metadata for every pipeline run.
The practical takeaway is to treat each PAX Exam run as a miniature deployment: packages resolve, components start, services appear and everything is released cleanly. A focused suite built on those contracts gives the release pipeline a dependable signal without recreating the complexity of the full production platform.