Karaf Container

The karaf test container allows to run OSGi tests inside a real Apache Karaf container. It was added to pax exam in version 3.1.0.

Karaf Test Container Reference

Upgrading from Karaf's own container

The Pax Exam Karaf Test Container is based on and supersedes the Karaf Exam test container from the Apache Karaf codebase. The Apache Karaf and Pax Exam communities both agreed that the Karaf test container would be easier to maintain as a Pax Exam module, so Pax Exam 3.1.0 is the first release to incorporate the Karaf test container, using Karaf 3.0.0.RC1 as a starting point.

Packages org.apache.karaf.tooling.exam.* have been renamed to org.ops4j.pax.exam.karaf.*.
The scanFeatures() option method for provisioning Karaf features which was dropped in Pax Exam 3.0.0 along with the Pax Runner Container has been superseded by org.ops4j.pax.exam.karaf.options.KarafDistributionOption.features()

Getting started

The fastest way to start is to copy the exam-itest-sample-karaf and adapt it to your needs. This example will be explained in this getting started guide.

pom Dependencies

Dependencies for pax exam karaf container

        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam-container-karaf</artifactId>
            <version>${pax.exam.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam-junit4</artifactId>
            <version>${pax.exam.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.exam</groupId>
            <artifactId>pax-exam</artifactId>
            <version>${pax.exam.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.ops4j.pax.url</groupId>
            <artifactId>pax-url-aether</artifactId>
            <version>1.6.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>javax.inject</groupId>
            <artifactId>javax.inject</artifactId>
            <version>1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>

Depends maven plugin

Bundle and feature versions can be refered to with versionAsInProject() instead of specifying a concrete version number. This requires to add the depends maven plugin to your build. You will also have to specify a maven dependency for every bundle or feaure your refer in this way.

Depends maven plugin

    <build>
        <plugins>
            <!-- Needed if you use versionAsInProject() -->
            <plugin>
                <groupId>org.apache.servicemix.tooling</groupId>
                <artifactId>depends-maven-plugin</artifactId>
                <version>1.2</version>
                <executions>
                    <execution>
                        <id>generate-depends-file</id>
                        <goals>
                            <goal>generate-depends-file</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

A basic Test

Tests using the karaf test container are similar to other pax exam OSGi tests. The main difference is that you need to specify the karaf container to run with and have some additional options using KarafDistributionOption.

Configurations for Karaf

    @Configuration
    public Option[] config() {
        MavenArtifactUrlReference karafUrl = maven()
            .groupId("org.apache.karaf")
            .artifactId("apache-karaf")
            .version("3.0.0")
            .type("tar.gz");
        MavenUrlReference karafStandardRepo = maven()
            .groupId("org.apache.karaf.features")
            .artifactId("standard")
            .classifier("features")
            .type("xml")
            .versionAsInProject();
        return new Option[] {
            // KarafDistributionOption.debugConfiguration("5005", true),
            karafDistributionConfiguration()
                .frameworkUrl(karafUrl)
                .unpackDirectory(new File("target/exam"))
                .useDeployFolder(false),
            keepRuntimeFolder(),
            features(karafStandardRepo , "scr"),
            mavenBundle()
                .groupId("org.ops4j.pax.exam.samples")
                .artifactId("pax-exam-sample8-ds")
                .versionAsInProject().start(),
       };
    }

The config above defines a karaf 3 container. Which is unpacked to target/exam/<guid>.
The features option allows to install karaf feature repositories and features.
Besides features it is also still possible to install simple bundles.

For the full test refer to CalculatorITest.

More Details

This section will be completed step by step. For the time being, please take at look at the original Karaf documentation for more details.