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 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

allFelixVersions

Containers: Pax Runner

allFrameworks

Containers: Pax Runner

allFrameworksVersions

Containers: Pax Runner

allKnopflerfishVersions

Containers: Pax Runner

autoWrap

Containers: Pax Runner

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

bootDelegationPackages

Containers: Native, Pax Runner

bundle

Containers: Native, Pax Runner

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

cleanCaches

Containers: Native, Pax Runner

cleanCaches(true)

The last case is equivalent to keepCaches()

compendiumProfile

Containers: Pax Runner

composite

Containers: Native, Pax Runner

configProfile

Containers: Pax Runner

customFramework

Containers: Pax Runner

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

equinox

Containers: Pax Runner

excludeDefaultRepositories

Containers: Pax Runner

felix

Containers: Pax Runner

frameworks

Containers: Pax Runner

frameworkStartLevel

Containers: Native, Pax Runner

jmockBundles

Containers: Native, Pax Runner

junitBundles

Containers: Native, Pax Runner

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

This is equivalent to cleanCaches(false).

knopflerfish

Containers: Pax Runner

localRepository

Containers: Pax Runner

logProfile

Containers: Pax Runner

maven

Containers: Native, Pax Runner

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.

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

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:

mavenConfiguration

Legacy option, not currently supported.

mockitoBundles

Containers: Native, Pax Runner

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.

rawPaxRunnerOption

Containers: 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

systemPackages

Containers: Native, Pax Runner

systemProperty

Containers: Native, Pax Runner

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.

vmOptions

Containers: Pax Runner

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

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.

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.

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
Examples
wrappedBundle(mavenBundle("junit", "junit-dep", "4.8.1")).exports("*;version=4.8.1"));