Configuration Options


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.

Not all options are supported by every container, in fact most options are for OSGi containers only.

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

Shared Default Configuration

To reuse the same configuration for all test classes in a suite and to avoid copying configuration methods, Pax Exam supports a ConfigurationFactory SPI.

If a test class does not have any @Configuration method, Pax Exam loads an implementation of the ConfigurationFactory interface (which must be unique) via the java.util.ServiceLoader and invokes the createConfiguation() method of this factory to obtain the configuration for the current test class.

Thus, to provide a default configuration of your test classes, create a class, e.g. com.example.MyConfigurationFactory, which implements org.ops4j.pax.exam.ConfigurationFactory, and a resource META-INF/services/org.ops4j.pax.exam.ConfigurationFactory containing the fully qualified class name of your configuration factory implementation.

Option Categories

Roughly speaking, options can be categorized into

  • provisioning options
  • property 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.

Option Overview

Option Details


Containers: Native, Forked

  • Adds a package name to the org.osgi.framework.bootdelegation framework property.



Containers: Native, Forked

  • Adds multiple package names to the org.osgi.framework.bootdelegation framework property.



Containers: Native, Forked

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

  • from http

  • from file



Containers: Native, Forked

  • clean the caches of downloaded and provisioned bundles when Pax Exam terminates

  • keep the caches


The last case is equivalent to keepCaches()


Containers: Native, Forked

  • 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("", "common", "1.0.0"),
            mavenBundle("", "util", "1.0.0"));


Containers: Native, Forked

  • Sets a framework property for the OSGi framework launched by the container. This is not in general equivalent to setting a system property of the same name.



Containers: Native, Forked

  • set the OSGi framework start level to a given value (a positive number).



Since: 3.5.0

Containers: All CDI containers.

Lets the user assemble a bean archive with well-defined classes and resources instead of simply using the test class path by default. This option has additional arguments which are documented on a separate page.


Containers: Native, Forked (see note on Karaf)

  • provisions a default version of JUnit and its dependencies.


The current version is org.ops4j.pax.tipi:org.ops4j.pax.tipi.junit: This is the original junit:junit:4.11 artifact repackaged as an OSGi bundle. The hamcrest-core dependency is also provisioned as an OSGi bundle.

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.

Karaf: Note that Karaf will by default provision default versions of JUnit and its dependencies unless KarafDistributionOption.overrideJUnitBundles() is used.


Containers: Native, Forked

  • keep the caches of downloaded and provisioned bundles, which are deleted by default when Pax Exam terminates


This is equivalent to cleanCaches(false).


Containers: Native, Forked

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

  • shortcut:

    maven("postgresql", "postgresql", "8.4-701.jdbc4")
  • reference the latest version of a non-OSGi Maven artifact in terms Maven groupId and artifactId

  • shortcut:

    maven("postgresql", "postgresql")


Containers: Native, Forked

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

  • a snapshot version

  • latest version (version not specified).


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

  • using a version range


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


    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


    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


    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.


Containers: All Java EE and Web containers

  • Deploys a web archive from a Maven repository to the web container, optionally setting the application name or web context root.

    mavenWar("org.ops4j.pax.exam.samples", "pax-exam-sample1-web", "3.0.0")
    mavenWar("org.ops4j.pax.exam.samples", "pax-exam-sample1-web", "3.0.0").name("pax-exam-sample1").contextRoot("sample1")


Containers: Forked

  • Propagates the value of a system property set in the driver VM to the framework VM started by the container.

  • Propagates multiple system properties

    propagateSystemProperties("org.osgi.service.http.port", "")


Containers: Native, Forked

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 multiple bundles from input stream

    provision(is1, is2, is3)


Containers: Forked


Containers: Forked


Containers: Native, Forked

  • Provisions a bundle from an input stream



Containers: Native, Forked

  • Adds a package name to the org.osgi.framework.system.packages framework property.



Containers: Native, Forked

  • Adds multiple package names to the org.osgi.framework.system.packages framework property.



Containers: Native, Forked

  • Sets a system property in the framework VM. For the Forked 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.

  • many (one or more) system properties



Containers: Native, Forked

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


The default value is 3 minutes.


Containers: Native, Forked

A synonym for bundle().


Containers: Forked

Specifies an argument passed to the Java VM spawned by Forked Container, e.g.

  • set the heap size

  • enable remote debugging



Containers: Forked

  • set multiple VM options

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


Containers: All Java EE and Web containers

  • Deploys a web archive to the web container, optionally setting the application name or web context root.



Containers: All Java EE and Web containers

  • Overrides Pax Exam's default conventions for constructing a WAR probe from the classpath, giving full control to the user. This option has a lot of arguments, which are documented on a separate page.


Containers: all

Enable a group of options only under specific conditions,  e.g. to enable debugging only when a system property has a given value.

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.


Containers: Native, Forked

  • set the working directory for Pax Exam


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


Containers: Native, Forked

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


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 other provisioning option


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")
  • specify the Bundle-SymbolicName of the wrapped bundle

  • specify the Bundle-Version of the wrapped bundle

  • specify exported packages

  • specify imported packages

  • specify bnd instructions

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