Configuration Options

Basics

A Pax Exam test is configured either by means of configuration methods annotated by @Configuration with return type Option[], or by a ConfigurationFactory, see next section.

Option is nothing but a marker interface. Options are created by static methods in org.ops4j.pax.exam.CoreOptions. Pax Exam users should never directly work with classes implementing Option.

Options can be container-specific. In particular, there is a large number of options for the Pax Runner Container which directly correspond to Pax Runner command line arguments. These options are just syntactic sugar for rawPaxRunnerOption(arg).

Pax Exam containers log a warning for each unsupported option type. Make sure to set up logging correctly to avoid missing these warnings.

Option Categories

Roughly speaking, options can be categorized into

provisioning options
property options
framework selection options
Pax Runner options

Provisioning options are used to provision bundles to the OSGi framework under test. Usually, each provisioning option (e.g. bundle()) provisions a single bundle, but there are some convenience options (e.g. junitBundles()) which provision groups of related bundles.

Property options are used to set system properties, OSGi framework properties or VM arguments for a forked Java Virtual Machine, where applicable.

Framework selection options can be used to define the OSGi framework(s) for running the tests. This does not apply to the Native Container, where the OSGi framework is determined by the first FrameworkFactory found on the classpath by means of Java SE 6 service lookup.

Pax Runner options wrap Pax Runner command line arguments, as you may have guessed, and they only apply to the Pax Runner Container.

As of Pax Exam 2.3.0, this page fully documents all options for the Native Test Container. Pax Runner Test Container options are now considered legacy and most of these are likely to be deprecated and dropped in future releases of Pax Exam.

Documenting these options would require digging into the (somewhat outdated and incomplete) Pax Runner documentation and/or the source code. This is not very likely to happen, unless someone volunteers to do it.

Option Overview

Option Details

allEquinoxVersions

Containers: Pax Runner

all versions (all versions known by the moment that Pax Exam was released)
```
allEquinoxVersions()
```

allFelixVersions

Containers: Pax Runner

all versions (all versions known by the moment that Pax Exam was released)
```
allFelixVersions()
```

allFrameworks

Containers: Pax Runner

latest version of each framework
```
allFrameworks()
```

allFrameworksVersions

Containers: Pax Runner

all versions of all frameworks
```
allFrameworksVersions()
```

allKnopflerfishVersions

Containers: Pax Runner

all versions (all versions known by the moment that Pax Exam was released)
```
allKnopflerfishVersions()
```

autoWrap

Containers: Pax Runner

automatically wrap all non-OSGi JARs as OSGi bundles
```
autoWrap()
```

Alternatively, you can use wrapBundle() for individual JARs, which also works for the Native Container.

bootClasspathLibraries

Containers: Pax Runner

bootClasspathLibrary

Containers: Pax Runner

bootDelegationPackage

Containers: Native, Pax Runner

Adds a package name to the org.osgi.framework.bootdelegation framework property.
```
bootDelegationPackage("sun.*")
```

bootDelegationPackages

Containers: Native, Pax Runner

Adds multiple package names to the org.osgi.framework.bootdelegation framework property.
```
bootDelegationPackages(
 "sun.*",
 "com.sun.*"
)
```

bundle

Containers: Native, Pax Runner

You can provision any bundle by its URL (any known protocols are accepted):

from http

bundle("http://repository.ops4j.org/maven2/org/ops4j/pax/url/pax-web-service/0.5.1/pax-web-service-0.5.1.jar")

from file

bundle("file:/home/adreghiciu/development/pax-web-service-0.5.1.jar")

cleanCaches

Containers: Native, Pax Runner

clean the caches of downloaded and provisioned bundles when Pax Exam terminates
```
cleanCaches()
```

cleanCaches(true)

keep the caches
```
cleanCaches(false)
```

The last case is equivalent to keepCaches()

compendiumProfile

Containers: Pax Runner

composite

Containers: Native, Pax Runner

Groups multiple options into one composite option. This is useful to build your own option methods, e.g.

public static Option baseBundles() {
    return combine(
        mavenBundle("com.example.foo", "common", "1.0.0"),
        mavenBundle("com.example.foo", "util", "1.0.0"));
}

configProfile

Containers: Pax Runner

customFramework

Containers: Pax Runner

use an OSGi framework version not pre-configured in Pax Exam

customFramework("equinox", "http://download.eclipse.org/equinox/drops/S-3.8M1-201108031800/org.eclipse.osgi_3.8.0.v20110726-1606.jar", "Equinox 3.8M1")

This only works for unknown versions of known frameworks (i.e. Equinox, Felix or Knopflerfish), but not for unknown frameworks.

debugClassLoading

Containers: Pax Runner

dsProfile

Containers: Pax Runner

easyMockBundles

Containers: Native, Pax Runner

Provisions a default version of EasyMock. The current version is 2.3.0.

equinox

Containers: Pax Runner

latest version (will use the latest version by the moment that Pax Exam was released)
```
equinox()
```

specific version
```
equinox().version("1.0.4")
```

more than one version

equinox().version("3.5.0"),
equinox().version("3.6.2")

excludeDefaultRepositories

Containers: Pax Runner

felix

Containers: Pax Runner

latest version (will use the latest version by the moment that Pax Exam was released)
```
felix()
```

specific version
```
felix().version("1.0.4")
```

more than one version

felix().version("1.0.4"),
felix().version("1.4.0")

frameworks

Containers: Pax Runner

frameworkStartLevel

Containers: Native, Pax Runner

set the OSGi framework start level to a given value (a positive number).
```
frameworkStartLevel(6)
```

jmockBundles

Containers: Native, Pax Runner

provisions a default version of JMock and its dependencies.
```
jmockBundles()
```

junitBundles

Containers: Native, Pax Runner

provisions a default version of JUnit and its dependencies. The current version is 4.9.0.
```
junitBundles()
```

The current default is org.junit:com.springsource.org.junit:4.9.0 which embeds the Hamcrest dependency.

This option is recommended when using the JUnit driver. If you wish to use a different version, replace this option by any other provisioning option specifying an explicit version of an OSGified JUnit artifact.

keepCaches

Containers: Native, Pax Runner

keep the caches of downloaded and provisioned bundles, which are deleted by default when Pax Exam terminates
```
keepCaches()
```

This is equivalent to cleanCaches(false).

knopflerfish

Containers: Pax Runner

latest version (will use the latest version by the moment that Pax Exam was released)
```
knopflerfish()
```

specific version
```
knopflerfish().version("2.2.0")
```

more than one version

knopflerfish().version("2.1.1"),
knopflerfish().version("2.2.0")

localRepository

Containers: Pax Runner

logProfile

Containers: Pax Runner

maven

Containers: Native, Pax Runner

reference a non-OSGi Maven artifact in terms of its Maven coordinates

maven().groupId("postgresql").artifactId("postgresql").version("8.4-701.jdbc4")

shortcut:

maven("postgresql", "postgresql", "8.4-701.jdbc4")

reference the latest version of a non-OSGi Maven artifact in terms Maven groupId and artifactId
```
maven().groupId("postgresql").artifactId("postgresql")
```

shortcut:
```
maven("postgresql", "postgresql")
```

mavenBundle

Containers: Native, Pax Runner

You can provision a bundle in terms of its Maven coordinates. Pax Exam uses the official Maven APIs to resolve an artifact from its coordinates from any of the repositories configured in Maven settings or by other Pax Exam options.

This option makes use of Mvn Protocol url protocol handler.

specifying an exact version

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.1")

a snapshot version

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.2-SNAPSHOT")

latest version (version not specified).

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service")

This will make maven url handler to search for the latest released version.

using a version range

mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("[0.1.0,1.0.0)")

This will make maven url handler to search for the highest released version between 0.1.0 (inclusive) and 1.0.0 (exclusive).

Bundle start options

All provisioning options (as the ones above) support setting up of:

bundle should be started or not
```
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").noStart()
```
If noStart() is used then the bundle will not be started. By default ( = noStart() not used) the bundle will be started.

bundle content (jar file) should be updated
```
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").update()
```
If update() is used then the bundle will be updated, meaning that the content of the bundle will be re-read from the original source (url). By default ( = update() not used) the bundle will not be updated, meaning that a cached bundle will be used from a previous run. There is one exception to this rule. If the provisioning option is a Maven bundle and the version is a SNAPSHOT version, by default the bundle will be updated automatically even if the update() is not used.
The reason behind not updating the bundles by default is related to performance, as re-downloading the bundles can be time consuming process and in most of the cases the bundle content will be the same. So, be sure that on bundles that you know that cange between runs you are using the update() method.

specify the start level
```
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").startLevel(10)
```
By using startLevel(<level>) the bundle will be started at the specified start level, in this example the start level of the bundle will be 10.

mavenConfiguration

Legacy option, not currently supported.

mockitoBundles

Containers: Native, Pax Runner

provisions a default version of Mockito and its dependencies.
```
mockitoBundles()
```

profile

Containers: Pax Runner

provision

Containers: Native, Pax Runner

Instead of using a URL, you can directly provision a bundle from an input stream. The stream content will be copied to the install area of the framework. This option is particularly useful in combination with Tinybundles.

provision a bundle from an input stream
```
provision(inputStream)
```

provision multiple bundles from input stream
```
provision(is1, is2, is3)
```

rawPaxRunnerOption

Containers: Pax Runner

Passes a String parameter as a command line argument to Pax Runner.

repositories

Containers: Pax Runner

repository

Containers: Pax Runner

scan

Containers: Pax Runner

scanBundle

Containers: Pax Runner

scanComposite

Containers: Pax Runner

scanDir

Containers: Pax Runner

scanFeatures

Containers: Pax Runner

scanFile

Containers: Pax Runner

scanPom

Containers: Pax Runner

serverMode

Containers: Pax Runner

systemPackage

Containers: Native, Pax Runner

Adds a package name to the org.osgi.framework.system.packages framework property.
```
systemPackage("javax.rmi")
```

systemPackages

Containers: Native, Pax Runner

Adds multiple package names to the org.osgi.framework.system.packages framework property.
```
systemPackages("javax.naming",
               "javax.rmi")
```

systemProperty

Containers: Native, Pax Runner

Sets a system property in the framework VM. For the Pax Runner Container, the property is set when the framework VM is started by the container. For the Native Container, this amounts to invoking System.setProperty() in the running VM, which may or may not have the same effect as a -Dkey=value VM argument for some properties defined in the JRE API.
```
systemProperty("org.osgi.service.http.port").value("8080")
```

many (one or more) system properties

systemProperty("org.osgi.service.http.port").value("8080"),
systemProperty("org.osgi.service.http.port.secure").value("8443")

systemTimeout

Containers: Native, Pax Runner

Specifies a timeout in milliseconds which is used by Pax Exam when waiting for a service to become available or for the framework to reach the requested start level

systemTimeout(5000)

The default value is 3 minutes.

url

Containers: Native, Pax Runner

A synonym for bundle().

vmOption

Containers: Pax Runner

Specifies an argument passed to the Java VM spawned by Pax Runner, e.g.

set the heap size

vmOption("-Xmx512M")
vmOption("-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005")

enable remote debugging

vmOption("-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005")

vmOptions

Containers: Pax Runner

set multiple VM options

vmOptions("-Xmx1G", "-XX:MaxPermSize=128M")

webProfile

Containers: Pax Runner

when

Containers: Native, Pax Runner

There might be cases when you have to use certain options only under specific conditions as for example you would like to enable debugging only when you set a system property. In order to fulfill such an requirement you can use optional composite option as in the following example:

@Configuration
public static Option[] configure()
{
    return options(
        when( Boolean.getBoolean( "isDebugEnabled" ) ).useOptions(
            vmOption( "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005" ),
            timeout( 0 )));
}

In the above example the vmOption and timeout options will be included only when there is a system property named isDebugEnabled with a value of true.

If you are using Maven you can then use the following to switch the debug options on:

mvn install -DisDebugEnabled=true

The condition is not limited to just system properties. You can use any expression that evaluates to a boolean or define your own condition.

workingDirectory

Containers: Native, Pax Runner

set the working directory for Pax Exam

workingDirectory("/home/hwellmann/pax-exam")

By default, Pax Exam will use a temporary directory created in ${java.io.tmpdir}.

wrappedBundle

Containers: Native, Pax Runner

In some cases you may have a standard JAR that you may need to make OSGi compatible in order to deploy it. You can do this on the fly by using the wrapping provisioning option that makes use of Wrap Protocol url protocol handler.

using a plain url of the jar to be wrapped

wrappedBundle("http://repo2.maven.org/maven2/javax/servlet/servlet-api/2.5/servlet-api-2.5.jar")

In this case the servlet api specified as a plain url will be downloaded and transformed into an OSGi bundle by adding the necessary metadata.

wrapping any another provision option

wrappedBundle(mavenBundle().groupId("javax.servlet").artifactId("servlet-api").version("2.5"))

In this case the same transformation will be applied but downloading (resolving the artifact) will use the maven option explained above.

The wrappedBundle() option supports a number of additional arguments which are specified in fluent API syntax, e.g.

wrappedBundle(mavenBundle("javax.servlet", "servlet-api","2.5")
    .bundleSymbolicName("javax.servlet.api")
    .bundleVersion("2.5")

Arguments

specify the Bundle-SymbolicName of the wrapped bundle
```
bundleSymbolicName(String)
```

specify the Bundle-Version of the wrapped bundle
```
bundleVersion(String)
```

specify exported packages
```
exports(String...)
```

specify imported packages
```
imports(String...)
```

specify bnd instructions
```
instructions(String...)
```

Examples

wrappedBundle(mavenBundle("junit", "junit-dep", "4.8.1")).exports("*;version=4.8.1"));