Karaf Test Container Reference

Detailed description of all features and options the karaf test container provides.

Depends plugin

<plugin>
  <groupId>org.apache.servicemix.tooling</groupId>
  <artifactId>depends-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>generate-depends-file</id>
      <goals>
        <goal>generate-depends-file</goal>
      </goals>
    </execution>
  </executions>
</plugin>

KarafDistributionOption

Basically the Pax Exam - Karaf bridge introduced with 3.0 should support all commands you know from Pax Exam 2.x. In addition we've added various additional commands to make your life easier. Those commands are listed and explained in this sub section.

As a small remark: All of the Options explained here are also accessible via the static methods in the KarafDistributionOption class in the options package automatically on your classpath when you reference the container package.

KarafDistributionConfigurationOption

All options defined below assume that there is a static import of "KarafDistributionOption.<option>".

The framework itself is non of the typical runtimes you define normally in PAXEXAM. Instead you define a packed distribution as zip or tar.gz. Those distributions have to follow the Karaf packaging style. Therefore instead of Karaf you can also use Servicemix or Geronimo.

MavenArtifactUrlReference karafUrl = maven().groupId("org.apache.karaf").artifactId("apache-karaf").version("3.0.0").type("tar.gz");
MavenArtifactUrlReference servicemixUrl = maven().groupId("org.apache.servicemix").artifactId("apache-servicemix").version("4.4.0").type("zip");

karafDistributionConfiguration().frameworkUrl(karafUrl).unpackDirectory(new File("target/exam")).useDeployFolder(false)

Unpack Directory

unpackDirectory(File dir)

Paxexam-Karaf Testframework extracts the distribution you specify by default into the paxexam config directory. If you would like to unpack them into your target directory simply extend the KarafDistributionConfigurationOption with the unpackDirectoryFile like shown in the next example: 

Use Deploy Folder

useDeployFolder(boolean)

By default exam will use the karaf deploy folder to deploy artifacts defined using ProvisioningOptions like mavenBundle(). This might cause problems with the bundle load order. Setting useDeployFolder(false) will make pax exam use a feature file instead.

editConfigurationFilePut

editConfigurationFilePut(String path, String key, String value)
editConfigurationFilePut(String configurationFilePath, File source, String... keysToUseFromSource)

Replaces or adds an option in one of Karaf's configuration files.

The second variant allows you to add all properties found in an source config file as KarafDistributionConfigurationFilePutOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily put an entire range of properties.

Example:

editConfigurationFilePut( "etc/config.properties", "karaf.framework", "equinox")

Change the OSGi framework to equinox.

editConfigurationFileExtend

This one does the same as the KarafDistributionConfigurationFilePutOption option with the one difference that it either adds or appends a specific property. This is especially useful if you do not want to store the entire configuration in the line in your code.

This option could also be extended in "batch-mode" via a property file. Therefore use the KarafDistributionOption#editConfigurationFileExtend(final String configurationFilePath, File source, String... keysToUseFromSource) method. This option allows you to extend all properties found in the file as KarafDistributionConfigurationFileExtendOption. If you configure the "keysToUseFromSource" array only the keys specified there will be used. That way you can easily extend an entire range of properties.

replaceConfigurationFile

The file replacement option allows you to simply replace a file in you Karaf distribution with a different file:

replaceConfigurationFile("etc/tests.cfg", new File("src/test/resources/test.cfg"));

configureConsole

The test container supports options to configure if the localConsole and/or the remote shell should be started. Possible options to do so are shown in the following two examples:

Example:

configureConsole().ignoreLocalConsole().startRemoteShell()

logLevel

Sets the log level of the karaf container.

logLevel(LogLevel.TRACE)

doNotModifyLogConfiguration 

The option to modify the logging behavior requires that the container automatically modifies the logging configuration file. If you would like to suppress this behavior simply set the doNotModifyLogConfiguration option as shown in the next example: 

keepRuntimeFolder

Per default the test container removes all test runner folders. If you want set the option keepruntimeFolder() then the unpacked karaf runtime will be available in the unpackDir.

KarafDistributionKitConfigurationOption

The KarafDistributionKitConfigurationOption is almost equal to all variations of the KarafDistributionConfigurationOption with the exception that it requires to have set a platform and optionally the executable and the files which should be made executable additionally. By default it is bin/karaf for nix platforms and bin\karaf.bat for windows platforms. The executable option comes in handy if you like to e.g. embed an own java runtime. You should add a windows AND a linux Kit definition. The framework automatically takes the correct one then. The following shows a simple example for karaf:

@Configuration
public Option[] config() {
    return new Option[]{
        new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/3.0.1-SNAPSHOT/zip",
            Platform.WINDOWS).executable("bin\\karaf.bat").filesToMakeExecutable("bin\\admin.bat"),
        new KarafDistributionKitConfigurationOption("mvn:org.apache.karaf/apache-karaf/3.0.1-SNAPSHOT/tar.gz", "karaf",
            Platform.NIX).executable("bin/karaf").filesToMakeExecutable("bin/admin") };
}

CoreOptions

bootDelegationPackage

The BootDelegationOption as known from PaxExam is also supported added the boot delegation string directly into the correct property files.

systemPackage

The Standard Exam SystemPackageOption is implemented by adding those packages to "org.osgi.framework.system.packages.extra" of the config.properties file.

bootClasspathLibraries

The BootClasspathLibraryOption is honored by copying the urls into the lib directory where they are automatically taken and worked on.

useOwnExamBundlesStartLevel 

useOwnExamBundlesStartLevel(int level)

The ExamBundlesStartLevel can be used to configure the start lvl of the bundles provided by the test-frameworks features.xml.

mavenBundle

mavenBundle().groupId("org.ops4j.pax.exam.samples").artifactId("pax-exam-sample8-ds").versionAsInProject()