Pax-Exam test runner for in-application testing of bundles, kar modules and services for applications based on OSGi including Karaf and OpenNMS. It can be used for generic projects based on Karaf and for more specific development and testing with OpenNMS.
TL;DR To run some test examples see:
For a brief video tutorial see:
OpenNMS Pax-exam demonstration video
More advanced examples with videos are also provided in misc-examples
See issues and known work-arounds at FAQ issues
See Release Notes for details on the latest release.
Pax-Exam is a fantastic test framework which supports in-container testing.
In normal operation, Pax-Exam downloads and provisions a Karaf OSGi container before injecting a bundle of Junit 4 tests (called a test probe) to test the services running in the framework.
This is fine for development testing but what if you have a complex application which already embeds Karaf? In this case we don't want to download a fresh karaf, but rather run the tests within the karaf already present in the application.
This project extends the Pax-Exam code to allow it to run Junit tests against an already running Karaf runtime.
The motivation for this project is to make it considerably easier to create and test both plugins and advanced configurations for OpenNMS without having to restart OpenNMS for each change in configuration.
OpenNMS is a complex open source network management application written in java and using the Karaf OSGi implementation.
Karaf is used as a run-time container within the core OpenNMS and also within distributed Minion and Sentinel modules.
OpenNMS does makes some limited use of Pax-Exam within it's development test api and when testing some karaf modules. See for instance KarafTestCase.java. However this is a complex internal use of Pax-exam which requires Pax-exam to run its Karaf test container in-test. It does not provide an easy to use example for external plugin development or testing.
The OpenNMS Plugin API leverages OSGi to allow plugins to be deployed and registered in a running OpenNMS application. Plugins are the preferred mechanism for external parties to create additional functionality for OpenNMS without having to modify the core OpenNMS code.
Plugins are a great idea but until now, it has been difficult to independently develop and test OpenNMS plugins without building a test framework for the module within the code base of the core OpenNMS application. Setting up a development environment has been a complex and error prone activity for a new developer.
To make plugin development easier, we wanted to create a simple to deploy test harness which can be used by plugin developers without having to dig into the core OpenNMS code.
In addition, we wanted to make it easier to run tests against advanced configurations such as Drools rules or alarm/event configurations.
By allowing us to inject tests and run them within a running pre-built OpenNMS it is possible for tests to directly access running OpenNMS services and data through the OpenNMS DAO's. This allows pre-test data-fill and event injection to be performed directly on a running system and the results to be monitored as part of a test. Ultimately this provides for more realistic and easier to configure integration testing than trying to create mock test frameworks or DAO's for specific modules as is done during development testing.
In summary the design goals for this project are to create a test framework which :
- Runs a full pre-built OpenNMS release instance with all dependencies within a docker-compose project on docker desktop - ideally supporting configurations based on the opennms-forge stackplay docker-compose examples.
- Allows any local configurations to be applied through the opennms docker overlay mechanism
- Provides simple to configure examples of how to set up OpenNMS (or karaf) to work with the external pax-exam project.
- Injects karaf commands and Junit tests using RMI from an external test project.
For more detailed information on how the system works see
To run some test examples see
More advanced examples with videos are also provided in misc-examples
The main branch is the development branch for opennms-paxexam. All artifacts are versioned with the next release SNAPSHOT
The master branch is the last published release and each release is also tagged on release.
The example test projects are intended to be copied and modified. (We may create an archetype later). They are not published to maven and always use SNAPSHOT versioning which matches every release (0.0.2-SNAPSHOT 0.0.2-SNAPSHOT etc)
The example test projects reference the version of the opennms-paxexam system they are using.
Change the opennms-paxexam.version property to use a different published version of opennms-paxexam (e.g. replace 0.0.2-SNAPSHOT with 0.0.1).
<properties>
...
<opennms-paxexam.version>0.0.2-SNAPSHOT</opennms-paxexam.version>
...
</properties>
Only the core opennms-paxexam system modules are are published to maven. That is, only the modules built under opennms-paxexam-parent.
For stability, only release versions are published. i.e. 0.0.1 and never 0.0.2-SNAPSHOT
Build the opennms-paxexam-parent modules locally if you want to work with snapshots.
The example test projects contain repository references to allow them to download releases of the published system.
At the moment, the opennms-paxexam system is being published to a github packages maven repository associated with the github opennms-paxexam project. This will probably change in future releases.
<repositories>
<repository>
<id>central</id>
<url>https://repo1.maven.org/maven2</url>
</repository>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/gallenc/opennms-paxexam</url>
<snapshots>
<!-- we only publish release versions of opennms-paxexam to github packages -->
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
This project is licensed under the Apache 2 licence.
Much of the extension work has built upon the excellent Pax-Exam project. Apache licence (Copyright 2008 written by Toni Menzel and others).
In addition some test examples from the Karaf-Cassandra project have also been adapted. Apache licence (Copyright 2015 Achim Nierbeck)
OpenNMS is licensed under the AGPL v3 licence. Any code linking to or extending OpenNMS code should be similarly licensed.
For this reason, the OpenNMS example in this project does NOT use any of the core OpenNMS api's but only generic Karaf commands.
A separate project will be provided to show example test cases which link directly to the OpenNMS api.